Spawning Claude Code as a Hermes Subagent
Hermes ships with a bundled skill that teaches it to delegate heavy coding work to Claude Code. Here is how the delegate_task() pattern works in practice.
One of the most useful patterns in Hermes is something that sounds strange at first: spawning Claude Code as a subagent. You have a server-side autonomous runtime — why would it call out to an IDE-centric coding assistant? Because Claude Code is genuinely good at coding work and Hermes does not need to reinvent it. The right move is to let each tool do what it does best.
The bundled skill at skills/autonomous-ai-agents/claude-code/SKILL.md inside the Hermes repo teaches this pattern. When Hermes sees a task that fits — "refactor this module," "write tests for this function," "implement this feature across several files" — it uses delegate_task() to hand the work off to Claude Code, waits for completion, then inspects the result. This post walks through why you would set this up, when it pays off, and how the handoff works.
Key Takeaways
- Hermes ships a bundled skill at
skills/autonomous-ai-agents/claude-code/SKILL.mdthat teaches it how to delegate to Claude Code. - Delegation uses
delegate_task(), which spawns a Claude Code process from Hermes and waits for the result. - Two transport mechanisms:
claude -p "prompt"print mode for stateless work, tmux-backed PTY for interactive sessions. - Credentials are shared — Hermes reads Claude Code's credential store directly, so Claude Pro/Max OAuth is reused.
- The pattern works well for "Hermes plans, Claude Code implements, Hermes reviews" workflows.
- Overhead is real — delegation costs a process spawn and a new context window, so reserve it for work that justifies the setup.
- For transport-level detail on print mode vs tmux, see Print Mode vs Tmux: Hermes Orchestrates Claude Code.
Why Delegate At All
Hermes has 47 built-in tools and can absolutely write code directly. It runs on claude-sonnet-4-6 by default and has file I/O, shell, and testing tools. So why offload to Claude Code?
Three reasons.
Tooling density. Claude Code has specialized coding tools — project-aware file editing, diff-first workflows, integrated linters, test runners wired to its tool harness — that Hermes has not re-implemented. For a multi-file refactor, Claude Code is simply more efficient.
Context scoping. Claude Code is project-scoped. It loads CLAUDE.md, understands the repo layout, and keeps its context focused. Hermes's context might already be full of skill definitions, memory notes, and conversation state from other tasks. Handing a self-contained coding job to a fresh Claude Code subprocess gives it a clean context window to work in.
Parallelism. Hermes can spawn multiple Claude Code subprocesses in parallel for independent workstreams. You can have three refactors happening at once, with Hermes as the coordinator. See Parallel Workstreams: Multiple Claude from Hermes for the scaling pattern.
When It Is Worth It
Not every coding task needs delegation. Spawning a subprocess has a fixed cost — the process start, loading Claude Code's own context, the tool negotiation. For a one-line fix, just let Hermes do it inline.
The threshold I use: delegate when the task is multi-step, multi-file, or stateful. Examples:
- Refactor a module across 5+ files
- Add a feature that touches models, migrations, and API routes
- Write an integration test that requires understanding the whole service
- Port a library from one framework to another
- Implement a PRD end-to-end
Everything smaller than that, Hermes handles in-process.
The Handoff Mechanics
The bundled Claude Code skill makes delegate_task() available to Hermes. The call looks approximately like this:
# Conceptual — actual call is made by the agent through the skill
delegate_task(
target="claude-code",
prompt="Refactor auth/middleware.py to use the new TokenValidator class. "
"Update all call sites. Run the tests. Return a summary of changes.",
working_directory="/home/user/projects/billing-api",
mode="print", # or "tmux"
timeout=600,
)
The skill instructs Hermes on how to build the prompt, which working directory to use, and which mode to pick. Print mode is a single claude -p "prompt" invocation that returns Claude Code's final output as stdout. Tmux mode opens a persistent session that Hermes can talk to turn-by-turn. For the decision matrix between them, see Print Mode vs Tmux: Hermes Orchestrates Claude Code.
On credentials: Hermes reads Claude Code's own credential store, so you do not pass any API keys when delegating. If you already log into Claude Code with Pro or Max OAuth, Hermes uses the same session. This is also why the Running Hermes on Claude Sonnet 4.6 setup works without extra configuration.
A Concrete Example
Here is a workflow I actually use. A Telegram message arrives at Hermes at 10pm:
Refactor the rate-limiter in the
billing-apirepo to use Redis instead of in-memory. Keep the public API the same. Add tests. Open a draft PR.
Hermes does three things.
Step 1: Plan. Hermes uses its own reasoning to break the task down. It writes a plan to memory:
# Plan: Redis rate-limiter port
1. Read current implementation (auth/rate_limiter.py)
2. Verify public interface (public methods, signatures)
3. Implement Redis backend (new RedisRateLimiter class)
4. Keep old in-memory class as fallback
5. Update factory function to pick backend from env
6. Port tests to cover both backends
7. Run full test suite
8. Open PR with summary
Step 2: Delegate. Hermes spawns Claude Code with the plan embedded in the prompt:
claude -p "Implement the following plan in /home/user/projects/billing-api. \
Return a summary of files changed and test results when done.
<plan omitted for brevity>"
Claude Code, running in the billing-api directory, has access to CLAUDE.md, the repo, and its own tools. It does the implementation, runs the tests, and prints a summary to stdout.
Step 3: Review. Hermes reads Claude Code's output, checks the test results, runs git diff itself to verify, and then either opens the PR or flags issues back to the user:
PR #287 opened. 4 files changed, 312 additions, 89 deletions. All 74 tests pass. Rate-limiter now backed by Redis via RATE_LIMITER_BACKEND=redis env var. In-memory backend preserved as fallback.
This gets pushed back to Telegram. I read it in the morning.
The key thing is that Hermes never had to be a great coder to make this work. It just had to be a reasonable planner and a good reviewer, and it leaned on Claude Code for the bit it is worse at. That is the whole value proposition of delegation.
What The Bundled Skill Does For You
The skills/autonomous-ai-agents/claude-code/SKILL.md skill is doing a lot of lifting. It encodes:
- When to delegate (the multi-step / multi-file / stateful heuristic)
- How to construct the prompt (project context, explicit return format)
- Which mode to use (print for one-shot, tmux for iterative)
- How to handle timeouts and partial failures
- How to parse Claude Code's output back into something Hermes can act on
You do not have to write any of that. You install Hermes, the skill is there, and delegation just works.
Pitfalls
A few things to watch out for.
Print mode discards Claude Code's context on exit. If your task needs to remember what Claude Code did in turn 3 at turn 8, use tmux mode instead. Print mode is for tasks that can be expressed as a single prompt.
Working directory matters. Claude Code loads its CLAUDE.md from the working directory. Pass the correct working_directory argument or Claude Code will be operating in the wrong project context.
Test the full loop locally before scheduling. If you set up a Hermes cron job that delegates to Claude Code, the first run should be manual. Delegation chains have a lot of moving parts and debugging failed cron deliveries at 3am is not fun.
Cost stacking. You are now running two LLM-powered agents for one task. The token cost is not linear — Hermes plus Claude Code will use more tokens than Hermes alone. For scheduled jobs, see Cost Control: Hermes Max-Turns, Budget, Fallback.
When NOT to Delegate
If you are sitting at your keyboard and about to open Claude Code anyway, just open Claude Code. Delegation through Hermes makes sense when the task is happening away from you — on a schedule, from a messaging gateway, as part of a larger autonomous workflow. Human-in-the-loop coding should stay in the IDE. See Hermes vs Claude Code: When to Use Which for the broader positioning.