> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hrns.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# hrns

> A minimal Go harness for experimenting with tool-using AI agents and embedding them in your own code.

`hrns` is a small Go project that gives you the core pieces of an agent harness without hiding the mechanics:

* a streaming chat client for OpenAI-compatible `/chat/completions`
* an agent loop that can execute tool calls and continue the conversation
* a tiny TUI for manual testing plus a one-shot `exec` mode
* a lightweight skill loader that exposes prompt files as a tool

If you want to play with agents, inspect the moving parts, and then reuse the same pieces inside your own Go code, this repo is aimed at exactly that.

## What exists today

The current repo behavior is intentionally narrow:

* The binary starts an interactive TUI.
* The same binary also supports `hrns exec -message="..."` for single-run execution.
* The TUI creates a persisted provider config on first run.
* The TUI stores multiple named providers and builds an OpenAI-compatible client from the saved current provider.
* The TUI stores the current agent and composes its prompt with discovered skill metadata.
* Built-in tools cover file reads, basic file edits, directory globbing, shell commands, HTTP fetches, and skill loading.
* Skills are discovered from `~/.agents/skills` and `./.agents/skills`.

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run the bundled TUI, configure a provider, and send your first prompt.
  </Card>

  <Card title="Provider setup" icon="plug" href="/guides/provider-setup">
    Configure saved providers for any OpenAI-compatible endpoint.
  </Card>

  <Card title="Embed in Go" icon="code" href="/guides/embed-in-go">
    Build your own agent wrapper by composing `openai.Client`, `loop.Loop`, and your own tools.
  </Card>

  <Card title="Add a tool" icon="screwdriver-wrench" href="/guides/add-a-tool">
    Extend the loop with custom tool implementations and simple schemas.
  </Card>
</CardGroup>

## Mental model

The runtime flow is small enough to keep in your head:

1. `main.go` loads skills and agents, assembles the tool map, and starts the TUI.
2. The TUI loads provider and agent config, composes the system message with skill metadata, builds the client and loop, then collects user input and sends the conversation to `loop.RunLoop`.
3. `loop.RunLoop` streams assistant output, accumulates tool calls, executes tools, appends tool results, and re-prompts the model until no more tools are called.
4. Streamed chunks are printed back to the terminal as assistant text, reasoning text, or tool-call notices.

If you want the fuller breakdown, read the [architecture guide](/internals/architecture).