> ## 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.

# Package reference: tui

> The terminal runner used by the bundled hrns binary.

## Purpose

The `tui` package is a thin terminal wrapper around `loop.Loop` with a small persisted provider config. It supports an interactive shell and a one-shot `exec` mode.

## Main entrypoints

### `tui.New(opts ...Option)`

Constructs a `TUIApp` with registered tools, agents, and built-in slash commands.

Useful option helpers:

* `tui.WithTool(name, tool)`
* `tui.WithTools(map[string]loop.Tool)`
* `tui.WithAgent(agent.Agent)`
* `tui.WithAgents([]agent.Agent)`
* `tui.WithSkills([]skills.Skill)`
* `tui.WithSystemPrompt(string)`

### `(*TUIApp).Run(ctx)`

Starts the bundled runner:

* loads `~/.config/hrns/config.json`
* runs onboarding if the config file is missing or empty
* selects the saved current agent, repairs a stale saved agent, or saves one registered agent as current
* composes the system message from the selected agent or base prompt plus discovered skill metadata
* builds `openai.Client` for the current provider
* constructs `loop.Loop` from the current client and registered tools
* detects interactive mode by default or `exec` mode when the first CLI argument is `exec`
* in interactive mode, prints the banner, reads stdin, handles slash commands, runs the loop, and stores message history
* in `exec` mode, parses `-message`, `-provider`, `-model`, and `-agent`, runs one turn, streams chunks, and exits

## Slash commands

The package currently handles:

* `/new`
* `/models`
* `/model <model>`
* `/providers`
* `/provider <name>`
* `/agents`
* `/agent <agent>`
* `/connect`
* `/help`

Commands are registered with usage text, descriptions, and handler methods; `/help` is rendered from that registry. Model changes are persisted to the config file. `/provider <name>` also persists `currentProvider` and rebuilds the in-memory client. `/connect` saves a new provider entry and updates `currentProvider`, but it does not switch the live client by itself. `/agent <agent>` persists `currentAgent` and resets the active system message to that agent's prompt.

## Exec flags

When the bundled binary is invoked as `hrns exec`, the package accepts:

* `-message` for the one user prompt to run
* `-provider` to choose a saved provider for that run
* `-model` to override the model used for the one-shot run
* `-agent` to choose a registered agent prompt for that run

When `-provider` is supplied without `-model`, `exec` uses the selected provider's saved default model.

## Rendering behavior

The package uses `github.com/fatih/color` for simple terminal coloring.

It renders:

* harness messages in blue
* errors in red
* tool names in red with yellow arguments
* reasoning text in gray

Assistant response text is printed with the default color settings.

## Relationship to the rest of hrns

The bundled runner is the easiest way to try the loop, but it is not the core abstraction. If you want a web UI, service, editor integration, or a richer batch runner, you usually replace `tui` rather than extend it.