Hermes Agent subagents are child agents that the main Hermes agent spawns with the delegate_task tool, each with a fresh conversation, its own terminal session and the parent's tools.
They let one agent split a job into parts, run those parts in parallel in the background and get back only a short summary of each.
Hermes Agent is the free, open-source agent from Nous Research, and subagents are built in, so there is nothing extra to install for the basics.
This page is the operator setup, in six steps, from the config block to live steering and the safety settings I'd switch on before letting subagents loose on a real repo.
Every setting and command below comes from Nous's own documentation.
The Hermes Agent Subagents Setup At A Glance
This is the whole operator setup on one screen.
| Step | What you do | Setting or command |
|---|---|---|
| 1 | Set the limits for width, depth and turns. | delegation.max_concurrent_children, max_spawn_depth, max_iterations |
| 2 | Choose what model the subagents run on. | delegation.model or inherit the main model |
| 3 | Write briefs that carry the full context. | The goal and context fields of delegate_task |
| 4 | Run a parallel batch and decide how results come back. | tasks=[...] plus optional delegation.independent_completions |
| 5 | Watch, steer and stop workers live. | Ctrl+T or F6 in the CLI, /agents in the TUI, the Subagents frame in Desktop |
| 6 | Switch on the safety settings for real repos. | delegation.worktree_isolation, a sandboxed backend, live transcripts |
The rest of the page takes each step in order.
What Hermes Agent Subagents Are
A subagent is a full child copy of the Hermes agent, not a one-off model call.
The docs say delegate_task spawns child agent instances with isolated context, inherited tool access and their own terminal sessions.
Each child gets a fresh conversation and works independently, and only its final summary enters the parent's context.
That last part is the big win, because a long research job no longer floods your main chat with pages of tool output.
Top-level delegations also run in the background automatically.
Hermes returns a handle straight away, so you can keep talking to the main agent, and the result posts back as a new message when the child finishes.
My video above covers this async behaviour, with the lead agent splitting jobs out to workers while you keep moving.
🔥 Want my exact Hermes Agent Subagents setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
Step 1: Set The Limits Before You Start
Subagents multiply, so set the guard rails first.
Open ~/.hermes/config.yaml and find the delegation: block.
# In ~/.hermes/config.yaml
delegation:
max_iterations: 60 # lower it for fleets of simple tasks, raise it for long investigations
That snippet comes from the docs, and the default for max_iterations is 250 tool-calling turns per child.
A child that runs out of turns comes back with exit_reason: max_iterations and truncated: true, so you can tell a budget stop from a finished task.
Width is set with delegation.max_concurrent_children.
The delegation page says up to 10 subagents run at once by default, while the configuration reference's example block shows 3, so I'd set the number explicitly rather than trust either.
If the model sends a batch bigger than the cap, Hermes returns a tool error instead of quietly dropping tasks.
Depth is set with delegation.max_spawn_depth, which defaults to 1, meaning children can't delegate further.
The docs warn that max_spawn_depth: 3 with max_concurrent_children: 3 can reach 3×3×3 = 27 concurrent leaf agents, so raise it on purpose.
There is also a separate cap for one-shot runs, delegation.oneshot_max_children, which defaults to 2 for hermes chat -q sessions.
Step 2: Choose The Subagent Model
By default, subagents use the same model as the parent, plus the parent's API key, provider configuration and credential pool.
The docs recommend a frontier planner with inexpensive workers, because subagents typically burn most of a run's tokens.
You pin that with delegation.model and an optional delegation.provider.
That topic is big enough for its own page, so I wrote a full walkthrough on the Hermes subagent model.
Step 3: Write Briefs That Carry Everything
This is where most subagent runs succeed or fail.
The docs put it in a warning box: subagents know nothing.
A child starts with a completely fresh conversation and has zero knowledge of the parent's history, earlier tool calls or anything you discussed.
Its only context is the goal and context the parent writes when it calls delegate_task.
The docs show the difference clearly.
# BAD - subagent has no idea what "the error" is
delegate_task(goal="Fix the error")
# GOOD - subagent has all context it needs
delegate_task(
goal="Fix the TypeError in api/handlers.py",
context="""The file api/handlers.py has a TypeError on line 47:
'NoneType' object has no attribute 'get'.
The function process_request() receives a dict from parse_body(),
but parse_body() returns None when Content-Type is missing.
The project is at /home/user/myproject and uses Python 3.11."""
)
There is one useful exception.
When the parent has a resolved workspace, every child's system prompt embeds the project context files, in the order .hermes.md, the AGENTS.md chain, CLAUDE.md and .cursorrules.
So a well-written AGENTS.md in your repo briefs every subagent for free.
Two more fields make briefs stronger.
An output_schema makes the child return JSON that the parent validates, with one correction turn if it doesn't match.
An images list, with up to 8 entries, forwards screenshots or mock-ups to a child that needs to see them.
🔥 Want my Hermes subagent setups done with you, step by step? Inside the AI Profit Boardroom, I've got a full Hermes Agent course plus the Agent OS, with video walkthroughs on delegation, profiles and models. You'll be learning alongside 3,400+ members with four coaching calls every week. → Get access here
Step 4: Run A Parallel Batch
A single task is one goal and one context.
A batch is a tasks list, and the docs give this example.
delegate_task(tasks=[
{"goal": "Research topic A", "context": "Focus on recent primary sources"},
{"goal": "Research topic B", "context": "Compare the leading explanations"},
{"goal": "Fix the build", "context": "Project root: /home/user/project"}
])
You don't write this code yourself, because the main agent calls the tool when it decides a job should be split.
The docs say the agent handles delegation automatically based on task complexity, but I still ask for it in plain words when I know a job splits cleanly.
By default, a batch returns one consolidated message once every task has finished.
If you'd rather act on each result as it lands, set delegation.independent_completions: true and start a new session.
With that on, tasks report as they finish, and tasks sharing the same group string come back together.
Grouping changes how results are delivered, not the order tasks run in, because all of them still run in parallel.
Step 5: Watch, Steer And Stop Workers Live
This is the part my second video covers, with the live controls in the CLI and Desktop.
The docs list the controls for each surface.
| Surface | How to inspect | How to control a worker |
|---|---|---|
| Classic CLI | Ctrl+T or F6 opens the live roster, and Enter opens a transcript tail. | s opens steering, and x then y requests a stop. |
| TUI | Ctrl+T or /agents opens the tree, and d opens rich detail. |
e steers, x stops a worker and X stops its subtree. |
| Desktop | Expand Subagents above the composer and select a worker. | Steer queues guidance and Stop requests interruption. |
Steering is queued, not instant, and the docs are careful about that.
The child picks up the guidance at its next iteration boundary, and an in-flight tool call is never cut.
If a child finishes before your steer lands, its result carries missed_steer and a note saying the steer didn't land.
Stopping a child keeps its partial work, which comes back with status="interrupted".
A follow-up message doesn't cancel a background batch, but /stop or closing the session ends it.
Step 6: Switch On The Safety Settings
Parallel children editing one repo can collide, so I'd switch on worktree isolation for code work.
delegation:
worktree_isolation: true # default: false
With it on, each child works in <repo>/.worktrees/subagent-<id> on its own branch, hermes-subagent/subagent-<id>.
Your own checkout stays untouched, and a worktree with no commits and a clean tree is pruned automatically.
The docs note it only works on git repos with the local terminal backend, and it quietly falls back to a shared folder elsewhere.
Every dispatch also writes a human-readable log per task under ~/.hermes/cache/delegation/live/<delegation_id>/, so you can tail -f a worker in real time.
Those logs are pruned after 7 days.
If your subagents run shell commands, put them behind a sandboxed backend too, and my Hermes Agent sandbox setup shows you how.
What Subagents Can't Do
Leaf subagents can't call delegate_task, clarify, memory, send_message or cronjob.
That means they can't ask you questions, write to shared memory, message anyone or schedule work in your name.
Orchestrator children keep delegate_task but keep the other blocks, and both roles keep execute_code.
There is no wall-clock timeout by default, but a child that makes no progress for 450 seconds, or 1,200 seconds inside a tool, is stopped and reported as a timeout.
A Hermes restart doesn't resume a running child, so use a cron job for work that must survive a restart.
Delegation Or execute_code?
The docs give a clear rule of thumb.
Use delegate_task when the subtask needs reasoning, judgment or multi-step problem solving.
Use execute_code when you need mechanical data processing or a scripted pipeline, because it returns only stdout and costs far fewer tokens.
Common Problems And Fixes
The subagent did the wrong thing.
The brief was probably thin, so put file paths, errors and the expected output into context.
A big batch was refused.
It was bigger than max_concurrent_children, so split it or raise the cap.
An orchestrator child didn't delegate.
max_spawn_depth is still 1, so raise it to 2.
My chat filled with "process finished" messages.
Those are suppressed by default, so check whether delegation.surface_child_process_notifications was switched on.
If you'd like a second pair of eyes on how agents fit your SEO business, you can book a free SEO strategy session with my team.
🔥 Want help setting up subagents for real client work? The AI Profit Boardroom has Hermes Agent training, the Agent OS and four weekly coaching calls where you can ask me how to brief and limit your subagents. → Join the AI Profit Boardroom
Related Reading
- Hermes subagent model shows how to pick the model your workers run on.
- Hermes advanced delegation covers model routes and profile routes.
- Hermes Agent MCP server explains how to give your agents more tools.
- Hermes Agent v0.22 covers the release line these features build on.
Also On Our Network
- 🌐 How businesses and creators use Hermes Agent subagents
- 🌐 Every Hermes subagent feature, scored with a verdict
- 🌐 The Hermes Agent subagents quick start for an Agent OS
- 🌐 Why your subagent worker model matters, measured on GoldieBench
- 🌐 Hermes swarm roles explained on the AI Profit Boardroom blog
FAQ: Hermes Agent Subagents
What are Hermes Agent subagents?
They are child agents the main agent spawns with delegate_task, each with a fresh conversation, its own terminal and the parent's tools.
Do I have to tell Hermes to use subagents?
No, because the docs say the agent delegates automatically when a task is complex enough, although you can ask for it directly.
How many Hermes subagents can run at once?
The delegation docs say up to 10 by default, and delegation.max_concurrent_children changes it.
Can Hermes subagents spawn their own subagents?
Only orchestrator children can, and only after you raise delegation.max_spawn_depth above 1.
Can I steer or stop a Hermes subagent mid-task?
Yes, through Ctrl+T or F6 in the CLI, /agents in the TUI or the Subagents frame in Desktop, and steering lands at the child's next checkpoint.
If you run an agency and want help mapping agents to your client work, you can book a free strategy session and we'll talk it through.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link-building agency, Goldie Agency, with 70+ people in Bangkok.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the book "Link Building Mastery", which covers nine link building strategies.
- I run GoldieBench, where I score AI models on real one-shot builds.
→ Get my best AI training inside the AI Profit Boardroom
Set the limits, write full briefs, watch the first batches live and switch on worktree isolation, and Hermes Agent subagents will do real work for you in parallel.
