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

# TUI workflow

> Use the bundled terminal interface to probe prompts, tools, and model behavior.

## What the TUI is for

The bundled runner is the fastest way to poke at the loop without writing extra code. In interactive mode it is useful for:

* trying prompts
* watching streamed output
* seeing when tool calls happen
* checking that your saved provider configuration works

It is not a general CLI framework. Today it is a small interactive shell plus a simple one-shot `exec` path around `loop.RunLoop`.

## Starting a session

Run:

```bash theme={null}
go run .
```

On first run, the app launches onboarding and writes `~/.config/hrns/config.json`. After that, it prints the active provider and model and waits for input.

## Running a one-shot prompt

Use `exec` when you want one prompt, streamed output, and then process exit:

```bash theme={null}
go run . exec -message="Read main.go and explain how hrns boots."
```

You can override the saved defaults for that run:

```bash theme={null}
go run . exec -provider "my-provider" -model my-model -message="List the Go packages in this repo."
```

`exec` still loads the same saved config and still requires first-run onboarding to have happened already. Unlike the interactive mode, it does not preserve conversation history across runs. You can also pass `-agent`; if you pass `-provider` without `-model`, the selected provider's saved default model is used.

## Built-in commands

### Change model

```text theme={null}
/model <model>
```

This updates the current provider's saved default model in the config file.

### List available models

```text theme={null}
/models
```

This sends `GET /models` to the current provider and prints the returned model IDs.

### Reset conversation

```text theme={null}
/new
```

This clears the accumulated conversation history.

### List saved providers

```text theme={null}
/providers
```

This prints the names of providers stored in the config file.

### Switch provider

```text theme={null}
/provider <name>
```

This saves `currentProvider`, rebuilds the OpenAI-compatible client, and keeps the current conversation history in memory.

### List agents

```text theme={null}
/agents
```

This prints the registered agents.

### Switch agent

```text theme={null}
/agent <agent>
```

This saves `currentAgent` and updates the active system message to that agent's prompt.

### Add a provider

```text theme={null}
/connect
```

This runs the same prompt sequence as first-run onboarding and saves another provider entry.

### Show help

```text theme={null}
/help
```

This prints the registered command list.

## What gets streamed back

The loop emits chunk types and the TUI renders them differently:

* assistant text chunks
* reasoning chunks
* tool call start notifications
* error chunks

Tool-call results are used to continue the conversation, but the current TUI does not print the raw tool result body back to the screen as a separate visible block.

## Session behavior

The TUI keeps a `messages` slice in memory and appends your prompts plus assistant/tool messages after each turn. That means later prompts in the same session include earlier context unless you run `/new`.

Provider state is slightly different:

* the provider client is built once when the TUI starts
* `/model` persists a new model value for the current provider
* `/provider <name>` rebuilds the client and updates the active model for the session
* `/agent <agent>` persists the selected agent and updates the active system message
* `/connect` saves another provider and updates `currentProvider` in the config file, but the active session keeps using the existing client until you run `/provider <name>` or restart

## Good prompts for exploration

Use prompts that make the model inspect the repo:

```text theme={null}
Read main.go and explain how hrns boots.
```

```text theme={null}
List the files in ./skills and summarize how skills are discovered.
```

```text theme={null}
Fetch https://example.com and tell me what came back.
```

## Known limits

* `/connect` alone does not switch the live client.
* `/model` expects an argument.
* `/agent` expects an argument.

For anything beyond quick experiments, build your own entrypoint on top of the packages instead of stretching the TUI too far.