Skip to main content

​
What you need

  • Go installed locally
  • an OpenAI-compatible chat completion endpoint
  • a model name that your provider accepts

​
1. Install hrns

You can install the binary from a local checkout or directly from GitHub.

​
Install from source

From the repository root: 
go install .

​
Install from GitHub

go install github.com/mishankov/hrns@latest
This puts the hrns binary in your Go bin directory.

​
2. Start the TUI

If you installed the binary: 
hrns
If you are running from a checkout instead: 
go run .
On the first run, hrns checks for ~/.config/hrns/config.json. If the file does not exist, it starts interactive onboarding and asks for:
  • provider name
  • provider API URL
  • provider API key
  • default model
  • whether to skip TLS verification
The saved config is reused on later launches. On the first run, the session starts with onboarding prompts: 
config file not found, running onboarding now
Input new provider name:
> my-provider
Input provider API URL:
> https://your-provider.example/v1
Input provider API key:
> your-api-key
Input default model:
> your-model
Skip SSL verify? (y/n)
> n
After onboarding completes, the normal TUI banner appears: 
HRNS loop. dev
Provider: my-provider
Model: my-model
>

​
3. Adjust settings from inside the TUI

To change the saved model for the current provider: 
/model <your-model>
Other built-in commands:
  • /new resets the conversation history
  • /models lists models from the current provider’s /models endpoint
  • /model <model> updates the current provider’s saved default model
  • /providers lists saved providers
  • /provider <name> switches the active provider for this session and saves it as current
  • /agents lists registered agents
  • /agent <agent> switches the active agent prompt and saves it as current
  • /connect adds another provider to the config file
  • /help prints the command list
/connect saves a provider entry and updates currentProvider in the config file, but it does not rebuild the active client for the same session. If you want to start using the new provider right away, run /provider <name> after connecting it.

​
4. Send a prompt that can use tools

Try something that encourages tool use: 
List the Go files in this repository, then read main.go and summarize how the app boots.
When the model decides to call tools, the TUI prints tool-call notices inline. Assistant text and reasoning text stream as chunks.

​
5. Know the current defaults

The bundled app is intentionally opinionated and minimal:
  • The TUI supports registered agents and can save the current agent prompt when agents are provided.
  • Provider configuration is stored in ~/.config/hrns/config.json.
  • The TUI can store multiple named providers and switch between them with /provider <name>.
  • Skills are loaded automatically from the default roots if present and appended to the active system prompt as discoverable context.
  • There is also a one-shot mode for non-interactive runs:
hrns exec -message="Read main.go and summarize how hrns boots."
It uses the saved provider and agent config, starts with a fresh conversation, and exits after the run completes. You can override the default provider, model, or agent with -provider, -model, and -agent. If you pass -provider without -model, the run uses that provider’s saved default model. If you want control over those pieces, the usual path is to embed the packages in your own Go program. See Embed hrns in your Go code.