Christmas Came Early: Async Subagents in Claude Code

Why I stayed up until 2am testing the biggest Claude Code update in a month...

On December 10th, Claude Code shipped a small line in the release notes:

Agents and bash commands can run asynchronously and send messages to wake up the main agent.

No screenshots. No launch blog. Easy to miss.

But it quietly changed the way I work.

Not because subagents are new, they aren’t, but because waiting is no longer the default.

Until now, even when you used subagents, your main thread was still blocked. You’d spawn one, then sit there until it finished. Background agents helped a bit, but under the hood everything was still serialized.

That changed yesterday. Multiple agents can now run in parallel. And more importantly, they can wake your main thread when something actually needs attention.

That flips the mental model.

My main Claude thread is no longer where work happens.
It’s where work is assigned, monitored, and coordinated.

Everything else can run in parallel.

---

What We’re Building Toward

By the end of this guide, you’ll go from “what’s a subagent?” to running background routines that monitor, analyze, and coordinate, while your main thread stays free for the work that actually needs your attention.

We’ll go step by step:

• Your first subagent: create and run one in under two minutes

• Background execution: launch it async and keep working

• Multiple agents: run several in parallel

• Coordination: agents that report back and suggest next actions

---

Level 1: Your First Subagent

There are two ways to create a subagent.

The fast way:
Type /agents in Claude Code and follow the prompts.

The manual way:
Create a markdown file in:

• .claude/agents/ (project-specific), or

• ~/.claude/agents/ (global)

Here’s a dead-simple example:

---
name: code-reviewer
description: Reviews code for issues. Use after making changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a code reviewer. When invoked, review the most recent changes for:
- Bugs or logic errors
- Missing error handling
- Code style issues

Be concise. Prioritize by severity.

Save this as code-reviewer.md. Restart Claude Code.

Now just tell Claude:

> Have the code-reviewer look at my recent changes

That’s it. You have a subagent.

---

Level 2: Background Execution

Here’s where async starts to matter.

Instead of blocking on the result:

> Run code-reviewer in the background while I keep working on the auth module

Your main thread stays free. The agent runs. When it’s done, it can wake you up with its findings.

This sounds small. It isn’t, because waiting used to be the bottleneck.

Before:

• Ask for a review

• Wait

• Read

• Continue

After:

• Ask for a review

• Start the next task

• Spawn another agent if you want

• Get interrupted only when something matters

At this point, Claude stops feeling like an assistant and starts feeling like delegated labor.

---

Level 3: Multiple Agents in Parallel

Once you’re comfortable with background execution, you stop thinking in terms of “tasks” and start thinking in terms of coverage.

> Run these three subagents in the background:
> 1. code-reviewer on the auth module
> 2. test-writer for the new login flow
> 3. doc-generator for the API changes
>
> I’ll keep working on the dashboard.

Three agents. Working simultaneously. Main thread still free.

Here’s the test-writer:

---
name: test-writer
description: Writes tests for new code. Run PROACTIVELY after features.
tools: Read, Write, Edit, Bash
model: sonnet
---

You write tests. When given a feature or module:
1. Analyze the code
2. Identify edge cases
3. Write comprehensive tests
4. Run them to verify they pass

Focus on behavior, not implementation details.

And the doc-generator:

---
name: doc-generator
description: Generates documentation for code changes.
tools: Read, Write, Grep, Glob
model: haiku
---

You write documentation. When invoked:
1. Analyze the code structure
2. Document public APIs
3. Add usage examples
4. Keep it concise but complete

At this point, you don’t have “Claude.”
You have a small team that doesn’t need your attention unless something goes wrong.

---

Level 4: Coordination (Agents Talking to Agents)

This is where it stopped feeling like a feature and started feeling like a system.

With wake messaging, agents can notify your main thread, and suggest what should happen next.

Here’s the setup I was experimenting with:

---
name: error-watcher
description: Monitors for errors. Runs in background PROACTIVELY.
tools: Bash, Read, Grep
model: haiku
---

You monitor system logs for crashes and errors.

When you find an issue:
1. Identify the type (crash, network error, runtime error)
2. Wake the main thread with a summary
3. Suggest which agent should handle it (code-fixer for bugs, api-debugger for network issues)

The idea:

• error-watcher runs in the background

• It finds a problem

• It wakes the main thread

• The main thread dispatches the right agent

Agents coordinating agents.
Your main thread as orchestrator.

---

Quick Reference

Create a subagent

• /agents, or

• Add a .md file to .claude/agents/ or ~/.claude/agents/

Run in background

> Run [agent-name] in the background

Run multiple

> Run agent-1, agent-2, and agent-3 in the background while I work on X

Coordinate

• Build “wake the main thread” instructions directly into agent prompts

---

What’s Next

Async agents are only 16 hours old as I write this. I’m still finding new patterns every session.

What I know for sure is this:
Once waiting stops being the default, going back to a single-threaded workflow feels primitive.

One main thread.
As many subagents as you need.
All running in parallel.

---