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/ needs tests/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.