bot/docs/web/tui.md

summary, read_when, title

summary	read_when	title
Terminal UI (TUI): connect to the Gateway from any machine	You want a beginner-friendly walkthrough of the TUI You need the complete list of TUI features, commands, and shortcuts	TUI

TUI (Terminal UI)

Quick start

1. Start the Gateway.

hanzo-bot gateway

2. Open the TUI.

hanzo-bot tui

3. Type a message and press Enter.

Remote Gateway:

hanzo-bot tui --url ws://<host>:<port> --token <gateway-token>

Use --password if your Gateway uses password auth.

What you see

• Header: connection URL, current agent, current session.
• Chat log: user messages, assistant replies, system notices, tool cards.
• Status line: connection/run state (connecting, running, streaming, idle, error).
• Footer: connection state + agent + session + model + think/verbose/reasoning + token counts + deliver.
• Input: text editor with autocomplete.

Mental model: agents + sessions

• Agents are unique slugs (e.g. main, research). The Gateway exposes the list.
• Sessions belong to the current agent.
• Session keys are stored as agent:<agentId>:<sessionKey>.
  • If you type /session main, the TUI expands it to agent:<currentAgent>:main.
  • If you type /session agent:other:main, you switch to that agent session explicitly.
• Session scope:
  • per-sender (default): each agent has many sessions.
  • global: the TUI always uses the global session (the picker may be empty).
• The current agent + session are always visible in the footer.

Sending + delivery

• Messages are sent to the Gateway; delivery to providers is off by default.
• Turn delivery on:
  • /deliver on
  • or the Settings panel
  • or start with hanzo-bot tui --deliver

Pickers + overlays

• Model picker: list available models and set the session override.
• Agent picker: choose a different agent.
• Session picker: shows only sessions for the current agent.
• Settings: toggle deliver, tool output expansion, and thinking visibility.

Keyboard shortcuts

• Enter: send message
• Esc: abort active run
• Ctrl+C: clear input (press twice to exit)
• Ctrl+D: exit
• Ctrl+L: model picker
• Ctrl+G: agent picker
• Ctrl+P: session picker
• Ctrl+O: toggle tool output expansion
• Ctrl+T: toggle thinking visibility (reloads history)

Slash commands

Core:

• /help
• /status
• /agent <id> (or /agents)
• /session <key> (or /sessions)
• /model <provider/model> (or /models)

Session controls:

• /think <off|minimal|low|medium|high>
• /verbose <on|full|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /elevated <on|off|ask|full> (alias: /elev)
• /activation <mention|always>
• /deliver <on|off>

Session lifecycle:

• /new or /reset (reset the session)
• /abort (abort the active run)
• /settings
• /exit

Other Gateway slash commands (for example, /context) are forwarded to the Gateway and shown as system output. See Slash commands.

Local shell commands

• Prefix a line with ! to run a local shell command on the TUI host.
• The TUI prompts once per session to allow local execution; declining keeps ! disabled for the session.
• Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent cd/env).
• Local shell commands receive BOT_SHELL=tui-local in their environment.
• A lone ! is sent as a normal message; leading spaces do not trigger local exec.

Tool output

• Tool calls show as cards with args + results.
• Ctrl+O toggles between collapsed/expanded views.
• While tools run, partial updates stream into the same card.

History + streaming

• On connect, the TUI loads the latest history (default 200 messages).
• Streaming responses update in place until finalized.
• The TUI also listens to agent tool events for richer tool cards.

Connection details

• The TUI registers with the Gateway as mode: "tui".
• Reconnects show a system message; event gaps are surfaced in the log.

Options

• --url <url>: Gateway WebSocket URL (defaults to config or ws://127.0.0.1:<port>)
• --token <token>: Gateway token (if required)
• --password <password>: Gateway password (if required)
• --session <key>: Session key (default: main, or global when scope is global)
• --deliver: Deliver assistant replies to the provider (default off)
• --thinking <level>: Override thinking level for sends
• --timeout-ms <ms>: Agent timeout in ms (defaults to agents.defaults.timeoutSeconds)

Note: when you set --url, the TUI does not fall back to config or environment credentials. Pass --token or --password explicitly. Missing explicit credentials is an error.

Troubleshooting

No output after sending a message:

• Run /status in the TUI to confirm the Gateway is connected and idle/busy.
• Check the Gateway logs: hanzo-bot logs --follow.
• Confirm the agent can run: hanzo-bot status and hanzo-bot models status.
• If you expect messages in a chat channel, enable delivery (/deliver on or --deliver).
• --history-limit <n>: History entries to load (default 200)

Connection troubleshooting

• disconnected: ensure the Gateway is running and your --url/--token/--password are correct.
• No agents in picker: check hanzo-bot agents list and your routing config.
• Empty session picker: you might be in global scope or have no sessions yet.