5396da844a
- developer-guide/codebase-ownership.md (new): subsystem -> source dirs -> docs entry point map; complements the narrow CODEOWNERS proposal in #23751 (docs table only, no .github/CODEOWNERS). - contributing.md: document the .agents/checks/*.md repo-local review checklist convention (idea from goose, Apache-2.0). - integrations/index.md: "Quick connect links" table with prefilled create-your-app deep links (Telegram BotFather, Discord ?new_application=true, Slack ?new_app=1, LINE, Feishu). Poke-inspired. - guides/agent-email-address.md (new): dedicated agent mailbox via the bundled himalaya skill — setup, cron polling pattern, prompt-injection safety notes. Poke-inspired. - user-guide/features/browser.md: Chrome 136+ silently refuses --remote-debugging-port on the default user-data-dir; dedicated profile is now mandatory (diagnosis from oh-my-pi, MIT). - developer-guide/adding-providers.md: "Tool-call wire format" section linking the OpenAI chat-completions reference as the canonical shape for convert_messages/convert_tools. - user-guide/features/tools.md: shell-init pitfall — heavy/interactive rc files (nvm, TTY-expecting blocks) break non-interactive agent terminal calls; interactive-guard pattern documented (from cline, Apache-2.0). Both new pages registered in sidebars.ts. Validated with npx docusaurus build (en + zh-Hans green; zh-Hans relative-link warnings are the known pre-existing untranslated-page noise).
3.2 KiB
3.2 KiB
title, description
| title | description |
|---|---|
| Codebase Ownership Map | Which directories belong to which subsystem, and where the right docs entry point lives for each |
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.