From 2812bfe5b9d799a107b019e0245ef5b1299e9041 Mon Sep 17 00:00:00 2001 From: Brooklyn Nicholson Date: Thu, 16 Apr 2026 19:29:18 -0500 Subject: [PATCH] docs(tui): add Ink TUI user guide + cross-link from CLI docs New primary guide at `user-guide/tui.md` covering launch, requirements, keybindings, slash commands, status line, configuration, sessions, and the revert path. Matches the voice of `user-guide/cli.md`. Cross-links: - `user-guide/cli.md`: tip callout pointing readers at the Ink TUI - `getting-started/quickstart.md`: shows both `hermes` and `hermes --tui` under "Start Chatting" so first-run users know they have the choice - `reference/environment-variables.md`: new "Interface" section with `HERMES_TUI` and `HERMES_TUI_DIR` - `reference/cli-commands.md`: `--tui` and `--dev` added to global options Sidebar: `user-guide/tui` slotted right after `user-guide/cli`. --- website/docs/getting-started/quickstart.md | 7 +- website/docs/reference/cli-commands.md | 2 + .../docs/reference/environment-variables.md | 7 + website/docs/user-guide/cli.md | 4 + website/docs/user-guide/tui.md | 142 ++++++++++++++++++ website/sidebars.ts | 1 + 6 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 website/docs/user-guide/tui.md diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index 880c01cb2..997b0acf3 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -77,11 +77,16 @@ You can switch providers at any time with `hermes model` — no code changes, no ## 3. Start Chatting ```bash -hermes +hermes # classic CLI +hermes --tui # modern Ink TUI (recommended) ``` That's it! You'll see a welcome banner with your model, available tools, and skills. Type a message and press Enter. +:::tip Pick your interface +Hermes ships with two terminal interfaces: the classic `prompt_toolkit` CLI and a newer [Ink TUI](../user-guide/tui.md) with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config — try each with `hermes` vs `hermes --tui`. +::: + ``` ❯ What can you help me with? ``` diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index fb93cf648..f88cd12bc 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -27,6 +27,8 @@ hermes [global-options] [subcommand/options] | `--worktree`, `-w` | Start in an isolated git worktree for parallel-agent workflows. | | `--yolo` | Bypass dangerous-command approval prompts. | | `--pass-session-id` | Include the session ID in the agent's system prompt. | +| `--tui` | Launch the [Ink TUI](../user-guide/tui.md) instead of the classic CLI. Equivalent to `HERMES_TUI=1`. | +| `--dev` | With `--tui`: run the TypeScript sources directly via `tsx` instead of the prebuilt bundle (for TUI contributors). | ## Top-level commands diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 63844b3f9..92ac45b5c 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -342,6 +342,13 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `HERMES_BACKGROUND_NOTIFICATIONS` | Background process notification mode in gateway: `all` (default), `result`, `error`, `off` | | `HERMES_EPHEMERAL_SYSTEM_PROMPT` | Ephemeral system prompt injected at API-call time (never persisted to sessions) | +## Interface + +| Variable | Description | +|----------|-------------| +| `HERMES_TUI` | Launch the [Ink TUI](../user-guide/tui.md) instead of the classic CLI when set to `1`. Equivalent to passing `--tui`. | +| `HERMES_TUI_DIR` | Path to a prebuilt `ui-tui/` directory (must contain `dist/entry.js` and populated `node_modules`). Used by distros and Nix to skip the first-launch `npm install`. | + ## Cron Scheduler | Variable | Description | diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md index 43d12611f..e8201d592 100644 --- a/website/docs/user-guide/cli.md +++ b/website/docs/user-guide/cli.md @@ -8,6 +8,10 @@ description: "Master the Hermes Agent terminal interface — commands, keybindin Hermes Agent's CLI is a full terminal user interface (TUI) — not a web UI. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. Built for people who live in the terminal. +:::tip +Hermes also ships a modern Node-based terminal UI with modal overlays, mouse selection, and non-blocking input. Launch it with `hermes --tui` — see the [Ink TUI](tui.md) guide. +::: + ## Running the CLI ```bash diff --git a/website/docs/user-guide/tui.md b/website/docs/user-guide/tui.md new file mode 100644 index 000000000..d79116ae5 --- /dev/null +++ b/website/docs/user-guide/tui.md @@ -0,0 +1,142 @@ +--- +sidebar_position: 2 +title: "Ink TUI" +description: "Launch the modern Node-based terminal UI for Hermes — mouse-friendly, rich overlays, and non-blocking input." +--- + +# Ink TUI + +The Ink TUI is the modern front-end for Hermes — a Node/React 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 Ink TUI +hermes --tui + +# Resume the latest Ink 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 Ink 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 Ink TUI identically. + +## Why the Ink 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, image paste from the clipboard (`Alt+V`), bracketed-paste safety. + +Same [skins](features/skins.md) and [personalities](features/personality.md) apply. Switch mid-session with `/skin ares`, `/personality pirate`, `/theme daylight`, and the UI repaints live. + +## 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. +- **`Ctrl+V`** pastes text from your clipboard directly into the composer; multi-line pastes stay on one row until you expand them. +- **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 in the transcript | +| `/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: compact # or "verbose" — default tool-call detail level + mouse_tracking: true # disable if your terminal conflicts with mouse reporting +``` + +`/details on` / `/details off` / `/details cycle` toggle this at runtime. + +## Sessions + +Sessions are shared between the Ink 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 diff --git a/website/sidebars.ts b/website/sidebars.ts index b1f7fcf59..c84184c4e 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -21,6 +21,7 @@ const sidebars: SidebarsConfig = { collapsed: true, items: [ 'user-guide/cli', + 'user-guide/tui', 'user-guide/configuration', 'user-guide/sessions', 'user-guide/profiles',