Codebase Ownership Map
خريطة ملكية الشيفرة
What this page is, and what it holds.
“Codebase Ownership Map” from the official documentation, reproduced in full. About 3 minutes to read.
Which directories belong to which subsystem, and where the right docs entry point lives for each
Outcomes taken from this page, not a template.
- Read the table and take only the row that applies to you.
Nothing summarised away.
The documentation body below is reproduced from the official source so commands and identifiers stay exact. Each section carries a short note describing what it contains.
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.
1 question answered by this page alone.
Every option is a real identifier from the Hermes documentation. The wrong ones are real too, just from other pages.