dev tutorial · reference
Codebase map & cheat sheet
The "where do I edit X?" companion — key files, your data dir, and the commands you'll actually use.
This is a reference, not a lesson. Skim it, don't read it top-to-bottom. It's built from tables so it prints cleanly — keep it open in a tab while you work and jump to whichever section answers your question.
Two locations, always
Everything in Hermes lives in one of two places. Keep them straight and the rest of the map falls into place:
| Location | What it is |
|---|---|
the repo (your clone) | The program — the agent's source code. Read it to understand the engine; edit it to contribute upstream or add a built-in tool. |
~/.hermes/ | Your data — config, secrets, memories, skills, scheduled jobs, and the conversation database. This is where most of your hand-authored extensions live. |
The repo — top-level folders & key files
The engine is small on purpose (the "narrow waist" principle). These are the files worth knowing by name:
| Path | What it does |
|---|---|
run_agent.py | The AIAgent class — the agent object you construct and drive. The front door to the whole system. |
agent/conversation_loop.py | The core turn loop: think → tool → result → repeat. The literal heartbeat (the agent loop). |
agent/turn_context.py | Per-turn setup — sanitizes input and builds the system prompt for that turn. |
agent/tool_executor.py | Runs the model's tool calls (sequential or concurrent) and returns results to the loop. |
agent/prompt_builder.py | Assembles the system prompt, including the skills index the model sees. |
agent/context_compressor.py | Summarizes old history when the context window fills up so the loop can keep going. |
agent/memory_manager.py / agent/memory_provider.py | Memory syncing and the pluggable memory backends (memory & learning). |
agent/curator.py | Background skill maintenance — the "self-improving" curator (skills). |
model_tools.py | Dispatches a model's function call to the right tool implementation. |
tools/ | All built-in tools — each one self-registers (tools & toolsets). |
tools/registry.py | The tool registry and registry.register() — how a tool announces itself. |
tools/approval.py | Dangerous-command approval and safety gating. |
tools/delegate_tool.py | Spawns subagents to hand off scoped subtasks. |
tools/memory_tool.py, session_search_tool.py, skill_manager_tool.py, mcp_tool.py | Notable tools: durable memory, full-text search over past sessions, skill management, and the MCP bridge. |
toolsets.py | Toolset (tool-bundle) definitions — which tools ship together (tools & toolsets). |
providers/base.py | Provider profiles — the model-backend abstraction that makes Hermes model-neutral. |
agent/*_adapter.py | Per-provider adapters (Anthropic, Gemini, Bedrock, …) that translate to each backend's API. |
gateway/ | The messaging gateway plus per-platform adapters (Telegram, Discord, …) (MCP, gateway & cron). |
cron/ | The scheduler — recurring jobs (MCP, gateway & cron). |
skills/ | Skills bundled with the repo (vs. the ones you write in ~/.hermes/skills/). |
plugins/ | The plugin system — the heaviest, most powerful extension point (building on Hermes). |
mcp_serve.py | Run Hermes itself as an MCP server so other agents can call it. |
cli.py / hermes_cli/ | The CLI entrypoint and the terminal UI you type into. |
hermes_state.py | SQLite session storage — the read/write layer over state.db. |
AGENTS.md / CONTRIBUTING.md | Architecture philosophy (the "bible") and dev-setup instructions. Read before contributing. |
Your data — ~/.hermes/
This directory is created by hermes setup. It survives upgrades, and most of your customization lives here:
| Path | What's there |
|---|---|
config.yaml | Settings — provider, model, enabled tools, mcp_servers, and more. |
.env | Secrets and API keys. Never commit this. |
memories/MEMORY.md & memories/USER.md | Durable memory and the agent's model of you (memory & learning). |
skills/ | Your skills — both hand-written and the ones the agent writes for itself (skills). |
cron/jobs.json & cron/output/ | Scheduled-job definitions and the captured results of each run (MCP, gateway & cron). |
state.db | The SQLite database of all conversations — full-text searchable. |
plugins/ | Your local plugins (building on Hermes). |
Essential commands
Run these in your terminal. The slash commands work inside a Hermes session:
| Command | What it does |
|---|---|
hermes | Start chatting in the terminal UI. |
hermes setup | One-time wizard — pick a provider and model, create ~/.hermes/. |
hermes setup --portal | Same wizard, but log in to Nous Portal via OAuth to cover all keys under one subscription. |
hermes model | Switch the active model — no code change (what Hermes is). |
hermes tools | List and toggle the tools the agent can use (tools & toolsets). |
hermes skills | List and manage skills (skills). |
hermes gateway setup | Connect a messaging platform — Telegram, Discord, etc. (MCP, gateway & cron). |
hermes gateway start | Run the gateway so the agent lives on those platforms. |
hermes mcp serve | Expose Hermes as an MCP server for other agents to call. |
hermes doctor | Diagnose your install — checks config, keys, and dependencies. |
hermes update | Update Hermes to the latest version. |
| Slash command (in-session) | What it does |
|---|---|
/tools | Show the toolbox the model can reach for right now. |
/skills | Show the procedural knowledge it can load on demand. |
/<skill-name> | Invoke a specific skill directly. |
/model | Switch models mid-conversation. |
/new | Start a fresh conversation. |
/compress | Manually summarize history to free up context. |
/usage | Show token/cost usage for the session. |
"I want to… → start here"
The fastest route from an intention to the right file or command. When in doubt, prefer the lighter option (skill or MCP over a code change):
| Goal | Where to look |
|---|---|
| Teach it a workflow | Write a Skill in ~/.hermes/skills/ (skills). |
| Add a brand-new ability | A tool in tools/ + toolsets.py (tools & toolsets) — or prefer an MCP server or skill first. |
| Connect an external service | An MCP server in config.yaml under mcp_servers (MCP, gateway & cron). |
| Ship to Telegram / Discord | hermes gateway setup (MCP, gateway & cron). |
| Automate a recurring task | A cron job (MCP, gateway & cron). |
| Change the model | hermes model / /model (what Hermes is). |
| Embed it in my own app | Import AIAgent from run_agent.py (building on Hermes). |
| Make it remember something | Memory — MEMORY.md / USER.md (memory & learning). |
Reading order for the engine
If you want to understand how the loop actually works by reading source, go in this order — each file hands off to the next:
run_agent.py --> the AIAgent you construct
|
v
agent/conversation_loop.py --> the turn loop (the heartbeat)
|
v
agent/tool_executor.py --> how tool calls get run
|
v
tools/registry.py --> how a tool registers itself
|
v
toolsets.py --> how tools are bundled
|
v
agent/prompt_builder.py --> what the model is actually toldA handy habit — Stuck on "where would I even change this?" Open this page, scan the "I want to…" section, then jump to the linked module. The map is meant to be the first thing you check, not the last.
Keep in your head
- Repo = program,
~/.hermes/= your data. Almost every question reduces to "which one?" - The engine lives in
run_agent.py+agent/; capability lives intools/,skills/, andplugins/. - Lighter is better: skill → MCP → tool → plugin, in that order of preference.
- When lost, start at the "I want to…" section and follow the module link.