Extending the Hermes CLI Safely

Hermes exposes protected hooks for wrapper CLIs that need custom widgets, keyboard shortcuts, commands, layout order, or styling. These seams are safer than copying or overriding the entire interactive run loop.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/extending-the-cli

Extension seams

Use the extra-widget hook for persistent panels, the keybinding hook for shortcuts, and process_command() for custom slash commands. Override the layout-children hook only when widget ordering truly must change. Style customizations belong in the style-dictionary hook.

A wrapper should call the parent implementation for commands it does not own. Toggleable widgets should use supported prompt-toolkit containers or filters and trigger a UI invalidation when state changes. New keys must avoid built-in submit, interrupt, exit, newline, and suggestion bindings.

Extension checklist

• Use a wrapper subclass rather than editing the main run loop.
• Add only the smallest protected hook needed.
• Keep widget state on the wrapper instance.
• Avoid collisions with built-in keybindings.
• Delegate unknown commands to super().process_command().
• Keep optional widgets hidden without leaving layout gaps.
• Preserve approval, clarification, model-picker, spinner, and voice surfaces.
• Test narrow terminals and resize behavior.

Pitfalls

• Replacing the full run method and inheriting a maintenance fork.
• Capturing stale state in widget callbacks.
• Registering a key that steals Enter, Ctrl-C, Ctrl-D, Tab, or escape-newline behavior.
• Reordering conditional overlays so approvals become inaccessible.
• Assuming a widget that renders once will refresh automatically.

Verification steps

1. Launch the wrapper with no custom panel visible.
2. Toggle the panel by key and command.
3. Confirm built-in input, completion, interrupt, and exit behavior remains intact.
4. Trigger a harmless approval or clarification surface.
5. Resize the terminal and check for clipped input or status lines.
6. Run a normal tool-using conversation.
7. Update Hermes in a test environment and confirm the wrapper still uses supported hooks.