mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
* refactor(desktop): split clarify-tool.tsx into a clarify/ folder
Pure moves, no behaviour change. Parsing, the question-card core
(shell, choice rows, question block), the delivery watchdog, and each
pending/settled card get their own file so the core can be reused.
* feat(clarify): one questions[] shape with per-question status and one outcome
The clarify tool now takes only questions=[{question, choices?, multi_select?}].
A wrong shape is a tool error that names the right one, so a model that
sends the old top-level question/choices corrects itself on the next call.
Every result has the same shape on every surface: each response carries
status (answered, skipped, unanswered) with user_response null unless
answered, and the result carries one outcome (submitted, cancelled,
timed_out, undelivered) plus an optional surface-written notice. The
timeout and cancel sentences that used to pose as the user's answer are
gone, and the compressor reads status instead of matching their prefixes.
The callback contract is callback(questions) -> {answers, outcome, notice?}
(None = skipped, missing qid = unanswered). tui_gateway settles a batch the
same way for the last lock, a cancel, an interrupt and the deadline, and
clarify.lock keeps a null answer as a skip. A multi-select answer that is
not a JSON array counts as one typed ("Other") answer. The tool-row preview
reads the first question.
* feat(clarify): every surface asks through the one question card
CLI: the batch panel is the only panel; Enter on an empty field skips a
question, Ctrl+C cancels and keeps the locked answers, the deadline returns
timed_out. -q and -z return undelivered with a no-user notice.
Ink TUI: the single-question prompt is gone; the card supports multi-select
(Space or a digit toggles, Enter locks, typed Other text joins the picks),
an empty submit skips, Esc cancels, and "Batch" names are dropped.
Desktop: the single-question card is deleted and its keyboard handling moved
into the one card (arrows, letters and digits, auto-advance, Enter picks then
confirms). Confirm enables at one answer; blank questions lock null; Skip and
a composer message cancel; the settled card shows No answer for unanswered
questions. The bots room card follows the same contract.
Messaging: one card per question with a "Reply skip to skip" line in every
locale; timeouts and delivery failures map to timed_out and undelivered.
* fix(clarify): cancelled for a released messaging card, labels win over the skip word
A prose reply to a messaging choice card, /new and session end released
the wait with "", which read as timed_out. They now resolve with a
CANCELLED marker and the tool gets outcome cancelled.
A typed reply that matches a choice label ("Skip") now resolves to that
choice; the skip word applies only when no choice matches.
The bots room card sends the picked labels as they are; the tool already
strips the recommendation label. Unused OUTCOMES and a new docstring and
comment are removed.
* fix(tui): re-editing a multi-select answer keeps its picks
The Ink card stored a multi-select answer as display text ("A, B"), so
revisiting the question put the whole string into Other and re-locked it
as one item. The answers map now keeps the raw JSON array, the card
restores the picks on revisit, and only the display lines format it.
Comments that earlier edits reworded are restored to their original
words, minus the phrases the change made wrong. The compute-host clarify
lock accepts None for a skipped question.
* test(clarify): align three checks with the one-answer confirm and the regenerated keys
The desktop Cmd+Enter test now expects a send with one answer (the blank
question locks null), the compressor test expects the single-answer summary
the code gives, and locales/_keys.desktop.json is regenerated for the
removed and added clarify strings.
* test(tui): the one-question card header is singular
515 lines
32 KiB
Markdown
515 lines
32 KiB
Markdown
# Hermes TUI
|
|
|
|
React + Ink terminal UI for Hermes. TypeScript owns the screen. Python owns sessions, tools, model calls, and most command logic.
|
|
|
|
```bash
|
|
hermes --tui
|
|
```
|
|
|
|
## What runs
|
|
|
|
The client entrypoint is `src/entry.tsx`. It exits early if `stdin` is not a TTY, starts `GatewayClient`, then renders `App`.
|
|
|
|
`GatewayClient` spawns:
|
|
|
|
```text
|
|
python -m tui_gateway.entry
|
|
```
|
|
|
|
Interpreter resolution uses `HERMES_PYTHON`, supplied by the CLI launcher or
|
|
Nix wrapper. Direct development runs without that value use `python3` on PATH,
|
|
or `python` on Windows. The TUI does not search `PYTHON`, `VIRTUAL_ENV`, or
|
|
checkout venv directories for a different interpreter.
|
|
|
|
The transport is newline-delimited JSON-RPC over stdio:
|
|
|
|
```text
|
|
ui-tui/src tui_gateway/
|
|
----------- -------------
|
|
entry.tsx entry.py
|
|
-> GatewayClient -> request loop
|
|
-> App -> server.py RPC handlers
|
|
|
|
stdin/stdout: JSON-RPC requests, responses, events
|
|
stderr: captured into an in-memory log ring
|
|
```
|
|
|
|
Malformed stdout lines are treated as protocol noise and surfaced as `gateway.protocol_error`. Stderr lines become `gateway.stderr`. Neither writes directly into the terminal.
|
|
|
|
## Running it
|
|
|
|
From the repo root, the normal path is:
|
|
|
|
```bash
|
|
hermes --tui
|
|
```
|
|
|
|
The CLI expects `ui-tui/dist/entry.js` to exist, or the whole source code available in which to run `npm install` and `npm run dev`.
|
|
|
|
```bash
|
|
cd ui-tui
|
|
npm install
|
|
```
|
|
|
|
Local package commands:
|
|
|
|
```bash
|
|
npm run dev
|
|
npm start
|
|
npm run build
|
|
npm run lint
|
|
npm run fmt
|
|
npm run fix
|
|
```
|
|
|
|
Tests use vitest:
|
|
|
|
```bash
|
|
npm test # single run
|
|
npm run test:watch
|
|
```
|
|
|
|
## Live agents
|
|
|
|
The dock above the composer appears automatically while children are running. It shows
|
|
actual live-child counts, task names, elapsed time, and the latest activity. Its row budget
|
|
shrinks on short terminals; finished work remains in the existing `/agents` / `/replay` history
|
|
rather than permanently occupying composer space. Async completion units are not counted
|
|
as extra agents.
|
|
|
|
- **Ctrl+T** expands the roster without clearing your draft; **Esc** returns.
|
|
- **↑/↓** selects an agent, **Enter** opens its details (tools, output, files, usage).
|
|
- **t** opens its bounded live transcript tail; **g/G** moves to top/bottom.
|
|
- **e** opens a separate steering form. **Enter** queues guidance and **Esc** returns.
|
|
“Queued” means accepted for the next tool boundary, not confirmed delivery.
|
|
- **x** requests that the selected child stop; **X** requests a subtree stop.
|
|
- Existing sort/filter, spawn-pause, timeline, and replay controls remain available.
|
|
|
|
The roster hydrates from the session-scoped `subagent.list` RPC alongside streamed events.
|
|
Only an open tail view polls `subagent.tail`; steering uses the existing `subagent.steer` RPC.
|
|
No model tool schema or prompt-caching behavior changes.
|
|
|
|
## App model
|
|
|
|
`src/app.tsx` is the center of the UI. Heavy logic is split into `src/app/`:
|
|
|
|
- `src/app/createGatewayEventHandler.ts` — maps gateway events to state updates
|
|
- `src/app/createSlashHandler.ts` — local slash command dispatch
|
|
- `src/app/useComposerState.ts` — draft, multiline buffer, queue editing
|
|
- `src/app/useInputHandlers.ts` — keypress routing
|
|
- `src/app/useMainApp.ts` — top-level composition hook: wires all sub-hooks, manages transcript history, session polling, and exposes props consumed by `app.tsx`
|
|
- `src/app/useSessionLifecycle.ts` — session create / resume / activate / close and visible-history reset
|
|
- `src/app/useSubmission.ts` — message send, shell exec (`!cmd`), inline interpolation (`{!cmd}`), and busy-input-mode dispatch (queue / steer / interrupt)
|
|
- `src/app/turnController.ts` — stateful class that drives the turn lifecycle: buffers streaming deltas, manages tool/reasoning state, handles interrupt and message-complete transitions
|
|
- `src/app/turnStore.ts` — nanostore for turn state (streaming text, tools, reasoning, subagents, todos, activity trail)
|
|
- `src/app/useConfigSync.ts` — fetches `config.get full` on session start and polls config mtime every 5 s; applies display settings and triggers MCP reload on change
|
|
- `src/app/useLongRunToolCharms.ts` — fires ambient activity messages for tools running longer than 8 s
|
|
- `src/app/overlayStore.ts` / `src/app/uiStore.ts` — nanostores for overlay and UI state
|
|
- `src/app/delegationStore.ts` — nanostore for subagent spawning caps and overlay accordion state
|
|
- `src/app/spawnHistoryStore.ts` — in-memory ring (last 10) of finished subagent fan-out snapshots; populated at turn end for `/replay`
|
|
- `src/app/inputSelectionStore.ts` — nanostore exposing the active text-input selection handle
|
|
- `src/app/gatewayContext.tsx` — React context for the gateway client
|
|
- `src/app/gatewayRecovery.ts` — pure function that decides whether to respawn and resume after a gateway crash, with a 3-attempt / 60 s budget
|
|
- `src/app/setupHandoff.ts` — launches external `hermes setup`, suspends Ink while it runs, opens a new session on success
|
|
- `src/app/scroll.ts` — scrolls the viewport while keeping the text selection anchor in sync
|
|
- `src/app/interfaces.ts` — internal interfaces (ComposerActions, GatewayRpc, etc.)
|
|
|
|
### Slash command subsystem (`src/app/slash/`)
|
|
|
|
- `types.ts` — `SlashCommand` interface and `SlashRunCtx` execution context (gateway rpc, transcript helpers, session refs, stale-guard)
|
|
- `registry.ts` — assembles `SLASH_COMMANDS` from all command files in registration order (core → billing → credits → session → ops → setup → debug) and exposes `findSlashCommand(name)` for case-insensitive lookup
|
|
- `commands/core.ts` — general TUI commands
|
|
- `commands/billing.ts` — `/billing`: manage Nous remote spending — buy credits, auto-reload, limits
|
|
- `commands/credits.ts` — `/credits`
|
|
- `commands/session.ts` — session and agent commands
|
|
- `commands/ops.ts` — operations commands
|
|
- `commands/setup.ts` — `/setup`
|
|
- `commands/debug.ts` — `/heapdump`, `/mem`
|
|
|
|
The top-level `app.tsx` composes these into the Ink tree with `Static` transcript output, a live streaming assistant row, prompt overlays, queue preview, status rule, input line, and completion list.
|
|
|
|
State managed at the top level includes:
|
|
|
|
- transcript and streaming state
|
|
- queued messages and input history
|
|
- session lifecycle
|
|
- tool progress and reasoning text
|
|
- prompt flows for approval, clarify, sudo, and secret input
|
|
- slash command routing
|
|
- tab completion and path completion
|
|
- theme state from gateway skin data
|
|
|
|
The UI renders as a normal Ink tree with `Static` transcript output, a live streaming assistant row, prompt overlays, queue preview, status rule, input line, and completion list.
|
|
|
|
The intro panel is driven by `session.info` and rendered through `branding.tsx`.
|
|
|
|
## Hotkeys and interactions
|
|
|
|
Current input behavior is split across `app.tsx`, `components/textInput.tsx`, and the prompt/picker components.
|
|
|
|
### Main chat input
|
|
|
|
| Key | Behavior |
|
|
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `Enter` | Submit the current draft |
|
|
| empty `Enter` twice | If queued messages exist and the agent is busy, interrupt the current run. If queued messages exist and the agent is idle, send the next queued message |
|
|
| `Shift+Enter` / `Alt+Enter` | Insert a newline in the current draft |
|
|
| `\` + `Enter` | Append the line to the multiline buffer (fallback for terminals without modifier support) |
|
|
| `Ctrl+C` | Interrupt active run, or clear the current draft, or exit if nothing is pending |
|
|
| `Ctrl+D` | Exit |
|
|
| `Cmd/Ctrl+G` / `Alt+G` | Open `$EDITOR` with the current draft (use `Alt+G` in VSCode/Cursor — they bind the primary keystroke to Find Next) |
|
|
| `Ctrl+L` | New session (same as `/clear`) |
|
|
| `Ctrl+V` / `Alt+V` | Paste text first, then fall back to image/path attachment when applicable |
|
|
| `Tab` | Apply the active completion |
|
|
| `Up/Down` | Cycle completions if the completion list is open; otherwise edit queued messages first, then walk input history |
|
|
| `Left/Right` | Move the cursor |
|
|
| modified `Left/Right` | Move by word when the terminal sends `Ctrl` or `Meta` with the arrow key |
|
|
| `Home` / `Ctrl+A` | Start of line |
|
|
| `End` / `Ctrl+E` | End of line |
|
|
| `Backspace` | Delete the character to the left of the cursor |
|
|
| `Delete` | Delete the character to the right of the cursor |
|
|
| modified `Backspace` | Delete the previous word |
|
|
| modified `Delete` | Delete the next word |
|
|
| `Ctrl+W` | Delete the previous word |
|
|
| `Ctrl+U` | Delete from the cursor back to the start of the line |
|
|
| `Ctrl+K` | Delete from the cursor to the end of the line |
|
|
| `Meta+B` / `Meta+F` | Move by word |
|
|
| `!cmd` | Run a shell command through the gateway |
|
|
| `{!cmd}` | Inline shell interpolation before send; queued drafts keep the raw text until they are sent |
|
|
|
|
Notes:
|
|
|
|
- `Tab` only applies completions when completions are present and you are not in multiline mode.
|
|
- Queue/history navigation only applies when you are not in multiline mode.
|
|
- `PgUp` / `PgDn` are left to the terminal emulator; the TUI does not handle them.
|
|
|
|
### Prompt and picker modes
|
|
|
|
| Context | Keys | Behavior |
|
|
| --------------------------- | ------------------- | ------------------------------------------------- |
|
|
| approval prompt | `Up/Down`, `Enter` | Move and confirm the selected approval choice |
|
|
| approval prompt | `o`, `s`, `a`, `d` | Quick-pick `once`, `session`, `always`, `deny` |
|
|
| approval prompt | `Esc`, `Ctrl+C` | Deny |
|
|
| clarify prompt with choices | `Up/Down`, `Enter` | Move and lock the selected choice |
|
|
| clarify prompt with choices | single-digit number | Quick-pick the matching numbered choice |
|
|
| clarify prompt with choices | `Enter` on "Other" | Switch into free-text entry |
|
|
| clarify free-text mode | `Enter` | Lock typed answer (empty skips the question) |
|
|
| clarify prompt | `Tab`, `Shift+Tab` | Switch question |
|
|
| clarify prompt | `Esc`, `Ctrl+C` | Cancel the remaining questions |
|
|
| sudo / secret prompt | `Enter` | Submit typed value |
|
|
| sudo / secret prompt | `Ctrl+C` | Cancel by sending an empty response |
|
|
| resume picker | `Up/Down`, `Enter` | Move and resume the selected session |
|
|
| resume picker | `1-9` | Quick-pick one of the first nine visible sessions |
|
|
| resume picker | `Esc`, `Ctrl+C` | Close the picker |
|
|
|
|
Notes:
|
|
|
|
- Clarify free-text mode and masked prompts use `ink-text-input`, so text editing there follows the library's default bindings rather than `components/textInput.tsx`.
|
|
- When a blocking prompt is open, the main chat input hotkeys are suspended.
|
|
- Sudo and secret prompts only expose `Ctrl+C` cancellation from the app-level blocked handler.
|
|
|
|
### Interaction rules
|
|
|
|
- Plain text entered while the agent is busy is queued instead of sent immediately.
|
|
- Slash commands and `!cmd` do not queue; they execute immediately even while a run is active.
|
|
- Queue auto-drains after each assistant response, unless a queued item is currently being edited.
|
|
- `Up/Down` prioritizes queued-message editing over history. History only activates when there is no queue to edit.
|
|
- Queued drafts keep their original `!cmd` and `{!cmd}` text while you edit them. Shell commands and interpolation run when the queued item is actually sent.
|
|
- If you load a queued item into the input and resubmit plain text, that queue item is replaced, removed from the queue preview, and promoted to send next. If the agent is still busy, the edited item is moved to the front of the queue and sent after the current run completes.
|
|
- Completion requests are debounced by 60 ms. Input starting with `/` uses `complete.slash`. A trailing token that starts with `./`, `../`, `~/`, `/`, or `@` uses `complete.path`.
|
|
- Text pastes are inserted inline directly into the draft. Nothing is newline-flattened.
|
|
- `Cmd/Ctrl+G` (or `Alt+G` in VSCode/Cursor, which intercept the primary keystroke for Find Next) writes the current draft, including any multiline buffer, to a temp file, suspends Ink, launches `$EDITOR`, then restores the TUI and submits the saved text if the editor exits cleanly.
|
|
- Input history is stored in `~/.hermes/.hermes_history` or under `HERMES_HOME`.
|
|
|
|
## Rendering
|
|
|
|
Assistant output is rendered in one of two ways:
|
|
|
|
- if the payload already contains ANSI, `messageLine.tsx` prints it directly
|
|
- otherwise `components/markdown.tsx` renders a small Markdown subset into Ink components
|
|
|
|
The Markdown renderer handles headings, lists, block quotes, tables, fenced code blocks, diff coloring, inline code, emphasis, links, and plain URLs.
|
|
|
|
Tool/status activity is shown in a live activity lane. Transcript rows stay focused on user/assistant turns.
|
|
|
|
## Prompt flows
|
|
|
|
The Python gateway can pause the main loop and ask the client a question. These are JSON-RPC
|
|
**requests from the server** (string id, answered with a response frame of the same id — see
|
|
`createServerRequestHandler.ts`), not events:
|
|
|
|
- `approval`: allow once, allow for session, allow always, or deny → `{ choice }`
|
|
- `clarify`: one or more questions; each answer is locked with the `clarify.lock` RPC, cancel → `{}`
|
|
- `sudo`: masked password entry → `{ value }`
|
|
- `secret`: masked value entry for a named env var → `{ value }`
|
|
- `session.list`: used by `SessionPicker` for `/resume`
|
|
|
|
A withdrawn question (timeout, interrupt) arrives as a `request.cancel` event carrying its id.
|
|
|
|
These are stateful UI branches in `app.tsx`, not separate screens.
|
|
|
|
## Commands
|
|
|
|
The following commands are handled directly by the TUI client. Unrecognized commands fall through to the Python gateway via `slash.exec` and `command.dispatch`.
|
|
|
|
### Core (`core.ts`)
|
|
`/help`, `/quit` (alias `/exit`), `/update`, `/clear` (alias `/new`),
|
|
`/density`, `/copy`, `/paste`, `/details` (alias `/detail`),
|
|
`/statusbar` (alias `/sb`), `/queue` (alias `/q`), `/logs`, `/history`,
|
|
`/save`, `/undo`, `/retry`, `/steer`, `/mouse` (alias `/scroll`),
|
|
`/status`, `/title`, `/fortune`, `/redraw`, `/terminal-setup`
|
|
|
|
### Billing (`billing.ts`)
|
|
`/billing` — manage Nous remote spending — buy credits, auto-reload, limits
|
|
|
|
### Session (`session.ts`)
|
|
`/model`, `/sessions` (aliases `/switch`, `/session`, `/resume`),
|
|
`/bg`, `/btw`, `/image`, `/personality`,
|
|
`/compress`, `/branch` (alias `/fork`), `/voice`, `/skin`,
|
|
`/indicator`, `/yolo`, `/reasoning`, `/fast`, `/busy`, `/verbose`, `/usage`
|
|
|
|
### Ops (`ops.ts`)
|
|
`/stop`, `/reload-mcp` (alias `/reload_mcp`), `/reload`, `/browser`,
|
|
`/rollback`, `/agents` (alias `/tasks`), `/replay`, `/replay-diff`,
|
|
`/skills`, `/reload-skills` (alias `/reload_skills`), `/plugins`, `/tools`
|
|
|
|
### Credits (`credits.ts`)
|
|
`/credits` — Nous credit balance and browser top-up
|
|
|
|
### Setup (`setup.ts`)
|
|
`/setup` — launches external `hermes setup` wizard, suspends Ink while it runs
|
|
|
|
### Debug (`debug.ts`)
|
|
`/heapdump`, `/mem` — V8 memory diagnostics
|
|
|
|
---
|
|
|
|
Anything not matched above falls through to:
|
|
|
|
1. `slash.exec`
|
|
2. `command.dispatch`
|
|
|
|
That lets Python own aliases, plugins, skills, and registry-backed commands without duplicating the logic in the TUI.
|
|
|
|
## Event surface
|
|
|
|
Primary event types the client handles today:
|
|
|
|
| Event | Payload |
|
|
| -------------------------- | --------------------------------------------------------------------------- |
|
|
| `gateway.ready` | `{ skin? }` |
|
|
| `skin.changed` | `{ skin }` |
|
|
| `session.info` | session metadata for banner + tool/skill panels |
|
|
| `message.start` | start assistant streaming |
|
|
| `message.delta` | `{ text, rendered? }` |
|
|
| `message.complete` | `{ text, rendered?, usage, status }` |
|
|
| `thinking.delta` | `{ text }` |
|
|
| `reasoning.delta` | `{ text, verbose? }` |
|
|
| `reasoning.available` | `{ text, verbose? }` |
|
|
| `status.update` | `{ kind, text }` |
|
|
| `notification.show` | `{ id, key, kind, level, text, ttl_ms? }` |
|
|
| `notification.clear` | `{ key }` |
|
|
| `tool.start` | `{ tool_id, name, context?, args_text? }` |
|
|
| `tool.generating` | `{ name }` |
|
|
| `tool.progress` | `{ name, preview }` |
|
|
| `tool.complete` | `{ tool_id, name, error?, summary?, duration_s?, inline_diff?, todos? }` |
|
|
| `request.cancel` | `{ id, method, reason }` clears the withdrawn server→client request |
|
|
| `background.complete` | `{ task_id, text }` |
|
|
| `billing.step_up.verification` | `{ verification_url, user_code }` |
|
|
| `review.summary` | `{ text }` |
|
|
| `browser.progress` | `{ message }` |
|
|
| `voice.status` | `{ state }` |
|
|
| `voice.transcript` | `{ text, no_speech_limit? }` |
|
|
| `subagent.spawn_requested` | `{ subagent_id?, task_index, goal?, depth?, parent_id? }` |
|
|
| `subagent.start` | `{ subagent_id?, task_index, goal?, depth?, parent_id? }` |
|
|
| `subagent.thinking` | `{ text }` |
|
|
| `subagent.tool` | `{ tool_name?, tool_preview?, text? }` |
|
|
| `subagent.progress` | `{ text }` |
|
|
| `subagent.complete` | `{ status, summary?, text?, duration_seconds? }` |
|
|
| `error` | `{ message }` |
|
|
| `gateway.stderr` | synthesized from child stderr |
|
|
| `gateway.protocol_error` | synthesized from malformed stdout |
|
|
| `gateway.start_timeout` | `{ cwd?, python?, stderr_tail? }` |
|
|
|
|
## Theme model
|
|
|
|
The client starts with `DEFAULT_THEME` from `theme.ts`, then merges in gateway skin data from `gateway.ready`.
|
|
|
|
Current branding overrides:
|
|
|
|
- agent name
|
|
- prompt symbol
|
|
- welcome text
|
|
- goodbye text
|
|
|
|
Current color overrides:
|
|
|
|
- banner title, accent, border, body, dim
|
|
- label, ok, error, warn
|
|
|
|
`branding.tsx` uses those values for the logo, session panel, and update notice.
|
|
|
|
## File map
|
|
|
|
```text
|
|
ui-tui/
|
|
packages/hermes-ink/ forked Ink renderer (local dep)
|
|
src/
|
|
entry.tsx TTY gate + render()
|
|
app.tsx top-level Ink tree, composes src/app/*
|
|
gatewayClient.ts child process + JSON-RPC bridge
|
|
gatewayTypes.ts gateway event and RPC response type definitions
|
|
theme.ts theme colors and skin merge
|
|
banner.ts ASCII art renderer (parses Rich color tags)
|
|
types.ts shared client-side types (ActiveTool, Msg, etc.)
|
|
|
|
app/
|
|
createGatewayEventHandler.ts event → state mapping
|
|
createSlashHandler.ts local slash dispatch
|
|
delegationStore.ts nanostore for subagent spawning caps and overlay accordion state
|
|
gatewayContext.tsx React context for gateway client
|
|
gatewayRecovery.ts crash-recovery budget: respawn+resume capped to 3 attempts / 60 s
|
|
inputSelectionStore.ts nanostore exposing the active text-input selection handle
|
|
interfaces.ts internal interfaces (ComposerActions, GatewayRpc, etc.)
|
|
overlayStore.ts nanostores for overlay state
|
|
scroll.ts viewport scroll with text-selection anchor sync
|
|
setupHandoff.ts launches external hermes setup, suspends Ink while it runs
|
|
spawnHistoryStore.ts ring buffer of finished subagent fan-out snapshots
|
|
turnController.ts stateful turn lifecycle driver (streaming, tools, reasoning)
|
|
turnStore.ts nanostore for turn state (streaming, tools, reasoning, subagents)
|
|
uiStore.ts nanostores for UI flags (busy, sid, mouseTracking, etc.)
|
|
useComposerState.ts draft + multiline buffer + queue editing
|
|
useConfigSync.ts config polling and MCP reload on mtime change
|
|
useInputHandlers.ts keypress routing
|
|
useLongRunToolCharms.ts ambient activity messages for tools running longer than 8 s
|
|
useMainApp.ts top-level composition hook
|
|
useSessionLifecycle.ts session create / resume / activate / close
|
|
useSubmission.ts message send, shell exec, interpolation, busy-input-mode dispatch
|
|
|
|
slash/
|
|
types.ts SlashCommand interface and SlashRunCtx execution context
|
|
registry.ts SLASH_COMMANDS assembly and findSlashCommand lookup
|
|
commands/
|
|
billing.ts /billing — manage Nous remote spending
|
|
core.ts general TUI commands
|
|
credits.ts /credits
|
|
debug.ts /heapdump, /mem
|
|
ops.ts operations commands
|
|
session.ts session and agent commands
|
|
setup.ts /setup wizard
|
|
|
|
components/
|
|
activeSessionSwitcher.tsx active session switch overlay
|
|
agentsOverlay.tsx subagent delegation overlay
|
|
appChrome.tsx status bar, input row, completions
|
|
appLayout.tsx top-level layout composition
|
|
appOverlays.tsx overlay routing (pickers, prompts)
|
|
billingOverlay.tsx billing overlay
|
|
branding.tsx banner + session summary
|
|
fpsOverlay.tsx FPS debug overlay
|
|
helpHint.tsx contextual help hint
|
|
markdown.tsx Markdown-to-Ink renderer
|
|
maskedPrompt.tsx masked input for sudo / secrets
|
|
messageLine.tsx transcript rows
|
|
modelPicker.tsx model switch picker
|
|
overlayControls.tsx shared overlay control buttons
|
|
pluginsHub.tsx plugins hub overlay
|
|
prompts.tsx approval + clarify flows
|
|
queuedMessages.tsx queued input preview
|
|
skillsHub.tsx skills hub overlay
|
|
streamingAssistant.tsx live streaming assistant row
|
|
streamingMarkdown.tsx streaming Markdown renderer
|
|
textInput.tsx custom line editor
|
|
themed.tsx theme-aware wrapper
|
|
thinking.tsx spinner, reasoning, tool activity
|
|
todoPanel.tsx todo list panel
|
|
|
|
config/
|
|
env.ts environment variable resolution and mouse defaults
|
|
limits.ts paste size, live-render and history limits
|
|
timing.ts streaming batch and debounce timing constants
|
|
|
|
content/
|
|
charms.ts ambient activity strings for long-running tools
|
|
faces.ts agent face / kaomoji pool
|
|
fortunes.ts /fortune quote pool
|
|
hotkeys.ts platform-aware hotkey display strings
|
|
placeholders.ts rotating input placeholder strings
|
|
setup.ts setup-required panel content
|
|
verbs.ts tool activity verb map (browser → browsing, etc.)
|
|
|
|
domain/
|
|
blockLayout.ts block layout and lead-gap helpers
|
|
details.ts details visibility mode resolution (hidden/collapsed/expanded)
|
|
messages.ts message formatting and transcript helpers
|
|
paths.ts cwd shortening and path display helpers
|
|
providers.ts provider display name helpers
|
|
roles.ts message role color and label helpers
|
|
slash.ts slash command parsing and TUI session model flag
|
|
usage.ts token usage zero value and helpers
|
|
viewport.ts viewport height estimation helpers
|
|
|
|
hooks/
|
|
useCompletion.ts tab completion (slash + path)
|
|
useGitBranch.ts current git branch via child_process execFile
|
|
useInputHistory.ts persistent history navigation
|
|
useQueue.ts queued message management
|
|
useVirtualHistory.ts virtual list scroll and height tracking
|
|
|
|
lib/
|
|
circularBuffer.ts fixed-size generic ring buffer
|
|
clipboard.ts clipboard read / write via child_process
|
|
editor.ts $EDITOR launch, PATH resolution, and Ink suspend
|
|
emoji.ts emoji and variation selector width helpers
|
|
externalCli.ts external CLI subprocess launcher
|
|
externalLink.ts open URLs in the system browser
|
|
forceTruecolor.ts 24-bit truecolor override before chalk imports
|
|
fpsStore.ts Ink frame FPS tracker nanostore
|
|
fuzzy.ts lightweight fuzzy subsequence scorer
|
|
gracefulExit.ts clean shutdown with failsafe timeout
|
|
history.ts persistent input history (read/append to disk)
|
|
inputMetrics.ts input width and wrap metrics
|
|
liveProgress.ts todo helpers and tool-shelf message assembly
|
|
mathUnicode.ts best-effort LaTeX → Unicode for inline math
|
|
memory.ts V8 heap snapshot and diagnostics helpers
|
|
memoryMonitor.ts automatic heap-dump trigger on high usage
|
|
messages.ts transcript message append helpers
|
|
openExternalUrl.ts platform-aware URL opener (macOS/Linux/Windows)
|
|
osc52.ts OSC 52 terminal clipboard copy sequence
|
|
parentLog.ts append-only log to ~/.hermes/tui-parent.log
|
|
perfPane.tsx FPS / render perf overlay pane
|
|
platform.ts platform-aware keybinding and SSH detection helpers
|
|
precisionWheel.ts high-precision scroll wheel with sticky-frame budget
|
|
prompt.ts composer prompt text helpers
|
|
reasoning.ts reasoning tag detection and split helpers
|
|
rpc.ts JSON-RPC result and command dispatch helpers
|
|
subagentTree.ts subagent tree flattening and aggregate helpers
|
|
syntax.ts syntax token types and theme-aware highlighting
|
|
terminalModes.ts terminal mode reset sequences (kitty, mouse, etc.)
|
|
terminalParity.ts VSCode-like terminal detection and hint helpers
|
|
terminalSetup.ts IDE keybinding config file install helpers
|
|
text.ts text helpers, ANSI detection, tool trail builders
|
|
todo.ts todo item tone and display helpers
|
|
viewportStore.ts viewport height nanostore via ScrollBoxHandle
|
|
virtualHeights.ts virtual list row height estimation
|
|
wheelAccel.ts scroll wheel acceleration state machine
|
|
|
|
protocol/
|
|
interpolation.ts {!cmd} inline shell interpolation regex and helpers
|
|
paste.ts bracketed paste snippet token regex
|
|
|
|
types/
|
|
hermes-ink.d.ts type declarations for @hermes/ink
|
|
|
|
__tests__/ vitest suite
|
|
```
|
|
|
|
Related Python side:
|
|
|
|
```text
|
|
tui_gateway/
|
|
entry.py stdio entrypoint
|
|
server.py RPC handlers and session logic
|
|
render.py optional rich/ANSI bridge
|
|
slash_worker.py persistent HermesCLI subprocess for slash commands
|
|
```
|