mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
78481ac124
Adds optional per-section overrides on top of the existing global
details_mode (hidden | collapsed | expanded). Lets users keep the
accordion collapsed by default while auto-expanding tools, or hide the
activity panel entirely without touching thinking/tools/subagents.
Config (~/.hermes/config.yaml):
display:
details_mode: collapsed
sections:
thinking: expanded
tools: expanded
activity: hidden
Slash command:
/details show current global + overrides
/details [hidden|collapsed|expanded] set global mode (existing)
/details <section> <mode|reset> per-section override (new)
/details <section> reset clear override
Sections: thinking, tools, subagents, activity.
Implementation:
- ui-tui/src/types.ts SectionName + SectionVisibility
- ui-tui/src/domain/details.ts parseSectionMode / resolveSections /
sectionMode + SECTION_NAMES
- ui-tui/src/app/uiStore.ts +
app/interfaces.ts +
app/useConfigSync.ts sections threaded into UiState
- ui-tui/src/components/
thinking.tsx ToolTrail consults per-section mode for
hidden/expanded behaviour; expandAll
skips hidden sections; floating-alert
fallback respects activity:hidden
- ui-tui/src/components/
messageLine.tsx + appLayout.tsx pass sections through render tree
- ui-tui/src/app/slash/
commands/core.ts /details <section> <mode|reset> syntax
- tui_gateway/server.py config.set details_mode.<section>
writes to display.sections.<section>
(empty value clears the override)
- website/docs/user-guide/tui.md documented
Tests: 14 new (4 domain, 4 useConfigSync, 3 slash, 3 gateway).
Total: 269/269 vitest, all gateway tests pass.
156 lines
7.7 KiB
Markdown
156 lines
7.7 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
title: "TUI"
|
|
description: "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](cli.md). 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
export HERMES_TUI=1
|
|
hermes # now uses the TUI
|
|
hermes chat # same
|
|
```
|
|
|
|
The classic CLI remains available as the default. Anything documented in [CLI Interface](cli.md) — 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](features/skins.md) and [personalities](features/personality.md) apply. Switch mid-session with `/skin ares`, `/personality pirate`, and the UI repaints live. See [Skins & Themes](features/skins.md) 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`.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
|
|
hermes --tui
|
|
```
|
|
|
|
The directory must contain `dist/entry.js` and an up-to-date `node_modules`.
|
|
|
|
## Keybindings
|
|
|
|
Keybindings match the [Classic CLI](cli.md#keybindings) 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.
|
|
|
|
## 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` | Modal session picker — preview, title, token totals, resume inline |
|
|
| `/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 |
|
|
|
|
Every other slash command (including installed skills, quick commands, and personality toggles) works identically to the classic CLI. See [Slash Commands Reference](../reference/slash-commands.md).
|
|
|
|
## Status line
|
|
|
|
The TUI's status line tracks agent state in real time:
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `starting agent…` | Session ID is live; tools and skills still coming online. You can type — messages queue and send when ready. |
|
|
| `ready` | Agent is idle, accepting input. |
|
|
| `thinking…` / `running…` | Agent is reasoning or running a tool. |
|
|
| `interrupted` | Current turn was cancelled; press Enter to send again. |
|
|
| `forging session…` / `resuming…` | Initial connect or `--resume` handshake. |
|
|
|
|
The per-skin status-bar colors and thresholds are shared with the classic CLI — see [Skins](features/skins.md) for customization.
|
|
|
|
## Configuration
|
|
|
|
The TUI respects all standard Hermes config: `~/.hermes/config.yaml`, profiles, personalities, skins, quick commands, credential pools, memory providers, tool/skill enablement. No TUI-specific config file exists.
|
|
|
|
A handful of keys tune the TUI surface specifically:
|
|
|
|
```yaml
|
|
display:
|
|
skin: default # any built-in or custom skin
|
|
personality: helpful
|
|
details_mode: collapsed # hidden | collapsed | expanded — global accordion default
|
|
sections: # optional: per-section overrides (any subset)
|
|
thinking: expanded # always open
|
|
tools: expanded # always open
|
|
activity: hidden # never show errors/warnings/info panel
|
|
mouse_tracking: true # disable if your terminal conflicts with mouse reporting
|
|
```
|
|
|
|
Runtime toggles:
|
|
|
|
- `/details [hidden|collapsed|expanded|cycle]` — set the global mode
|
|
- `/details <section> [hidden|collapsed|expanded|reset]` — override one section
|
|
(sections: `thinking`, `tools`, `subagents`, `activity`)
|
|
|
|
Per-section overrides take precedence over the global `details_mode`. With
|
|
`activity: hidden`, errors/warnings are suppressed entirely (the floating-alert
|
|
fallback that normally surfaces under `details_mode: hidden` is also silenced
|
|
when activity is explicitly hidden).
|
|
|
|
## Sessions
|
|
|
|
Sessions are shared between the TUI and the classic CLI — both write to the same `~/.hermes/state.db`. You can start a session in one, resume in the other. The session picker surfaces sessions from both sources, with a source tag.
|
|
|
|
See [Sessions](sessions.md) for lifecycle, search, compression, and export.
|
|
|
|
## Reverting to the classic CLI
|
|
|
|
Launching `hermes` (without `--tui`) stays on the classic CLI. To make a machine prefer the TUI, set `HERMES_TUI=1` in your shell profile. To go back, unset it.
|
|
|
|
If the TUI fails to launch (no Node, missing bundle, TTY issue), Hermes prints a diagnostic and falls back — rather than leaving you stuck.
|
|
|
|
## See also
|
|
|
|
- [CLI Interface](cli.md) — full slash command and keybinding reference (shared)
|
|
- [Sessions](sessions.md) — resume, branch, and history
|
|
- [Skins & Themes](features/skins.md) — theme the banner, status bar, and overlays
|
|
- [Voice Mode](features/voice-mode.md) — works in both interfaces
|
|
- [Configuration](configuration.md) — all config keys
|