Debugging Hermes TUI Slash Commands - Setup Guide¶
Source: nousresearch/hermes-agent (76 installs) Category: Development / Debugging License: MIT · Platforms: Linux, macOS, Windows Dependencies: Hermes Agent TUI (Ink/TypeScript frontend)
Diagnose and fix Hermes TUI slash command issues across the three-layer architecture: Python command registry, tui_gateway JSON-RPC bridge, and Ink/TypeScript frontend. Essential for Hermes developers and power users debugging command autocomplete, registration, or TUI-CLI inconsistency.
What It Does¶
| Capability | How |
|---|---|
| Command autocomplete debugging | Diagnose why commands don't appear in TUI autocomplete |
| Layer desync detection | Identify when Python registry ≠ gateway ≠ frontend |
| TUI-CLI inconsistency | Fix commands that work in CLI but not TUI |
| Config persistence | Debug commands that persist config but don't apply live |
| New command registration | Walkthrough for adding commands to all three layers |
Architecture Overview¶
Hermes slash commands span three layers:
┌─────────────────────────────┐
│ Ink/TypeScript Frontend │ ← What you see (autocomplete, rendering)
├─────────────────────────────┤
│ tui_gateway JSON-RPC │ ← Bridge between Python ↔ TypeScript
├─────────────────────────────┤
│ Python Command Registry │ ← Backend command definitions
└─────────────────────────────┘
A bug in any single layer can cause commands to fail silently.
Installation¶
Via skills.sh (Recommended)¶
npx skills add https://github.com/nousresearch/hermes-agent --skill debugging-hermes-tui-commands
Direct from Hermes Agent Repo¶
git clone --depth 1 https://github.com/nousresearch/hermes-agent.git /tmp/hermes-agent
cp -r /tmp/hermes-agent/skills/development/debugging-hermes-tui-commands ~/.hermes/skills/
When to Use¶
| Symptom | Likely Layer | Action |
|---|---|---|
| Command missing from autocomplete | Frontend or Gateway | Check tui_gateway command list |
| Works in CLI, not TUI | Gateway bridge | Verify JSON-RPC method registration |
| Config saves but TUI stale | Frontend | Check frontend config reload logic |
| Command registered but no-op | Python registry | Verify command handler binding |
| Adding new command | All three | Follow the three-layer registration |
Common Debugging Commands¶
# Check registered Python commands
hermes commands list
# Restart TUI gateway
hermes gateway restart
# Check TUI frontend for loaded commands
# (In TUI, type / and observe autocomplete)
# Verify JSON-RPC bridge is healthy
curl -s http://localhost:$(hermes gateway port)/health
Prerequisites¶
| Requirement | Details |
|---|---|
| Hermes Agent | v0.20.0+ (TUI-enabled) |
| Node.js | 18+ (for Ink/TypeScript frontend) |
| Terminal | TUI-capable (iTerm2, Kitty, WezTerm, Windows Terminal) |
Verification¶
After install, test by diagnosing a known command:
Hermes, why doesn't /my-custom-command show up in the TUI autocomplete?
The agent should walk through the three-layer diagnostic: Python registry → gateway → frontend.
Pitfalls¶
- TUI-only skill: Does not apply to CLI-only Hermes deployments. The three-layer architecture is TUI-specific.
- Requires TUI access: You need a running Hermes TUI to verify fixes. Cannot diagnose purely from CLI.
- Gateway restart needed: Many fixes require
hermes gateway restartto take effect. The skill will guide this but won't auto-restart.
Installed via: npx skills add nousresearch/hermes-agent --skill debugging-hermes-tui-commands
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.