Hermes Agent - Key Files Map

Critical Path Files

These are the files you must understand to work on Hermes Agent:

Tier 1: Core Orchestration (Read These First)

File	Lines	Responsibility
`run_agent.py`	~11,500	The brain. AIAgent class, conversation loop, tool execution, error recovery, provider adapters, streaming, token tracking. Everything flows through here.
`cli.py`	~10,000	The face. Interactive TUI, slash command handling, streaming display, session management. Entry point for `hermes` command.
`gateway/run.py`	~9,800	The gateway. GatewayRunner, multi-platform message routing, session lifecycle, command handling, cron ticker. Entry point for `hermes gateway`.
`model_tools.py`	~600	Tool discovery. AST-based module scanning, async bridging, tool definition filtering. Bridge between tools and agent.

Tier 2: Agent Infrastructure

File	Lines	Responsibility
`agent/prompt_builder.py`	~800	System prompt assembly: identity, memory blocks, skills index, platform hints, behavioral nudges.
`agent/anthropic_adapter.py`	~200	Native Anthropic API: OAuth, thinking budgets, output limits, cache control headers.
`agent/auxiliary_client.py`	~200	Side-task LLM routing: auto-detects cheapest available provider for compression, vision, search.
`agent/context_compressor.py`	~300	Proactive context compression: threshold detection, middle-turn summarization, protected regions.
`agent/memory_manager.py`	~200	External memory provider orchestration: prefetch, cadence tracking, plugin bridge.
`agent/bedrock_adapter.py`	~150	AWS Bedrock Converse API adapter.
`agent/skill_utils.py`	~300	Skill matching: platform filtering, conditional activation (requires/fallback toolsets).
`hermes_state.py`	~1,300	SessionDB: SQLite WAL, FTS5, write retry with convoy prevention, session/message CRUD.
`trajectory_compressor.py`	~1,600	Context compression engine: region selection, auxiliary LLM summarization, injection.

Tier 3: Tool System

File	Lines	Responsibility
`tools/registry.py`	483	Singleton tool registry. ToolEntry dataclass, register/deregister/dispatch/get_definitions. Thread-safe with RLock.
`tools/terminal_tool.py`	~400	Shell command execution across 6 backends. Dangerous command detection, disk usage warnings.
`tools/file_tools.py`	~500	read_file, write_file, patch, search_files. Device blocking, sensitive path protection, size guards.
`tools/browser_tool.py`	~800	Browser automation (local Chromium, Browserbase, Browser Use, FireCrawl). Accessibility tree navigation.
`tools/code_execution_tool.py`	~600	Python sandbox with RPC stub generation. UDS/file-based transport. Tool call forwarding.
`tools/delegate_tool.py`	~400	Subagent spawning. Tool blocklists, depth limits, memory isolation, parallel ThreadPoolExecutor.
`tools/memory_tool.py`	~400	Persistent MEMORY.md and USER.md. Frozen snapshot pattern, injection defense, file locking.
`tools/mcp_tool.py`	~1,000	MCP client: stdio/HTTP transport, auto-reconnection, environment filtering, OSV checking, sampling.
`tools/skills_tool.py`	~1,200	Skill listing (Tier 1), viewing (Tier 2/3), progressive disclosure. Skills index for system prompt.
`tools/skill_manager_tool.py`	~500	Skill CRUD: create, edit, patch, write_file, remove_file, delete. Validation + security scanning.
`tools/approval.py`	~300	Dangerous command approval: 37 patterns, approval modes (on/auto/off), per-session state.

Tier 4: Security

File	Lines	Responsibility
`tools/tirith_security.py`	~300	Content-level threat scanning: homograph URLs, injection, obfuscation. Binary auto-install.
`tools/path_security.py`	~100	Path traversal detection, symlink-aware directory validation.
`tools/url_safety.py`	~150	SSRF prevention: private IP blocking, internal hostname blocking, fail-closed DNS.
`tools/credential_files.py`	~200	Credential registry for remote sandbox mounting. Session-scoped, path-validated.
`tools/skills_guard.py`	~200	Security scanning for skill install/create/edit. Trusted repo list, quarantine.
`SECURITY.md`	85	Threat model documentation: single-tenant, operator protection.

Tier 5: Execution Environments

File	Lines	Responsibility
`tools/environments/base.py`	~600	Abstract BaseEnvironment: execute(), cleanup() interface.
`tools/environments/local.py`	~300	Direct host execution. Env filtering, credential blocklist, session snapshots.
`tools/environments/docker.py`	~600	Docker/Podman containers. cap-drop ALL, PID limits, memory limits, resource throttling.
`tools/environments/modal.py`	~400	Modal serverless. Persistent filesystems, GPU support, auto-scaling.
`tools/environments/ssh.py`	~300	SSH remote execution. Key-based auth, command wrapping.
`tools/environments/daytona.py`	~200	Daytona cloud dev environments. SDK-based.
`tools/environments/singularity.py`	~200	HPC Singularity containers.

Tier 6: Gateway & Platforms

File	Lines	Responsibility
`gateway/platforms/base.py`	2,133	Abstract adapter. connect(), send(), handle_message(). Media methods. Message queueing.
`gateway/platforms/telegram.py`	~1,800	Telegram: Bot API, long-poll/webhook, voice memos, forum topics, typing indicators.
`gateway/platforms/discord.py`	~2,000	Discord: WebSocket, voice channels (VoiceReceiver), per-guild config, slash commands.
`gateway/platforms/slack.py`	~500	Slack: Bolt framework, Socket Mode, thread support.
`gateway/platforms/whatsapp.py`	~500	WhatsApp: Baileys Node.js bridge, E2E encryption.
`gateway/config.py`	~250	Platform enum, SessionResetPolicy, PlatformConfig, GatewayConfig.
`gateway/session.py`	~2,000	Session management: state tracking, PII redaction, expiry, memory flushing.
`gateway/delivery.py`	~250	DeliveryRouter: cron output → platform routing.
`gateway/stream_consumer.py`	~300	GatewayStreamConsumer: progressive message editing for streaming.
`gateway/hooks.py`	~150	HookRegistry: lifecycle events (startup, session, agent, command).

Tier 7: Configuration & Utilities

File	Lines	Responsibility
`hermes_constants.py`	295	Import-safe constants: home paths, environment detection (Termux/WSL/container), reasoning efforts.
`hermes_logging.py`	391	Centralized logging: session context, component routing, redacting formatter, log rotation.
`hermes_time.py`	105	Timezone-aware clock: HERMES_TIMEZONE env, config fallback, cached resolution.
`utils.py`	~200	Truthy parsing, atomic file operations (temp+fsync+replace).
`hermes_cli/config.py`	~500	Config loading: YAML + env vars + defaults merge. Profile support.
`hermes_cli/auth.py`	~300	Authentication: Nous Portal, Codex OAuth, credential refresh.
`toolsets.py`	703	Toolset definitions: ~30 presets, recursive resolution, diamond dependency detection.
`toolset_distributions.py`	365	Probability-weighted toolset sampling for batch trajectory generation.

Tier 8: Research & Batch

File	Lines	Responsibility
`batch_runner.py`	~800	Parallel batch trajectory generation. JSONL datasets, checkpointing, tool statistics.
`mini_swe_runner.py`	~700	SWE benchmark runner. Minimal agent, single terminal tool, Hermes trajectory format.
`rl_cli.py`	~400	RL training CLI. Atropos/Tinker integration, Wandb tracking, extended timeouts.
`mcp_serve.py`	~800	MCP server: expose sessions to external tools (Claude Code, Cursor).

Tier 9: Plugins & Extensions

File	Lines	Responsibility
`plugins/memory/honcho/`	-	Honcho AI dialectic user modeling integration.
`plugins/memory/mem0/`	-	Mem0 memory service adapter.
`plugins/memory/*/`	-	8 total memory provider adapters (read-only, run alongside built-in).
`acp_adapter/entry.py`	86	Agent Communication Protocol CLI entry point.
`acp_adapter/server.py`	~200	ACP agent server: HermesACPAgent, slash commands, session management.
`acp_adapter/tools.py`	~200	ACP tool kind mapping: read/edit/execute/fetch classification.

File Dependency Graph (Simplified)

                    hermes_constants.py (no deps)
                           │
                    hermes_logging.py
                           │
                    hermes_state.py
                           │
                    tools/registry.py (no deps)
                           │
              ┌────────────┼────────────┐
              │            │            │
         tools/*.py   tools/approval.py  tools/environments/*.py
              │            │            │
              └────────────┼────────────┘
                           │
                    model_tools.py
                           │
              ┌────────────┼────────────┐
              │            │            │
         agent/*.py   trajectory_    hermes_cli/
         (adapters,   compressor.py  (config,
          prompt,                     auth)
          memory)
              │
              └────────────┼────────────┐
                           │            │
                    run_agent.py     batch_runner.py
                           │         mini_swe_runner.py
              ┌────────────┼────────────┐
              │            │            │
           cli.py    gateway/run.py  acp_adapter/
                           │
                    gateway/platforms/*.py

Important Configuration Files

File	Purpose
`pyproject.toml`	Package definition, entry points, all 137 dependencies, optional extras
`.env.example`	392 lines of environment variable documentation
`cli-config.yaml.example`	894 lines: complete configuration schema with inline docs
`CONTRIBUTING.md`	661 lines: development guide, architecture overview, tool creation guide
`AGENTS.md`	471 lines: AI assistant guide for working with the codebase
`SECURITY.md`	85 lines: threat model and security architecture

Skills & Optional Skills

Built-in Skills (`skills/`, 28 categories)

Pre-installed skills that ship with the agent. Categories include coding, writing, analysis, research, etc.

Optional Skills (`optional-skills/`, 16 categories)

Official skills that are not activated by default. Discoverable via hermes skills browse --source official. Install with hermes skills install <identifier>.

Important Prompts

The system prompt is assembled in agent/prompt_builder.py. Key prompt sections:

Section	Location	Content
Core identity	`prompt_builder.py:20-50`	"You are Hermes Agent..."
Tool use guidance	`prompt_builder.py:50-140`	How to use tools effectively
Memory guidance	`prompt_builder.py:144-156`	"Save durable facts using the memory tool..."
Session search guidance	`prompt_builder.py:158-162`	"Use session_search to recall past conversations..."
Skill creation guidance	`prompt_builder.py:164-171`	"After complex tasks, save as a skill..."
Skills index	`prompt_builder.py:583-808`	Compact listing of all available skills
Platform hints	`prompt_builder.py` (varies)	CLI/Telegram/Discord formatting rules