mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-09 13:21:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
hermes-agent/docs/opentui-env-flags.md
alt-glitch 33924c074c docs(opentui): point bench references at the tui-bench repo 
bench/ moved to github.com/NousResearch/tui-bench; repoint the lingering
references in dev-handoff, env-flags, memory-story, ui-opentui README, and
the memlog/memSampler/reconciler source comments.
2026-06-14 10:56:08 +05:30

4.6 KiB
Raw Blame History

OpenTUI env flags — the consolidated ledger

Every environment variable the OpenTUI TUI reads (grep-verified 2026-06-12), classified by who should ever touch it. The design rule shipped with this doc: regular users see zero diagnostic surface by default; one master switch (HERMES_TUI_DIAGNOSTICS=1) turns all of it on when needed.

1. The master switch

var default effect
HERMES_TUI_DIAGNOSTICS off Enables the diagnostic slash commands (/mem, /heapdump). While off they're hidden from /help (client-side filter) and invoking them prints the enable hint rather than executing. They never appear in slash completion in either state — completion is gateway-driven and these are client-only commands the gateway doesn't know (an adversarial review confirmed there's no bypass path; if a SERVER command named mem/heapdump is ever added it must be gated gateway-side too — the client gate would shadow but not hide it). Also flips the default of HERMES_TUI_WINDOW_STATS to on. Not a secret — support flows are "relaunch with HERMES_TUI_DIAGNOSTICS=1".

2. User-facing configuration (fine to document publicly)

var default effect
HERMES_TUI_ENGINE auto (opentui if Node≥26.3 + built, else ink) Engine pick; also display.tui_engine in config.yaml.
HERMES_TUI_MOUSE on (launcher sets it) Mouse support (wheel scroll, selection, click-to-expand). Glitch verdict 2026-06-12: leave as-is — always on, no realistic reason to disable; treat as plumbing, don't document it user-facing.
HERMES_TUI_MAX_MESSAGES ceiling Scrollback rows kept in the TUI. Can LOWER the ceiling, never raise: 3000 with windowing, 1000 with windowing off (handle-table safety).
HERMES_TUI_TOOL_OUTPUT_LINES unlimited Cap expanded tool-output lines (set a number to restore a cap).
HERMES_TUI_COMPOSER_ROWS default rows Composer height.

3. Escape hatches & tuning (dev-facing, individually settable)

var default effect
HERMES_TUI_WINDOWING on 0 = bit-exact pre-windowing renderer (every row mounts; cap clamps back to 1000). The A/B + regression escape hatch.
HERMES_TUI_WINDOW_IDLE_MS ~1000 Idle-measure pulse cadence (the spacer-exactness march). Test knob.
HERMES_TUI_WINDOW_STATS = HERMES_TUI_DIAGNOSTICS Exposes live/peak mounted-row counters (globalThis.__hermesTuiWindowStats) for tui-bench's live-attach reads.
HERMES_TUI_MEMLOG = HERMES_TUI_DIAGNOSTICS In-process 1Hz memory self-sampling (boundary/memlog.ts) → ~/.hermes/logs/memwatch/<boot>-<pid>.jsonl (rss/heap/external + mounted rows; 14-day retention). Fleet view: node memwatch-report.mjs from the tui-bench repo (github.com/NousResearch/tui-bench). The "monitor all my sessions" answer: one export HERMES_TUI_DIAGNOSTICS=1 in your shell rc covers every session.
HERMES_TUI_LOG_LEVEL / HERMES_TUI_LOG_FILE engine defaults Logging verbosity/destination (/logs reads the ring buffer regardless). Deliberately independent of the master switch — support often wants logs without the full diag surface.

4. Internal plumbing (set by the launcher/tui-bench/tests — humans never set these)

var set by effect
HERMES_PYTHON, HERMES_PYTHON_SRC_ROOT, HERMES_CWD launcher / bench Which gateway python + repo root + cwd the TUI spawns against (the bench's fake-gateway seam).
HERMES_TUI_ACTIVE_SESSION_FILE launcher/bench Session handoff file.
HERMES_TUI_RESUME, HERMES_TUI_PROMPT, HERMES_TUI_FAKE launcher/tests Resume-at-boot, seeded prompt, fake-mode.
HERMES_TUI_RPC_TIMEOUT_MS, HERMES_TUI_STARTUP_TIMEOUT_MS tests/CI Protocol timeouts.
(ui-tui only) HERMES_TUI_MEMSAMPLE_FD/MS bench Ink fd-3 node sampler.

How the pieces compose (the support script)

  • Regular user, normal day: zero flags, zero diagnostic commands visible.
  • "My TUI feels heavy" support flow: HERMES_TUI_DIAGNOSTICS=1 hermes → /mem for the live numbers, /heapdump for a snapshot to attach, window stats exposed for tui-bench's live-attach.sh <pid> to read.
  • Developer profiling: same master switch + the individual knobs (HERMES_TUI_WINDOWING=0 A/B, WINDOW_IDLE_MS tuning) as needed.
  • Anything in section 4 appearing in a user-facing doc is a bug.

Gating implementation: logic/env.ts (diagnosticsEnabled()), logic/slash.ts (DIAGNOSTIC_COMMANDS — dispatch hint, help + completion filtering), view/transcript.tsx (stats default). Tests: slash.test.ts (gating both states), utilityCommands.test.ts (commands themselves, gate enabled suite-wide).