Debugging Hermes TUI Slash Commands
Overview
Hermes slash commands span three layers — Python command registry, tui_gateway JSON-RPC bridge, and the Ink/TypeScript frontend. When a command misbehaves (missing from autocomplete, works in CLI but not TUI, config persists but UI doesn't update), the bug is almost always one layer being out of sync with another.
Use this skill when you encounter issues with slash commands in the Hermes TUI, particularly when commands aren't showing in autocomplete, aren't working properly in the TUI, or need to be added/updated.
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 CommandDef entry to COMMAND_REGISTRY in hermes_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_only vs 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 subcommands matches the expected tab-completion options shown by the TUI.
If the command runs server-side, add a handler in HermesCLI.process_command() in cli.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_REGISTRY in hermes_cli/commands.py. Autocomplete data ships from Python.
Command shows in autocomplete but doesn't work. Check the command handler in tui_gateway/server.py and the frontend handler in ui-tui/src/app/createSlashHandler.ts. If the command is local-only in Ink, it must be handled in app.tsx built-in branch; otherwise it falls through to slash.exec and must have a Python handler.
Command behavior differs between CLI and TUI. The command might have different implementations. Check both cli.py::process_command and 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.set is not enough. Also patch the relevant nanostore state immediately (usually patchUiState(...)) and pass any new state through rendering components. Example: /details collapsed must update live detail visibility, not just save details_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 from COMMAND_REGISTRY automatically) includes the canonical name. If the command is cli_only with a gateway_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-debugpy skill to break inside _SlashWorker.exec or the command handler. remote-pdb set at the handler entry is the fastest path.
- Ink side not reacting: use the
node-inspect-debugger skill to break in app.tsx's slash dispatch or the local command branch. sb('dist/app.js', <line>) after npm run build.
- Registry mismatch / unclear which side is wrong: compare the canonical
COMMAND_REGISTRY entry 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
aliases tuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it
- For commands with subcommands, ensure the
subcommands tuple in CommandDef matches what's in the TUI code
cli_only=True commands won't work in gateway/messaging platforms — unless you add a gateway_config_gate and 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/ToolTrail and transcript/pending MessageLine rows. A /clean pass 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/).
1---2name: debugging-hermes-tui-commands3description: Debug Hermes TUI slash commands: Python, gateway, Ink UI.4license: MIT5---6
7# Debugging Hermes TUI Slash Commands
8
9## Overview
10
11Hermes slash commands span three layers — Python command registry, tui_gateway JSON-RPC bridge, and the Ink/TypeScript frontend. When a command misbehaves (missing from autocomplete, works in CLI but not TUI, config persists but UI doesn't update), the bug is almost always one layer being out of sync with another.
12
13Use this skill when you encounter issues with slash commands in the Hermes TUI, particularly when commands aren't showing in autocomplete, aren't working properly in the TUI, or need to be added/updated.
14
15## When to Use
16
17- A slash command exists in one part of the codebase but doesn't work fully
18- A command needs to be added to both backend and frontend
19- Command autocomplete isn't working for specific commands
20- Command behavior is inconsistent between CLI and TUI
21- A command persists config but doesn't apply live in the TUI
22
23## Architecture Overview
24
25```
26Python backend (hermes_cli/commands.py) <- canonical COMMAND_REGISTRY
27 │
28 ▼
29TUI gateway (tui_gateway/server.py) <- slash.exec / command.dispatch
30 │
31 ▼
32TUI frontend (ui-tui/src/app/slash/) <- local handlers + fallthrough
33```
34
35Command 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.
36
37## Investigation Steps
38
391. **Check if the command exists in the TUI frontend:**
40 ```bash
41 search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/
42 search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/
43 ```
44
452. **Examine the TUI command definition:**
46 ```bash
47 read_file ui-tui/src/app/slash/commands/core.ts
48 # If not there:
49 search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files
50 ```
51
523. **Check if the command exists in the Python backend:**
53 ```bash
54 search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/
55 search_files --pattern "commandname" --path hermes_cli/commands.py --context 3
56 ```
57
584. **Examine the gateway implementation:**
59 ```bash
60 search_files --pattern "complete.slash|slash.exec" --path tui_gateway/
61 ```
62
63## Fix: Missing Command Autocomplete
64
65If a command exists in the TUI but doesn't show in autocomplete:
66
671. Add a `CommandDef` entry to `COMMAND_REGISTRY` in `hermes_cli/commands.py`:
68 ```python
69 CommandDef("commandname", "Description of the command", "Session",
70 cli_only=True, aliases=("alias",),
71 args_hint="[arg1|arg2|arg3]",
72 subcommands=("arg1", "arg2", "arg3")),
73 ```
74
752. Pick `cli_only` vs gateway availability carefully:
76 - `cli_only=True` — only in the interactive CLI/TUI
77 - `gateway_only=True` — only in messaging platforms
78 - neither — available everywhere
79 - `gateway_config_gate="display.foo"` — config-gated availability in the gateway
80
813. Ensure `subcommands` matches the expected tab-completion options shown by the TUI.
82
834. If the command runs server-side, add a handler in `HermesCLI.process_command()` in `cli.py`:
84 ```python
85 elif canonical == "commandname":
86 self._handle_commandname(cmd_original)
87 ```
88
895. For gateway-available commands, add a handler in `gateway/run.py`:
90 ```python
91 if canonical == "commandname":
92 return await self._handle_commandname(event)
93 ```
94
95## Common Issues
96
971. **Command shows in TUI but not in autocomplete.** The command is defined in the TUI codebase but missing from `COMMAND_REGISTRY` in `hermes_cli/commands.py`. Autocomplete data ships from Python.
98
992. **Command shows in autocomplete but doesn't work.** Check the command handler in `tui_gateway/server.py` and the frontend handler in `ui-tui/src/app/createSlashHandler.ts`. If the command is local-only in Ink, it must be handled in `app.tsx` built-in branch; otherwise it falls through to `slash.exec` and must have a Python handler.
100
1013. **Command behavior differs between CLI and TUI.** The command might have different implementations. Check both `cli.py::process_command` and the TUI's local handler. Local TUI handlers take precedence over gateway dispatch.
102
1034. **Command persists config but doesn't apply live.** For TUI-local commands, updating `config.set` is not enough. Also patch the relevant nanostore state immediately (usually `patchUiState(...)`) and pass any new state through rendering components. Example: `/details collapsed` must update live detail visibility, not just save `details_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.
104
1055. **Gateway dispatch silently ignores the command.** The gateway only dispatches commands it knows about. Check `GATEWAY_KNOWN_COMMANDS` (derived from `COMMAND_REGISTRY` automatically) includes the canonical name. If the command is `cli_only` with a `gateway_config_gate`, verify the gated config value is truthy.
106
107## Debugging Tactics
108
109When surface-level inspection doesn't reveal the bug:
110
111- **Python side hangs or misbehaves:** use the `python-debugpy` skill to break inside `_SlashWorker.exec` or the command handler. `remote-pdb` set at the handler entry is the fastest path.
112- **Ink side not reacting:** use the `node-inspect-debugger` skill to break in `app.tsx`'s slash dispatch or the local command branch. `sb('dist/app.js', <line>)` after `npm run build`.
113- **Registry mismatch / unclear which side is wrong:** compare the canonical `COMMAND_REGISTRY` entry against the TUI's local command list side-by-side.
114
115## Pitfalls
116
117- Don't forget to set the appropriate category for the command in `CommandDef` (e.g., "Session", "Configuration", "Tools & Skills", "Info", "Exit")
118- Make sure any aliases are properly registered in the `aliases` tuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it
119- For commands with subcommands, ensure the `subcommands` tuple in `CommandDef` matches what's in the TUI code
120- `cli_only=True` commands won't work in gateway/messaging platforms — unless you add a `gateway_config_gate` and the gate is truthy
121- 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`/`ToolTrail` and transcript/pending `MessageLine` rows. A `/clean` pass should explicitly check both.
122- Rebuild the TUI (`npm --prefix ui-tui run build`) before testing — tsx watch mode may lag on first launch
123
124## Verification
125
126After fixing:
127
1281. Rebuild the TUI:
129 ```bash
130 cd /home/bb/hermes-agent && npm --prefix ui-tui run build
131 ```
132
1332. Run the TUI and test the command:
134 ```bash
135 hermes --tui
136 ```
137
1383. Type `/` and verify the command appears in autocomplete suggestions with the expected description and args hint.
139
1404. Execute the command and confirm:
141 - Expected behavior fires
142 - Any persisted config updates correctly (`read_file ~/.hermes/config.yaml`)
143 - Live UI state reflects the change immediately (not just after restart)
144
1455. 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/`).
ichichuang