Skip to main content

​
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: 
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: 
go run . exec -message="Read main.go and explain how hrns boots."
You can override the saved defaults for that run: 
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

/model <model>
This updates the current provider’s saved default model in the config file.

​
List available models

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

​
Reset conversation

/new
This clears the accumulated conversation history.

​
List saved providers

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

​
Switch provider

/provider <name>
This saves currentProvider, rebuilds the OpenAI-compatible client, and keeps the current conversation history in memory.

​
List agents

/agents
This prints the registered agents.

​
Switch agent

/agent <agent>
This saves currentAgent and updates the active system message to that agent’s prompt.

​
Add a provider

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

​
Show help

/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: 
Read main.go and explain how hrns boots.

List the files in ./skills and summarize how skills are discovered.

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.