Wiki · Features in depth
TUI — working in the terminal
The most comfortable way to reach an agent on a server: a live view of running work, a status line and conversations you can resume after a dropped connection.
⌨️
The TUI is a terminal interface for the same agent.
Same conversations, same slash commands as before — with a cleaner layout, a status line and a
live view of work in progress. On a server it is the most comfortable way to work.
Launch
❯ hermes --tui # open the TUI
❯ hermes --tui -c # resume the latest conversation
❯ hermes --tui --resume latest # the same, spelled out
❯ hermes --tui -r 20260409_000000_aa11bb # by session id
❯ hermes --tui --resume "my project" # by session title
You can make it permanent — with an environment variable or in the settings. An explicit flag
always wins (to drop back to the classic REPL for one run: hermes --cli):
# for this shell only
❯ export HERMES_TUI=1
# or permanently in ~/.hermes/config.yaml
display:
interface: tui
Why use it
| Benefit | What it means in practice |
|---|---|
| Instant first frame | The banner paints before everything finishes loading — the terminal never feels stuck |
| A live view of work | You see how many helpers are running and which background processes the agent started |
| A status line | Says what the agent is doing (ready, thinking…, running…) and the session title |
| Richer slash commands | Some commands render a navigable panel or picker in the TUI instead of plain text |
Slash commands that look better in the TUI
| Command | What it does |
|---|---|
/help | Commands grouped by category, navigable with arrow keys |
/sessions (or /switch) | Live session switcher — switch, close or open one |
/model | Model picker grouped by provider, with cost hints |
/usage | Tokens, cost and context usage panel |
/agents (or /tasks) | Tree of running helpers with per-branch cost and stop controls |
/details | Verbose tool-call details (globally or per section) |
/skin | Theme change with a live preview |
/reload | Re-reads ~/.hermes/.env so new keys work without a restart |
/mouse | Mouse tracking preset (see the tmux pitfall below) |
Keys
| Key | What it does |
|---|---|
Ctrl+T | Expands the live work dock to full height (helpers and processes) |
Ctrl+R | Toggles the dock between detailed and a single summary line |
Enter or t | Opens the live transcript of the selected helper |
d / e / x | Details / steer it / stop it |
On macOS the function key F7 (a fallback binding for Ctrl+R
in some terminals) may not be forwarded — MacBooks use that row for system controls. Hold
Fn (the globe key) or just use Ctrl+R.
When the connection drops
Over SSH the link sometimes breaks. You can make the TUI re-attach to your last conversation on launch:
❯ export HERMES_TUI_RESUME=1 # always resume the most recent TUI session
❯ export HERMES_TUI_RESUME=<id> # or a specific one
Pitfalls from our systems
| What happened | What to do |
|---|---|
| Inside tmux the prompt row kept showing "No image in clipboard" | Mouse tracking sent events tmux did not understand. The /mouse wheel preset fixed it (scrolling works, hover events are off) |
| On a small terminal there was little room to type | The dock fits the terminal height; Ctrl+R collapses it to one line, or use a separate terminal window |
| A command died with a Python error although the system was fine | System tools launched from an environment carrying its own Python inherit library paths. Running them with a clean environment (env -u PYTHONPATH) fixes it |
| After editing settings nothing changed | A new key in .env applies after /reload; what is in config.yaml is read when a session starts |
| I switched to the TUI and could not get back | hermes --cli for one run, or change display.interface in the settings |
Our tips
| Tip | Why |
|---|---|
Name your sessions (/title) | The switcher and resume become far easier to use |
| Run long jobs in the background | The TUI shows what is running while you give it the next task |
| On a server, use tmux or screen | If the connection drops, your work and the agent keep running |
| Watch the status line | thinking… means the agent is working — no need to ask "so, how is it going?" |