Codebase Ownership Map
Hermes is a large repository, and most contributions touch exactly one subsystem. This page maps each subsystem to its source directories and the documentation entry point you should read before changing it. Use it to find the right starting doc, the right place for a change, and the right test directory (tests mirror source: code in tools/ is tested in tests/tools/, plugins in tests/plugins/<type>/, and so on).
| Subsystem | Source directories | Docs entry point |
|---|---|---|
| Agent core (loop, transports, compression) | agent/, run_agent.py | Agent Loop, Context Compression & Caching |
| Prompt assembly | agent/prompt_builder.py, agent/system_prompt.py | Prompt Assembly |
| Model providers & transports | agent/transports/, plugins/model-providers/, hermes_cli/models.py | Adding Providers, Model Provider Plugins, Provider Runtime |
| Built-in tools | tools/ | Adding Tools, Tools Runtime |
| Messaging gateway | gateway/, plugins/platforms/ | Gateway Internals, Adding Platform Adapters |
| CLI | hermes_cli/ | Extending the CLI |
| Plugins system | plugins/ | Build a Hermes Plugin |
| Skills (bundled & optional) | skills/, optional-skills/ | Creating Skills |
| Cron / scheduled jobs | cron/ | Cron Internals |
| Session storage | hermes_state.py | Session Storage |
| Browser stack | tools/browser_tool.py, tools/browser_supervisor.py, tools/browser_cdp_tool.py | Browser Supervisor |
| Egress firewall | agent/proxy_sources/iron_proxy.py | Egress Internals |
| ACP (IDE integration) | acp_adapter/ | ACP Internals |
| Desktop app | apps/desktop/ | Desktop Plugin SDK, Worktree UI Development |
| TUI | ui-tui/, tui_gateway/ | Worktree UI Development |
| Docs site | website/ | Contributing |
| Tests | tests/, tests-js/ | Contributing → Before Submitting |
A few conventions that fall out of this map:
- Changes should stay inside their subsystem. A plugin that needs to edit core files is a design smell — widen the generic plugin surface instead (see the contribution rubric in the repository's
AGENTS.md). - Run the mirror test directory for every source directory you touch. A change to
plugins/platforms/telegram/needstests/plugins/platforms/green, not just the test file you happened to think of. - When two subsystems are involved, the narrower one owns the change. Prefer a fix in an adapter or plugin over a branch in the agent core; the core is a narrow waist, and every addition there is paid for on every API call.