hermes-agent/website/docs/user-guide/tui.md

sidebar_position	title	description
2	TUI	Launch the modern terminal UI for Hermes — mouse-friendly, rich overlays, and non-blocking input.

TUI

The TUI is the modern front-end for Hermes — a terminal UI backed by the same Python runtime as the Classic CLI. Same agent, same sessions, same slash commands; a cleaner, more responsive surface for interacting with them.

It's the recommended way to run Hermes interactively.

Launch

# Launch the TUI
hermes --tui

# Resume the latest TUI session (falls back to the latest classic session)
hermes --tui -c
hermes --tui --continue

# Resume a specific session by ID or title
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"

# Run source directly — skips the prebuild step (for TUI contributors)
hermes --tui --dev

You can also enable it via env var:

export HERMES_TUI=1
hermes          # now uses the TUI
hermes chat     # same

Or make it the persistent default in ~/.hermes/config.yaml:

display:
  interface: tui   # "cli" (default) or "tui"

With display.interface: tui, a bare hermes (and hermes chat) launches the TUI. Explicit flags always win — run hermes --cli to drop back to the classic REPL for a single invocation, or hermes --tui / HERMES_TUI=1 to force the TUI when the config default is cli.

The classic CLI remains the shipped default. Anything documented in CLI Interface — slash commands, quick commands, skill preloading, personalities, multi-line input, interrupts — works in the TUI identically.

Why the TUI

• Instant first frame — the banner paints before the app finishes loading, so the terminal never feels frozen while Hermes is starting.
• Non-blocking input — type and queue messages before the session is ready. Your first prompt sends the moment the agent comes online.
• Rich overlays — model picker, session picker, approval and clarification prompts all render as modal panels rather than inline flows.
• Live session panel — tools and skills fill in progressively as they initialize.
• Mouse-friendly selection — drag to highlight with a uniform background instead of SGR inverse. Copy with your terminal's normal copy gesture.
• Alternate-screen rendering — differential updates mean no flicker when streaming, no scrollback clutter after you quit.
• Composer affordances — inline paste-collapse for long snippets, Cmd+V / Ctrl+V text paste with clipboard-image fallback, bracketed-paste safety, and image/file-path attachment normalization.

Same skins and personalities apply. Switch mid-session with /skin ares, /personality pirate, and the UI repaints live. See Skins & Themes for the full list of customizable keys and which ones apply to classic vs TUI — the TUI honors the banner palette, UI colors, prompt glyph/color, session display, completion menu, selection bg, tool_prefix, and help_header.

Collapsible banner sections

The TUI startup banner groups runtime info into four collapsible sections, each rendered with a ▸ / ▾ chevron next to the section title:

Section	Default state
Tools	Open
Skills	Collapsed
System Prompt	Collapsed
MCP Servers	Collapsed

Click anywhere on a section header (or its chevron) to toggle it. The Tools list opens by default because it's the most-checked section at session start; Skills, System Prompt, and MCP Servers collapse by default so the banner stays compact even when you've installed dozens of skills or wired up many MCP servers. State is local to the banner instance, so the next launch resets to the defaults.

Requirements

• Node.js ≥ 20 — the TUI runs as a subprocess launched from the Python CLI. hermes doctor verifies this.
• TTY — like the classic CLI, piping stdin or running in non-interactive environments falls back to single-query mode.

On first launch Hermes installs the TUI's Node dependencies into ui-tui/node_modules (one-time, a few seconds). Subsequent launches are fast. If you pull a new Hermes version, the TUI bundle is rebuilt automatically when sources are newer than the dist.

External prebuild

Distributions that ship a prebuilt bundle (Nix, system packages) can point Hermes at it:

export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui

The directory must contain dist/entry.js.

Keybindings

Keybindings match the Classic CLI exactly. The only behavioral differences:

• Mouse drag highlights text with a uniform selection background.
• Cmd+V / Ctrl+V first tries normal text paste, then falls back to OSC52/native clipboard reads, and finally image attach when the clipboard or pasted payload resolves to an image.
• /terminal-setup installs local VS Code / Cursor / Windsurf terminal bindings for better Cmd+Enter and undo/redo parity on macOS.
• Slash autocompletion opens as a floating panel with descriptions, not an inline dropdown.
• Ctrl+X opens the live session switcher. When a queued message is highlighted (sent while the agent was still running), it still deletes that queued message instead. Esc cancels editing and unhighlights without deleting.
• Ctrl+G / Ctrl+X Ctrl+E — open the current input buffer in $EDITOR for multi-line / long-prompt composition; save-and-exit sends the contents back as the prompt.

Slash commands

All slash commands work unchanged. A few are TUI-owned — they produce richer output or render as overlays rather than inline panels:

Command	TUI behavior
/help	Overlay with categorized commands, arrow-key navigable
/sessions (alias /switch)	Live session switcher — list open TUI sessions, switch between them, close them, or start another one
/model	Modal model picker grouped by provider, with cost hints
/skin	Live preview — theme change applies as you browse
/details	Toggle verbose tool-call details (global or per-section)
/usage	Rich token / cost / context panel
/agents (alias /tasks)	Observability overlay — live subagent tree with kill/pause controls, per-branch cost / token / file rollups, turn-by-turn history
/reload	Re-reads ~/.hermes/.env into the running TUI process so newly added API keys take effect without a restart
/mouse [on|off|toggle|wheel|buttons|all]	Pick a mouse tracking preset at runtime (also persists to display.mouse_tracking in config.yaml). wheel (1000+1006) keeps scroll-wheel scrolling without the hover events that make tmux spam "No image in clipboard" over the prompt row; buttons adds drag-to-select; all is the default with hover-driven UI.

Every other slash command (including installed skills, quick commands, and personality toggles) works identically to the classic CLI. See Slash Commands Reference.

Live session switcher

Use the live session switcher when you want one terminal to act as a dispatcher for several TUI sessions. It lists only sessions that are currently live in this TUI process; closed sessions remain saved transcripts and can still be reopened with /resume or hermes --tui --resume <id-or-title>.

Open it with any of these:

• Ctrl+X from the TUI.
• /sessions or /switch.
• /sessions new to create a fresh live session immediately.
• Click the N live sessions count in the status line.