Specification: Configuration and Multi-ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ System

Overview

Config loading follows a three-path system: load_cli_config() for CLICommand-Line Interface mode (includes CLICommand-Line Interface-specific defaults), load_config() for tools/setup (merges DEFAULT_CONFIG + user YAML), and direct YAML load for the gateway. All three use deep-merge to combine defaults with user overrides without requiring users to include the entire config.

Architecture

ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/-aware path resolution:
    get_hermes_home() → ~/.hermes (default) or ~/.hermes/profiles/<name> (profile)
                        ↑
                _apply_profile_override() sets HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware) before any module imports

Config loaders:
    ├── load_cli_config() — CLICommand-Line Interface mode (cli.py)
    │   └── merges CLICommand-Line Interface-specific defaults + user config.yaml
    ├── load_config() — tools/setup (hermes_cli/config.py)
    │   └── merges DEFAULT_CONFIG + user config.yaml
    └── Direct YAML — gateway runtime (gateway/run.py)
        └── reads config.yaml raw

Config sections (non-exhaustive):
    model, agent, terminal, compression, display, stt, tts,
    memory, security, delegation, smart_model_routing, checkpoints,
    auxiliary, curator, skills, gateway, logging, cron, profiles,
    plugins, honcho

Data Models

Config structure (config.yaml)

No fixed schema — sections are added to DEFAULT_CONFIG as dictionaries. New keys are auto-merged without version bumps. A _config_version field tracks schema migration needs.

ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ structure (filesystem)

~/.hermes/
    ├── config.yaml       # Default profile
    ├── .env              # Secrets (default profile)
    ├── sessions.db       # SessionA single conversation history stored in SQLite with FTS5 search store
    ├── logs/
    ├── skills/
    ├── plugins/
    ├── skins/
    └── profiles/
        ├── personal/
        │   ├── config.yaml
        │   ├── .env
        │   ├── sessions.db
        │   └── ...
        └── work/
            └── ...

Technical Decisions

Risks and Unknowns

1. Three config loaders can drift — a key may work in CLICommand-Line Interface but not in gateway or vice versa
2. GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core reads raw YAML without DEFAULT_CONFIG merge — new keys added to DEFAULT_CONFIG may not appear in gateway without explicit work
3. Deep-merge may produce unexpected results for nested structures (lists are replaced, not merged)

Out of Scope

• Cloud-synced profiles
• GUI config editor

Test Plan: Configuration and Multi-ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ System

Scope

Tests covering config.yaml loading and deep-merge, .env secrets loading, profile creation/clone/list/use, config version migration, toolset configuration, and model catalog.

Test Files

• tests/hermes_cli/test_config.py — Config loading and merge
• tests/hermes_cli/test_config_drift.py — Config drift detection
• tests/hermes_cli/test_config_validation.py — Config validation
• tests/hermes_cli/test_config_env_expansion.py — Env var expansion in config
• tests/hermes_cli/test_config_env_refs.py — Config references to env vars
• tests/hermes_cli/test_profiles.py — ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ operations
• tests/hermes_cli/test_profile_distribution.py — ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ distribution
• tests/hermes_cli/test_profile_describer.py — ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ description
• tests/hermes_cli/test_profile_export_credentials.py — Credential export
• tests/hermes_cli/test_apply_profile_override.py — ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ override
• tests/hermes_cli/test_model_catalog.py — Model catalog tests
• tests/hermes_cli/test_tools_config.py — ToolsetA named grouping of tools that can be enabled/disabled per platform (e.g., hermes-telegram, web, browser) configuration
• tests/hermes_cli/test_toolset_validation.py — ToolsetA named grouping of tools that can be enabled/disabled per platform (e.g., hermes-telegram, web, browser) validation
• tests/hermes_cli/test_models.py — Model list and filtering
• tests/hermes_cli/test_env_loader*.py — .env loading (5+ test files)

Unit Tests

• DEFAULT_CONFIG deep-merge with user config
• Config version migration
• ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ directory creation and isolation
• .env parsing and variable expansion
• Model catalog loading from provider registry

Integration Tests

• Full config loading through all three loaders (CLICommand-Line Interface, tools, gateway)
• ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/-aware HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware) resolution
• ProfileAn isolated agent instance with its own config, credentials, skills, and sessions, stored under ~/.hermes/profiles/ clone creates independent copy
• ToolsetA named grouping of tools that can be enabled/disabled per platform (e.g., hermes-telegram, web, browser) enable/disable per platform
• Config drift detection and repair

Edge Cases and Failure Scenarios

Test Infrastructure

• Temp HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware) and profile directories
• Controlled config yaml content per test
• Monkeypatched env for .env tests

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: MCPModel Context Protocol Server Integration

Architecture

MCPModel Context Protocol Tools (tools/mcp_tool.py, tools/mcp_serve.py)
    │
    ├── MCPModel Context Protocol Client (tools/mcp_client/ or tools/*mcp*.py)
    │   ├── stdio transport
    │   ├── SSE transport
    │   ├── OAuth authentication
    │   └── Circuit breaker
    │
    ├── MCPModel Context Protocol Server (mcp_serve.py)
    │   └── Serves Hermes tools as MCPModel Context Protocol tools
    │
    ├── Optional MCPModel Context Protocol Servers (optional-mcps/)
    │   ├── linear/ — Linear issue tracking
    │   ├── n8n/ — n8n workflow automation
    │   └── unreal-engine/ — Unreal Engine integration
    │
    └── MCPModel Context Protocol Config (config.yaml → tools/mcp_config/hermes_cli)
        └── Server definitions with URL, auth, transport type

Data Models

MCPModel Context Protocol Server Configuration

API Contracts

MCPModel Context Protocol follows the Model Context Protocol specification. Tools are defined using JSON Schema and called via JSON-RPCA remote procedure call protocol encoded in JSON, used between the TUI frontend and Python backend messages over the configured transport.

Technical Decisions

Risks and Unknowns

1. MCPModel Context Protocol server reliability depends on the external server — circuit breaker mitigates but does not eliminate this
2. OAuth token refresh for long-lived sessions may require re-authentication
3. MCPModel Context Protocol tool schemas are fixed at connection time — dynamic tool addition mid-session may not be reflected

Out of Scope

• Hosting MCPModel Context Protocol servers (except mcp_serve.py which serves Hermes tools)
• MCPModel Context Protocol registry or marketplace

Test Plan: MCPModel Context Protocol Server Integration

Scope

Tests covering MCPModel Context Protocol client connection, tool discovery, tool calling, transport (stdio/SSE), OAuth authentication, circuit breaker, mcp_serve.py, and optional MCPModel Context Protocol server functionality.

Test Files

• tests/tools/test_mcp_tool.py — Core MCPModel Context Protocol tool calling
• tests/tools/test_mcp_tool_401_handling.py — MCPModel Context Protocol auth error handling
• tests/tools/test_mcp_tool_session_expired.py — SessionA single conversation history stored in SQLite with FTS5 search expiry handling
• tests/tools/test_mcp_cancelled_error_propagation.py — Cancellation propagation
• tests/tools/test_mcp_capability_gating.py — Capability gating
• tests/tools/test_mcp_circuit_breaker.py — Circuit breaker pattern
• tests/tools/test_mcp_client_cert.py — Client certificate auth
• tests/tools/test_mcp_dynamic_discovery.py — Dynamic tool discovery
• tests/tools/test_mcp_elicitation.py — MCPModel Context Protocol tool elicitation
• tests/tools/test_mcp_oauth_*.py — OAuth flow tests (4+ files)
• tests/tools/test_mcp_probe.py — Server probing
• tests/tools/test_mcp_sse_transport.py — SSE transport
• tests/tools/test_mcp_stdio_init_timeout.py — Stdio init timeout
• tests/tools/test_mcp_stability.py — Stability under load
• tests/tools/test_mcp_parked_self_probe.py — Self-probe behavior
• tests/tools/test_mcp_utility_capability_gating.py — Utility gating
• tests/hermes_cli/test_mcp_*.py — MCPModel Context Protocol CLICommand-Line Interface commands (5+ files)

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: ACPAgent Communication Protocol Protocol (IDEIntegrated Development Environment Integration)

Architecture

ACPAgent Communication Protocol Adapter (acp_adapter/)
    │
    ├── ACPAgent Communication Protocol Server (acp_adapter/server.py)
    │   ├── WebSocket endpoint
    │   ├── HTTP endpoint
    │   └── JSON-RPCA remote procedure call protocol encoded in JSON, used between the TUI frontend and Python backend message handling
    │
    ├── ACPAgent Communication Protocol Registry (acp_registry/)
    │   └── Server catalog and discovery
    │
    └── Editor integrations
        ├── VS Code extension protocol
        ├── Zed extension protocol
        └── JetBrains plugin protocol

Data Models

ACPAgent Communication Protocol Message

Code Context

API Contracts

ACPAgent Communication Protocol follows the JSON-RPCA remote procedure call protocol encoded in JSON, used between the TUI frontend and Python backend 2.0 specification over WebSocket transport. Methods include query submission, file context updates, and tool execution requests.

Technical Decisions

Risks and Unknowns

1. Editor-specific protocol differences may require adapter customization per editor
2. Large project context may exceed token limits when sent as agent context
3. ACPAgent Communication Protocol adoption depends on editor ecosystem support

Out of Scope

• Full file system access from editor
• Multi-editor collaboration session

Test Plan: ACPAgent Communication Protocol Protocol (IDEIntegrated Development Environment Integration)

Scope

Tests covering ACPAgent Communication Protocol adapter server, registry maintenance, editor protocol compatibility, and authentication.

Test Files

• tests/hermes_cli/test_copilot_*.py — Copilot/ACPAgent Communication Protocol integration tests (5+ files)
• tests/acp/ — ACPAgent Communication Protocol-specific test directory
• tests/acp_adapter/ — ACPAgent Communication Protocol adapter tests
• tests/agent/test_copilot_acp_client.py — ACPAgent Communication Protocol client tests
• tests/agent/test_copilot_acp_deprecation.py — ACPAgent Communication Protocol deprecation handling

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Trajectory and Data Generation

Architecture

Data Generation Pipeline
    │
    ├── Batch Runner (batch_runner.py)
    │   ├── Parallel agent execution
    │   ├── Checkpoint system
    │   └── Result collection
    │
    ├── Trajectory Compressor (trajectory_compressor.py)
    │   ├── Configurable compression levels
    │   ├── Tool-call structure preservation
    │   └── Token optimization
    │
    ├── SWE-bench Runner (mini_swe_runner.py)
    │   └── SWE-bench evaluation harness
    │
    └── Configuration (datagen-config-examples/)
        └── Example configs for common setups

Data Models

Batch Config

Compressed Trajectory

Technical Decisions

Risks and Unknowns

1. Batch runner with hundreds of parallel agents requires significant API budget
2. Trajectory compression quality varies by conversation length and complexity
3. SWE-bench evaluation requires code execution sandbox

Out of Scope

• Training model weights from generated data
• Dataset hosting or distribution

Test Plan: Trajectory and Data Generation

Scope

Tests covering batch runner, trajectory compression, and checkpointing functionality.

Test Files

• tests/test_batch_runner_checkpoint.py — Batch runner checkpointing
• tests/run_agent/test_codex_app_server_compaction.py — Trajectory compression

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Internationalization

Architecture

Internationalization (locales/)
    │
    ├── en/ — English (default)
    ├── es/ — Spanish
    ├── zh-CN/ — Chinese (Simplified)
    └── <locale>/ — Future locales

Data Models

Locale file format

Technical Decisions

Risks and Unknowns

1. Maintainability of translations across rapid development — new strings may not be translated promptly
2. Not all CLICommand-Line Interface output is currently internationalized (incremental adoption)

Out of Scope

• Runtime language switching (requires agent restart)
• Machine translation of missing strings

Test Plan: Internationalization

Scope

Tests covering locale string loading and locale-aware CLICommand-Line Interface output.

Test Files

• Tests for locale loading are integrated into CLICommand-Line Interface and config test suites
• No dedicated internationalization test module identified

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: KanbanA durable multi-agent work queue (SQLite-backed board) for distributing tasks across profiles/workers Multi-AgentThe AI runtime (AIAgent class) that drives conversation, tool calling, and memory Work Queue

Overview

KanbanA durable multi-agent work queue (SQLite-backed board) for distributing tasks across profiles/workers is implemented as three cooperating layers: a CLICommand-Line Interface parser and SQLite-backed store (hermes_cli/kanban.py), a kanban_* toolset for agent workers (tools/kanban_tools.py), and a long-lived dispatcher embedded in the gateway (or run standalone via hermes kanban daemon). Boards live in a directory tree where each board has its own SQLite database, workspaces directory, and (when run standalone) dispatcher.

Architecture

User / orchestrator agent
    │  kanban_create / kanban_link / kanban_comment ...
    v
kanban_* tools (tools/kanban_tools.py)        hermes kanban CLICommand-Line Interface (hermes_cli/kanban.py)
    │                                                 │
    └───────────────►  SQLite board store (per-board DB)
                              │
                              v
                     Dispatcher (embedded in gateway, default)
                     │  - reclaim stale claims (60s tick)
                     │  - promote ready tasks
                     │  - atomically claim + spawn assigned profile
                     │  - auto-block after failure_limit
                     │
                     └──► Worker agent (spawned, HERMES_KANBAN_BOARD pinned)
                              │  kanban_heartbeat / kanban_complete / kanban_comment
                              v
                     BoardThe hard isolation boundary of the kanban system — workers are spawned with a pinned board and cannot see others DB (claim released, run history appended)

Data Models

BoardThe hard isolation boundary of the kanban system — workers are spawned with a pinned board and cannot see others

Task

API Contracts

The model-facing contract is the kanban_* toolset:

Profiles that explicitly enable the kanban toolset outside a dispatcher-spawned task also get kanban_list and kanban_unblock for board routing.

Sequences

Dispatch tick (default 60s)

Dispatcher tick
    → reclaim stale claims (SIGTERM then SIGKILL runaway workers)
    → promote ready tasks (respect dependency links)
    → atomically claim a task
    → spawn the assigned profile (HERMES_KANBAN_BOARD pinned)
    → worker heartbeats keep the claim alive
    → worker completes → run history recorded → next promotion

Idempotent create (automation / webhooks)

kanban_create(dedup_key="K")
    → existing task with key K? → return its id (no duplicate)
    → otherwise create a new task with key K

Technical Decisions

Risks and Unknowns

1. Single-host dispatcher limits multi-machine collaboration (out of scope for now)
2. Auto-block heuristics may block a task a human could complete manually — operators can unblock
3. Attachment storage lives in the board directory, so hard-deleting a board removes attachments

Out of Scope

• Cross-machine / distributed boards
• Task dependency DAG execution (links exist, but the dispatcher promotes ready tasks; complex DAG scheduling is future work)
• Fine-grained per-user ACLs beyond the board/tenant isolation model

Test Plan: KanbanA durable multi-agent work queue (SQLite-backed board) for distributing tasks across profiles/workers Multi-AgentThe AI runtime (AIAgent class) that drives conversation, tool calling, and memory Work Queue

Scope

Tests covering the kanban CLICommand-Line Interface, the SQLite board store, the worker/orchestrator toolset, dispatcher behavior (claim/reclaim/promotion/spawn), board isolation, attachments, comment injection, model overrides, and dashboard integration.

Test Files

• tests/tools/test_kanban_tools.py — Worker/orchestrator kanban_* toolset
• tests/tools/test_kanban_redaction.py — Sensitive-data redaction in kanban tool output
• tests/tools/test_delegate_kanban_isolation.py — Subagent/worker board isolation
• tests/tools/test_kanban_comment_injection.py — Comment injection from worker environment
• tests/plugins/test_kanban_worker_runs.py — Worker run lifecycle through the dispatcher
• tests/plugins/test_kanban_board_project_api.py — BoardThe hard isolation boundary of the kanban system — workers are spawned with a pinned board and cannot see others and project APIs
• tests/plugins/test_kanban_dashboard_plugin.py — Dashboard plugin wiring
• tests/plugins/test_kanban_attachments.py — File attachment lifecycle
• tests/plugins/test_kanban_estimate.py — Task effort estimation
• tests/plugins/test_kanban_model_override.py — Per-task model override propagation

Unit Tests

• BoardThe hard isolation boundary of the kanban system — workers are spawned with a pinned board and cannot see others creation, listing, switching, renaming, archiving, and deletion
• Task create (including dedup-key idempotency), show, edit, assign, block, complete, archive
• Dependency link/unlink behavior
• Attachment add/list/remove

Integration Tests

• Worker spawned for board A cannot see board B (isolation via pinned env)
• Comment injection from the worker environment into a task
• Model override reaching the spawned worker
• Dashboard plugin loading against a real board store

Edge Cases and Failure Scenarios

Test Infrastructure

• Per-board SQLite fixtures in temp directories
• Mock gateway/dispatcher state for tick-driven tests
• Isolated HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware) per test (no writes to ~/.hermes/)

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Observability

Overview

Observability is delivered through three cooperating mechanisms: (1) the observer-hook contract, which plugins use to reconstruct execution; (2) a Prometheus-format /v1/metrics HTTP export for gateway runtime health; and (3) the Langfuse and NeMo Relay plugins plus shared-metrics scripts that consume both. The contract is backend-neutral and versioned, so any vendor can integrate without core changes.

Architecture

AgentThe AI runtime (AIAgent class) that drives conversation, tool calling, and memory / GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core runtime
    │  emits lifecycle events (session, LLM, API, tool, approval, subagent)
    v
Observer hook contract (docs/observability/README.md)
    │  correlation IDs · sanitized payloads · timing/status/error · hermes.observer.v1
    │
    ├──► plugins/observability/langfuse/  (traces)
    ├──► plugins/observability/nemo_relay/ (traces + shared metrics)
    │
GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core runtime health
    │  /v1/metrics (Prometheus text format)
    v
scripts/observability/ (OpenTelemetry-style capture collectors, health export probe)

Data Models

Observer lifecycle events

Every event carries correlation IDs (session/turn/task/api_request), a timestamp, status, timing, and sanitized payload. Callbacks accept **kwargs so new fields are additive and backward-compatible.

GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core metrics (/v1/metrics)

API Contracts

GET /v1/metrics

Response (200 OK): Prometheus text format (content-type text/plain). Body lists gateway gauges, per-platform up/degraded gauges, and cron scheduler gauges.

Error Responses: 401 when the metrics endpoint requires auth; otherwise standard HTTP errors.

Sequences

PluginA Python package that extends the agent via hooks, tools, CLI subcommands, or provider profiles trace flow

AgentThe AI runtime (AIAgent class) that drives conversation, tool calling, and memory turn
    → pre_api_request hook (api_request_id generated)
    → post_api_request hook (status, duration, sanitized body)
    → pre_tool_call / post_tool_call hooks
    → Langfuse / NeMo Relay plugin serializes to its backend
    → correlation ids join all events into one trace

GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core metrics scrape

Prometheus (or operator)
    → GET /v1/metrics
    → gateway emits runtime gauges
    → platform adapters report up/degraded
    → cron scheduler reports heartbeat

Technical Decisions

Risks and Unknowns

1. Payload sanitization must keep up with new sensitive fields (secrets, tokens, PII)
2. OpenTelemetry-style collectors are scripts, not a maintained core integration — coverage may lag
3. /v1/metrics authentication posture (who may scrape) is deployment-dependent

Out of Scope

• A built-in metrics database or dashboard UI (Langfuse/NeMo Relay/collectors fill this role)
• Behavior-changing instrumentation (observers report, they do not modify)
• Any single-vendor binding in the core tree

Test Plan: Observability

Scope

Tests covering the observer-hook contract events and correlation, payload sanitization, fail-open behavior, the /v1/metrics gateway export, and the Langfuse / NeMo Relay plugin consumers and shared-metrics scripts.

Test Files

• tests/plugins/test_langfuse_plugin.py — Langfuse plugin trace delivery against the observer contract
• tests/plugins/test_nemo_relay_plugin.py — NeMo Relay plugin trace + shared-metrics delivery
• tests/scripts/test_smoke_nemo_relay_shared_metrics.py — Shared-metrics path smoke test

Unit Tests

• Observer hook callback registration and invocation for each lifecycle event
• Correlation ID propagation across event types
• Payload sanitization before hook delivery

Integration Tests

• Langfuse plugin consuming real lifecycle events from an agent turn
• NeMo Relay plugin consuming the contract and the shared-metrics path
• GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core /v1/metrics endpoint emitting runtime gauges

End-to-End Tests

• A full agent turn with API request + tool call produces a joinable trace through the Langfuse consumer

Edge Cases and Failure Scenarios

Test Infrastructure

• Fake agent/turn fixtures emitting observer events
• Temp HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware) isolation
• Mock Langfuse / NeMo Relay backends (no live network)

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Multi-Platform CLICommand-Line Interface

Overview

The CLICommand-Line Interface is built on prompt_toolkit for input with autocompletion and Rich for output rendering. Commands are defined centrally in the COMMAND_REGISTRY in hermes_cli/commands.py, which all downstream consumers (CLICommand-Line Interface dispatch, gateway dispatch, Telegram menu, Slack mapping, autocomplete) derive from automatically.

Architecture

prompt_toolkit REPL
     │
     ├── text input ──→ process_text()
     │                      │
     │               ┌────┴────────┐
     │               │ Text input  │→ AIAgent.chat()
     │               │             │
     │               │ Slash cmd   │→ process_command()
     │               └─────────────┘
     │                      │
     │               resolve_command(name)
     │                      │
     │               matched CommandDef
     │                      │
     │               handler method
     │
     └── autocomplete ──→ SlashCommandCompleter
                                  │
                           queries COMMAND_REGISTRY

Data Models

CommandDef

SkinConfig

API Contracts

No external API contracts. The CLICommand-Line Interface communicates with AIAgent through direct method calls.

Technical Decisions

Risks and Unknowns

1. The classic CLICommand-Line Interface has grown to ~16k LOC — god-file refactoring is needed but risky for an active codebase
2. prompt_toolkit's patch_stdout conflicts with ANSI escape codes used by the spinner

Out of Scope

• The TUITerminal User Interface (ui-tui/) is a separate surface, not part of the classic CLICommand-Line Interface
• GUI elements beyond terminal rendering

Test Plan: Multi-Platform CLICommand-Line Interface

Scope

Tests covering HermesCLI class, slash command registry and dispatch, skin/theme system, banner rendering, autocomplete, and CLICommand-Line Interface configuration.

Test Files

• tests/hermes_cli/ — 300+ test files covering all CLICommand-Line Interface subsystems
• tests/hermes_cli/test_commands.py — Slash command dispatch tests
• tests/hermes_cli/test_skin_engine.py — Skin/theme engine tests
• tests/hermes_cli/test_banner.py — Banner rendering tests
• tests/hermes_cli/test_completion.py — Autocomplete tests
• tests/hermes_cli/test_cli_output.py — CLICommand-Line Interface output formatting tests
• tests/hermes_cli/test_hooks_cli.py — CLICommand-Line Interface hook tests
• tests/hermes_cli/test_tools_config.py — Tool configuration tests

Unit Tests

• CommandDef registry and resolution
• Skin config loading and merging
• Banner rendering with skin colors
• Path completion logic
• Slash command argument parsing

Integration Tests

• Full CLICommand-Line Interface startup and command dispatch
• Skin switching via /skin command
• Configuration loading from config.yaml
• GatewayThe asyncio-based service that manages messaging platform adapters and routes messages to the agent core command compatibility

End-to-End Tests

• test_cli_skin_integration.py — Skin engine integration
• test_cli_file_drop.py — File drop handling

Edge Cases and Failure Scenarios

Test Infrastructure

• pytest with temp HERMES_HOMEThe base directory for an agent instance's config, state, skills, logs, etc. (profile-aware)
• Mock stdin/stdout for CLICommand-Line Interface interaction testing
• Subprocess-per-test-file isolation

Coverage Matrix

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations