Building on Hermes: pick your altitude

The whole game: pick the lightest edge that works

Over six modules you've seen every moving part. Module 1 gave you the loop. Module 3 gave you tools. Module 4 gave you skills. Module 5 gave you memory. Module 6 gave you the outward-facing edges — MCP, the gateway, cron. That's the entire machine.

So why do new builders still get stuck? Almost always for one reason: they reach for a heavy extension point when a light one would do. They write a brand-new core tool when a skill would have nailed it; they fork the loop when a plugin was the answer. The good news is that Hermes's own contributor guide — AGENTS.md — ships a literal decision tool for exactly this. It's called the Footprint Ladder, and it's the centerpiece of this module.

Remember the narrow waist — from Module 1: the core is a narrow waist; capability lives at the edges. The Footprint Ladder is just that principle turned into a checklist. The loop stays small and stable on purpose — your job as a builder is to add ability around it, at the lightest rung that does the job.

The Footprint Ladder

Here's the rule from AGENTS.md, stated plainly: always choose the highest rung — the one with the least new footprint — that correctly solves your problem. Rung 1 adds almost nothing to the system; rung 6 changes the core for everyone. Climb down only when the rung above genuinely can't do the job.

1. Extend existing code / config. Your idea is a variation of something that already exists — a new option on a tool you already have, a config tweak, a tweak to an existing skill. Zero new surface. Use when: "this is basically the thing Hermes already does, but…"
2. CLI command + skill. The capability is really config/state/infra you can express as shell commands. You add a hermes <subcommand> and a skill that teaches the model when to run it. Zero model-tool footprint (the model just runs the terminal). Examples in core: hermes webhook, hermes cron, hermes tools. Use when: a human could do it from a shell, and you mainly need to teach the agent the procedure.
3. Service-gated tool (a tool with a check_fn). A real structured tool — but one that only appears in the toolbox when its prerequisite is configured (recall Module 3's conditional tools). Costs nothing when the service isn't set up. Examples: Home Assistant tools (gated on a token), memory-provider tools. Use when: you need structured params/returns, but only some users will have the backing service.
4. Plugin. Third-party, niche, or user-specific capability that shouldn't ship in core. Lives in ~/.hermes/plugins/ or a pip package, discovered at runtime. A plugin can register tools, lifecycle hooks, platforms, even memory providers. Use when: it's substantial and self-contained, but not something every Hermes user needs.
5. MCP server (added to the catalog). A structured tool exposed over the Model Context Protocol (recall Module 6). Zero permanent core-schema footprint, and the bonus is reuse: any MCP host — not just Hermes — can call it. Use when: you're wrapping an external API/service and want it reusable beyond Hermes.
6. New core tool. The heaviest rung. Justified only when the capability is fundamental, useful to nearly every user, and genuinely unreachable via terminal, files, or an MCP server. The bar is high — think terminal, read_file, web_search. Use when: nothing lighter can express it and everyone needs it. Rare.

The shape of the advice — most ideas land on rungs 1–3. If you find yourself drafting a new core tool on day one, stop and walk back up the ladder — there's almost always a lighter rung that ships faster and breaks nothing. (Full text: Architecture docs and the repo's AGENTS.md.)

"What do I want to build?" → which rung

The ladder tells you how light to go. This table is the faster lookup — start from the thing you actually want and read across to where it lives:

Embed Hermes in your own app — the Python library

One option doesn't appear on the ladder because it's a different move entirely: instead of extending the CLI, you import the agent and drive it from your own Python. No terminal, no chat UI — Hermes becomes the engine inside your product. This is how you turn it from a tool you use into infrastructure you ship.

The shape is always the same three beats: build an agent → run a conversation → read the response.

from run_agent import AIAgent

# 1. build the agent (model + a few options)
agent = AIAgent(model="anthropic/claude-sonnet-4.6", quiet_mode=True)

# 2. run a turn — Hermes runs the full tool loop internally
result = agent.run_conversation("Summarize today's commits in this repo.")

# 3. read the answer out
print(result["final_response"])

A couple of honest caveats. run_conversation() returns a dict (final_response plus the full messages trace); there's also a simpler chat() that just returns the string. And the real AIAgent.__init__ (in run_agent.py) takes dozens of options — model, toolsets, max_iterations, memory toggles, and more. Don't memorize them; check the exact signature against the Python-library guide. The shape above is what matters and it won't change.

Plugins (briefly), and what a "hook" is

Plugins are the heavy-duty edge extension — rung 4. The build-a-hermes-plugin guide walks through a complete one with tools, hooks, data files, and skills all in a single package, dropped into ~/.hermes/plugins/ and discovered at runtime.

The word worth defining is hook:

What's a hook? — a hook is a callback you register at a specific moment in the agent's lifecycle. Hermes plugins can subscribe to events like on_session_start, on_session_end, and pre_llm_call / post_llm_call (before and after each model call), plus pre_tool_call / post_tool_call. That's how you wire in logging, metrics, guardrails, or an alert when something specific happens — without touching the loop itself.

(Heads up: Hermes uses "hook" for a few different mechanisms — plugin lifecycle callbacks, gateway event hooks, and shell hooks in config.yaml. The lifecycle-callback kind above is the one that lives inside a plugin.)

Delegation: spinning up subagents

One power tool deserves its own mention because it changes how you think about big jobs: delegation. The tools/delegate_tool.py tool lets the agent spawn isolated subagents to run workstreams in parallel — for example, researching three competitors at once and folding the summaries back together. It's the fan-out primitive. (See the delegation feature docs and delegation patterns.)

There's one fact about subagents you must internalize, or your delegations will quietly fail:

Heads up — they know nothing; spell everything out. Every subagent starts with a completely fresh context. It has none of your conversation history — not the file you're editing, not the error you're chasing, not the constraint you mentioned ten messages ago. If the child needs a file path, a stack trace, or a rule, you must pass it explicitly in the delegation prompt. A vague hand-off produces a confidently wrong answer about the wrong thing.

Two more guardrails to know: children get a restricted toolset, and by default they can't recursively delegate and can't write to shared memory (those tools are stripped from the child). So delegation is a clean one-level fan-out: parent splits the work, children do focused jobs in isolation, parent collects the summaries. Perfect for parallel research; not a way to build a recursive agent swarm.

Your starter project (do this this week)

Reading is over. The way you actually learn an agent is by shipping something small and real. So pick one idea, place it on the Footprint Ladder, and build the smallest version that works — this week, not someday.

Three concrete starters, each mapped to its rungs:

• A daily research briefing. A skill that knows how to gather and summarize what you care about (rung 1–2), fired by cron each morning, delivered to you over the gateway on Telegram. Touches skills + cron + gateway — a full lap around the codebase in one project.
• A domain-skill pack you publish. Bundle a handful of skills for a niche you know well (legal intake, recipe scaling, on-call runbooks) and share it to the Skills Hub. Pure rung 1 — and the friendliest contribution for non-coders.
• An MCP server wrapping an API you actually use. Your team's internal API, a database, a SaaS you live in. Rung 5 — structured, and reusable by any MCP host, not just Hermes.

Don't build alone — when you get stuck or ship something, the Nous Research Discord is where the practitioners are. Real feedback from people building on Hermes is where the actual wisdom lives — far more than any doc. Show up, ask, share what you made.

The series in one breath

You started with one idea and ended with a build plan. Here's the whole arc:

• Module 1 — an agent is a loop, not a chatbot; you extend it at the edges.
• Module 2 — you traced that loop line-by-line: think → call a tool → see the result → repeat.
• Module 3 — tools are the loop's hands; some are conditional, appearing only when configured.
• Module 4 — skills are procedural knowledge the model loads on demand; the lightest way to make Hermes great at something.
• Module 5 — memory turns a goldfish into a stateful product that knows you across sessions.
• Module 6 — the outward edges: MCP for structured tools, the gateway to live on Telegram/Discord, cron to run on a schedule.
• Module 7 — the Footprint Ladder: choose the lightest edge that works, then ship.

Key takeaways

• The core builder skill is choosing the right extension point — and the Footprint Ladder in AGENTS.md is the decision tool for it.
• Always pick the lightest rung that works; most ideas belong on rungs 1–3 (extend / CLI+skill / service-gated tool).
• Use the project → rung map: workflow→skill, API→MCP, users→gateway, schedule→cron, embed→library, lifecycle code→hook.
• The Python library (AIAgent from run_agent) embeds the whole loop inside your own app: build → run_conversation → read response.
• Subagents start with zero context — spell out every file, error, and constraint; they can't recurse or write shared memory.
• Pick one small idea, place it on the ladder, and ship the smallest version this week.

Quick check — you want Hermes to be excellent at triaging your team's support tickets, which live behind an internal REST API. Where on the ladder does this land — and is it one rung or two?

Answer: It's naturally two pieces. The API connection is structured and reusable, so wrap it as an MCP server (rung 5) — or a plugin (rung 4) if it's Hermes-specific. Then teach the agent the triage procedure with a skill (rung 1). Resist the urge to make this a new core tool (rung 6): it's neither fundamental nor needed by every user, and the lighter rungs ship faster and break nothing.

Pair with your AI — turn your idea into a plan before you write a line of code: "Here's what I want to build: [describe your idea in a sentence]. Walk me down Hermes's Footprint Ladder and help me place it on the lightest rung that actually works — extend existing code, CLI+skill, service-gated tool, plugin, MCP server, or new core tool. Then sketch the smallest first version I could ship this week."