Skip to main content

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