debugging-hermes-tui-commands

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), one layer is out of sync with another. Use for any slash command that half-works, needs adding to backend + frontend, or behaves differently in CLI vs 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

1. TUI frontend: search for /commandname under ui-tui/ (*.ts, *.tsx).
2. TUI command definitions: ui-tui/src/app/slash/commands/core.ts.
3. Python backend: hermes_cli/commands.py (COMMAND_REGISTRY, CommandDef).
4. Gateway: tui_gateway/server.py (slash.exec / complete.slash).

Fix: Missing Command Autocomplete

If a command exists in the TUI but doesn't show in autocomplete:

1. 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")),
   

2. Pick cli_only vs gateway availability carefully:

   • cli_only=True — only in the interactive CLI/TUI
   • gateway_only=True — only in messaging platforms
   • neither — available everywhere
   • gateway_config_gate="display.foo" — config-gated availability in the gateway