Class 12 · 12.4

Agents & sub-agents (and a cameo from Codex)

Now the heart of the week: agents and sub-agents. We’ll separate the hype (“multi-agent”) from the real gold (sub-agents), build our own reviewer, hand the job to a different AI entirely, and preview the agent-teams world to come.

🎯 Goal: delegate to other agents⏱ Read: 16 min🤖 Type: hands-on

“Multi-agent” sounds mystical. Part of it is genuinely mundane; the valuable part — sub-agents — is where the power lives. Let’s take them in order.

01“Multi-agents”: the boring truth

The simplest meaning of multi-agent is just… opening several terminals and running several Claudes. One builds the frontend, one the backend, one the tests. If your boundaries are well-defined, they can work in parallel.

A cautionary demo

With a thin plan.md, launching three independent agents would likely be a fiasco — not enough shared fabric, agents unaware of each other, pieces that don’t fit. It shows what “multi-agent” means, and why coordination (12.2’s shared files) matters before you parallelise.

02A different agent altogether: Codex CLI

Your other agent need not be Claude. To make the point vivid, we bring in Codex — OpenAI’s equivalent of Claude Code, run from the command line. Install it, then drive it non-interactively with codex exec:

terminal

npm install -g @openai/codex     # or: brew install codex
codex                                # interactive; first run does an OAuth login

# the magic: run a one-shot prompt, no chat
codex exec "review planning/plan.md and write feedback to planning/review.md"

Why this is a big deal

codex exec runs a whole other AI as a single shell command. That means any agent can be launched from a script — and, in a moment, from inside Claude Code. It opens the door to genuinely mixed multi-agent workflows. (You don’t need Codex — a second claude works just as well; the different-LLM twist is just fun.)

03Sub-agents: the real gold

A sub-agent is a separate agent that takes on one task, runs it in its own isolated context, and returns just the result to the main Claude Code. You have already seen built-in ones (Explore, Plan) flash by in a different colour.

The noisy to-and-fro happens in the sub-agent’s context. The main agent only ever sees the clean answer — that’s the whole point.

Why reach for one? Four reasons: protect context (the big one — keep noise off the main window), parallelism (several at once), focus (perfect one prompt for one job), and cost/speed (a cheaper model like Haiku for simple tasks).

04Build a reviewer sub-agent

Sub-agents live in .claude/agents/ as markdown files with a little front matter. Here is a reviewer — and the fun version that delegates the actual review to Codex:

.claude/agents/reviewer.md

---
name: reviewer
description: Carry out a comprehensive review when requested.
# tools: and model: are optional — omit to inherit the caller’s
---
You carry out a comprehensive review of plan.md when requested,
using a different AI. You MUST run the following shell command and
do NOT review it yourself:

codex exec "review planning/plan.md, write feedback to planning/review.md"

You don’t call it with a slash

Unlike a command, you don’t type /reviewer. You ask for it in plain language — and the recommended phrasing names it explicitly: “use the reviewer sub-agent to review planning/plan.md.” Claude decides to launch it, and the whole review runs off in isolation.

claude

> use the reviewer sub-agent to review planning/plan.md

# main Claude spawns the sub-agent → it runs `codex exec` →
# Codex writes planning/review.md → only the result returns.
# /context shows the main window is still almost empty.

Make it general

Swap “review plan.md” for “review all changes since the last commit” and you have a reusable change-reviewer — the seed of real multi-agent orchestration, and exactly what we’ll trigger automatically with a hook next.

05Sub-agents vs. agent teams

A quick preview so the terms don’t confuse you later (agent teams come on the wild day):

	Sub-agents	Agent teams (experimental)
Shape	One main agent delegates one task, gets the result back.	A whole group of agents running collaboratively at once.
Communication	Only through the main agent.	Agents can talk to each other directly.
Lifespan	Short: take the task, do it, return.	Long-running presence in your “team”.
Example	A reviewer that reads a file and reports back.	A tester that gives feedback straight to the frontend and backend agents.

06Weighing sub-agents

Strengths

Why you’d use them

Protect the main context, run work in parallel, self-correct (review/test agents), and focus one perfected prompt on one job.

Costs

The trade-offs

More moving parts (more can go wrong), boundary/interface mistakes, compounding errors if one drifts, and sometimes more spend from all the extra churn.

Not always cheaper

Sub-agents are sold as a way to save money with cheaper models — but self-correcting review loops mean more calls overall. Better outcomes, yes; guaranteed savings, no. Use them where the context or parallelism win is real.

✓ Key takeaways

“Multi-agent” can just mean several terminals — coordination matters more than count.
codex exec runs another AI as one shell command — launchable from scripts and from Claude.
A sub-agent runs a task in isolated context and returns only the result — protecting your window.
Define them in .claude/agents/*.md; invoke by asking to “use the … sub-agent”.
Agent teams (later) run many collaborating, communicating agents; sub-agents are simpler and task-focused.