debugging-hermes-tui-commands
Debug Hermes TUI: slash commands, rendering/layout, Python gateway, Ink UI.
- License 许可
- MIT
- 所属仓库
- iberi22/skills
- 最近更新
- 2026-10-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- debugging-hermes-tui-commands
- author
- Hermes Agent
- license
- MIT
- version
- 1.1.0
- metadata
- { "hermes": { "tags": [ "debugging", "hermes-agent", "tui", "slash-commands", "rendering", "layout", "typescript", "python" ], "related_skills": [ "python-debugpy", "node-inspect-debugger", "systematic-debugging" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Debug Hermes TUI: slash commands, rendering/layout, Python gateway, Ink UI.
02 资源文件 1
- 参考文档references/tui-rendering-pipeline.md7.2 KB
03 SKILL.md 正文
Debugging Hermes TUI — Commands & Rendering
Overview
Hermes has two TUIs: the classic CLI (prompt_toolkit + Rich, Python) and the Ink TUI (hermes --tui, React/TypeScript via Ink). Slash commands and rendering issues can span up to three layers — Python command registry/backend, tui_gateway JSON-RPC bridge, and the Ink/TypeScript frontend.
When to Use This Skill
- Slash commands: missing from autocomplete, work in CLI but not TUI, config persists but UI doesn't update, behavior inconsistent between layers
- Rendering/layout: scrollback separators wrong width after resize, status bar overflow, layout flicker, broken alignment, stale width calculations
- Adding commands: register in both Python backend and TypeScript frontend
Architecture Overview
Python backend (hermes_cli/commands.py) <- canonical COMMAND_REGISTRY
│
▼
TUI gateway (tui_gateway/server.py) <- slash.exec / command.dispatch
│
▼
TUI frontend (ui-tui/src/app/slash/) <- local handlers + fallthrough
Classic CLI rendering pipeline (the default hermes command):
Print to scrollback → ChatConsole (Rich Console) → ANSI escapes → _cprint() → prompt_toolkit print_formatted_text(ANSI(...))
Live TUI footer → _get_status_bar_fragments() → prompt_toolkit FormattedTextControl → Window
Live separators → input_rule_top / input_rule_bot Windows with char='─' (auto-fills width)
See references/tui-rendering-pipeline.md for a deep dive on the rendering pipeline, including how scrollback vs live TUI rendering interacts with terminal resize.
When to Use
- A slash command exists in one part of the codebase but doesn't work fully
- A command needs to be added to both backend and frontend
- Command autocomplete isn't working for specific commands
- Command behavior is inconsistent between CLI and TUI
- A command persists config but doesn't apply live in the TUI
Architecture Overview
Python backend (hermes_cli/commands.py) <- canonical COMMAND_REGISTRY
│
▼
TUI gateway (tui_gateway/server.py) <- slash.exec / command.dispatch
│
▼
TUI frontend (ui-tui/src/app/slash/) <- local handlers + fallthrough
Command definitions must be registered consistently across Python and TypeScript to work properly. The Python COMMAND_REGISTRY is the source of truth for: CLI dispatch, gateway help, Telegram BotCommand menu, Slack subcommand map, and autocomplete data shipped to Ink.
Investigation Steps
-
Check if the command exists in the TUI frontend:
search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/ search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/ -
Examine the TUI command definition:
read_file ui-tui/src/app/slash/commands/core.ts # If not there: search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files -
Check if the command exists in the Python backend:
search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/ search_files --pattern "commandname" --path hermes_cli/commands.py --context 3 -
Examine the gateway implementation:
search_files --pattern "complete.slash|slash.exec" --path tui_gateway/
Fix: Missing Command Autocomplete
If a command exists in the TUI but doesn't show in autocomplete:
-
Add a
CommandDefentry toCOMMAND_REGISTRYinhermes_cli/commands.py:CommandDef("commandname", "Description of the command", "Session", cli_only=True, aliases=("alias",), args_hint="[arg1|arg2|arg3]", subcommands=("arg1", "arg2", "arg3")), -
Pick
cli_onlyvs gateway availability carefully:cli_only=True— only in the interactive CLI/TUIgateway_only=True— only in messaging platforms- neither — available everywhere
gateway_config_gate="display.foo"— config-gated availability in the gateway
-
Ensure
subcommandsmatches the expected tab-completion options shown by the TUI. -
If the command runs server-side, add a handler in
HermesCLI.process_command()incli.py:elif canonical == "commandname": self._handle_commandname(cmd_original) -
For gateway-available commands, add a handler in
gateway/run.py:if canonical == "commandname": return await self._handle_commandname(event)
Common Issues
-
Command shows in TUI but not in autocomplete. The command is defined in the TUI codebase but missing from
COMMAND_REGISTRYinhermes_cli/commands.py. Autocomplete data ships from Python. -
Command shows in autocomplete but doesn't work. Check the command handler in
tui_gateway/server.pyand the frontend handler inui-tui/src/app/createSlashHandler.ts. If the command is local-only in Ink, it must be handled inapp.tsxbuilt-in branch; otherwise it falls through toslash.execand must have a Python handler. -
Command behavior differs between CLI and TUI. The command might have different implementations. Check both
cli.py::process_commandand the TUI's local handler. Local TUI handlers take precedence over gateway dispatch. -
Command persists config but doesn't apply live. For TUI-local commands, updating
config.setis not enough. Also patch the relevant nanostore state immediately (usuallypatchUiState(...)) and pass any new state through rendering components. Example:/details collapsedmust update live detail visibility, not just savedetails_mode; in-session global/details <mode>may need a separate command-override flag so live commands can override built-in section defaults while startup/config sync preserves default-expanded thinking/tools behavior. -
Gateway dispatch silently ignores the command. The gateway only dispatches commands it knows about. Check
GATEWAY_KNOWN_COMMANDS(derived fromCOMMAND_REGISTRYautomatically) includes the canonical name. If the command iscli_onlywith agateway_config_gate, verify the gated config value is truthy.
Debugging Tactics
When surface-level inspection doesn't reveal the bug:
- Python side hangs or misbehaves: use the
python-debugpyskill to break inside_SlashWorker.execor the command handler.remote-pdbset at the handler entry is the fastest path. - Ink side not reacting: use the
node-inspect-debuggerskill to break inapp.tsx's slash dispatch or the local command branch.sb('dist/app.js', <line>)afternpm run build. - Registry mismatch / unclear which side is wrong: compare the canonical
COMMAND_REGISTRYentry against the TUI's local command list side-by-side.
Pitfalls
- Don't forget to set the appropriate category for the command in
CommandDef(e.g., "Session", "Configuration", "Tools & Skills", "Info", "Exit") - Make sure any aliases are properly registered in the
aliasestuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it - For commands with subcommands, ensure the
subcommandstuple inCommandDefmatches what's in the TUI code cli_only=Truecommands won't work in gateway/messaging platforms — unless you add agateway_config_gateand the gate is truthy- After adding live UI state, search every consumer of the old prop/helper and thread the new state through all render paths, not just the active streaming path. TUI detail rendering has at least two important paths: live
StreamingAssistant/ToolTrailand transcript/pendingMessageLinerows. A/cleanpass should explicitly check both. - Rebuild the TUI (
npm --prefix ui-tui run build) before testing — tsx watch mode may lag on first launch
Verification
After fixing:
-
Rebuild the TUI:
cd /home/bb/hermes-agent && npm --prefix ui-tui run build -
Run the TUI and test the command:
hermes --tui -
Type
/and verify the command appears in autocomplete suggestions with the expected description and args hint. -
Execute the command and confirm:
- Expected behavior fires
- Any persisted config updates correctly (
read_file ~/.hermes/config.yaml) - Live UI state reflects the change immediately (not just after restart)
-
If the command is also gateway-available, test it from at least one messaging platform (or run the gateway tests:
scripts/run_tests.sh tests/gateway/).
04 同仓库更多 Skills
web-design-guidelines
暂无简介
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall. Recovers the page via archives and provenance-checked fallbacks.
studio-coach
暂无简介
src-generator
暂无简介
sqlite-pro
暂无简介
rigor-evaluator
Use when you need a quick heuristic rigor score (10 criteria, 0-2 each) for the features in a .gitcore/features.json file, to decide which features are ready to ship.