Interactive Chat

Relevant source files

• .env.example
• AGENTS.md
• README.md
• agent/auxiliary_client.py
• cli-config.yaml.example
• cli.py
• gateway/run.py
• gateway/slash_commands.py
• hermes_cli/auth.py
• hermes_cli/browser_connect.py
• hermes_cli/cli_commands_mixin.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/curses_ui.py
• hermes_cli/main.py
• hermes_cli/models.py
• hermes_cli/plugins_cmd.py
• hermes_cli/runtime_provider.py
• hermes_cli/session_listing.py
• hermes_cli/setup.py
• hermes_cli/subcommands/acp.py
• hermes_cli/subcommands/claw.py
• hermes_cli/subcommands/insights.py
• hermes_cli/subcommands/memory.py
• hermes_cli/subcommands/pairing.py
• hermes_cli/subcommands/plugins.py
• hermes_cli/subcommands/skills.py
• hermes_cli/subcommands/tools.py
• hermes_cli/write_approval_commands.py
• run_agent.py
• tests/agent/test_auxiliary_client.py
• tests/cli/test_branch_command.py
• tests/cli/test_cli_browser_connect.py
• tests/cli/test_cli_resume_command.py
• tests/gateway/test_resume_command.py
• tests/hermes_cli/test_browser_connect_dual_stack.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_curses_arrow_keys.py
• tests/hermes_cli/test_curses_color_compat.py
• tests/hermes_cli/test_curses_ui_search.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_plugins_cmd.py
• tests/hermes_cli/test_plugins_cmd_enable_disable_nested.py
• tests/hermes_cli/test_plugins_cmd_list.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/hermes_cli/test_session_listing.py
• tests/hermes_cli/test_setup_menu_curses_migration.py
• tests/hermes_cli/test_subcommands_followup.py
• tests/tools/test_memory_tool.py
• tests/tools/test_memory_tool_schema.py
• tests/tools/test_write_approval.py
• tools/memory_tool.py
• tools/write_approval.py
• web/src/pages/PluginsPage.tsx
• website/docs/user-guide/features/memory.md

This page documents the interactive terminal chat experience provided by the Hermes Agent CLI. It covers the REPL architecture, prompt_toolkit integration, slash commands, and session management.

---

Component Architecture

The interactive chat is managed primarily by the HermesCLI class in cli.py. It orchestrates the lifecycle of a conversation by bridging user input to the AIAgent core.

1. TUI layer — Uses prompt_toolkit to manage a fixed input widget (TextArea) at the bottom of the terminal with scrolling output above cli.py60-75
2. Branding/display layer — hermes_cli/banner.py renders the ASCII logo and version labels.
3. Command layer — hermes_cli/commands.py provides a central COMMAND_REGISTRY for slash commands and tab-completion hermes_cli/commands.py64-130
4. Agent layer — AIAgent (from run_agent.py) handles the conversation loop, tool execution, and response management run_agent.py5-21

Diagram 1: Interactive Chat Component Map

Sources: cli.py55-75 hermes_cli/commands.py45-64 run_agent.py17-21 cli.py81-89

---

REPL Flow and Input Handling

The CLI uses an asynchronous REPL loop. patch_stdout() is used to ensure that background updates (like the agent's spinner or tool progress) do not corrupt the user's input line cli.py63 The system supports multi-line input via Shift+Enter or Ctrl+Enter aliases cli.py81-89

Diagram 2: Input-to-Agent Execution Flow

Sources: cli.py60-90 hermes_cli/commands.py1-9 run_agent.py136-141 gateway/run.py68-70

---

Slash Commands

Commands are defined in hermes_cli/commands.py and categorized for the help system. The COMMAND_REGISTRY is the single source of truth for the CLI, gateway, and autocomplete hermes_cli/commands.py61-64

Session & Control Commands

Command	Alias	Description
/new	/reset	Start a new session (fresh ID + history) hermes_cli/commands.py68-69
/retry	-	Retry the last message (resend to agent) hermes_cli/commands.py80
/undo	-	Remove the last user/assistant exchange hermes_cli/commands.py83-84
/rollback	-	List or restore filesystem checkpoints hermes_cli/commands.py93-94
/background	/bg	Run a prompt in a separate background session hermes_cli/commands.py102-103
/goal	-	Set a standing goal Hermes works on across turns hermes_cli/commands.py114-115
/steer	-	Inject a mid-run note after the next tool call hermes_cli/commands.py112-113

Configuration & UI Commands

Command	Alias	Description
/model	-	Switch model/provider for this session hermes_cli/commands.py137-138
/config	-	Show or edit current configuration hermes_cli/commands.py134-135
/status	-	Show session info, token totals, and recaps hermes_cli/commands.py120
/clear	-	Clear screen and start a new session hermes_cli/commands.py73-74

Sources: hermes_cli/commands.py64-140

---

Session Management and Persistence

Interactive mode ensures continuity through several mechanisms:

1. State Directory: All settings and session data are stored in ~/.hermes/ by default hermes_cli/config.py4-6
2. History: Input history is persisted in ~/.hermes_history via prompt_toolkit.history.FileHistory cli.py61
3. Context Compression: ContextCompressor monitors context usage and triggers summarization. Manual compression is available via /compress hermes_cli/commands.py91-92
4. Environment Loading: The CLI automatically loads environment variables from ~/.hermes/.env and the project root run_agent.py119-132

Runtime Provider and Model Resolution

When a session starts, the system resolves credentials and configuration using a priority chain:

1. Config Precedence: CLI arguments → config.yaml → .env → defaults hermes_cli/config.py9-15
2. API Keys: Secrets are stored in ~/.hermes/.env while behavior settings go to config.yaml hermes_cli/config.py5-6
3. Timeouts: Provider-specific and model-specific timeouts (e.g., request_timeout_seconds) are applied at runtime cli-config.yaml.example109-124
4. OAuth Management: hermes_cli/auth.py manages tokens for providers like Nous Portal and xAI hermes_cli/auth.py4-17

Diagram 3: Provider Resolution Hierarchy

Sources: hermes_cli/auth.py8-13 hermes_cli/config.py4-15 hermes_cli/models.py39-99 cli-config.yaml.example13-43