Claude Code Agents and Subagents, Explained

I spent part of last month deleting agent files. Claude Code agents and Claude Code subagents are the most useful thing I have added to my workflow in a year, and also the easiest to cargo-cult: you clone somebody's repo of sixty specialist personas, drop them into a folder, and then spend a fortnight wondering why nothing got faster. The mechanism is genuinely simple once you see it. Knowing when to delegate is the hard part. And the question almost nobody answers is where all those agents should actually run once you stop babysitting them.

Here is the version I wish I had read first.

What a Claude Code agent actually is

An agent is a Markdown file. That's it. YAML frontmatter on top declares who it is and what it may touch; everything below the frontmatter becomes its system prompt.

Drop the file in .claude/agents/ and it belongs to the project, so it gets committed and everyone working in the repo gets the same specialist. Drop it in ~/.claude/agents/ and it follows you across every project on your machine. Both paths and the full frontmatter list are in Anthropic's subagents documentation.

The fields worth knowing on day one:

There are more, including skills, effort, memory and isolation: worktree for agents that should work in their own git worktree, but the seven above cover most of what you'll write.

Claude Code agents and Claude Code subagents are the same file, used two ways

This is the distinction that trips people up, and it has nothing to do with the file format.

Run claude --agent code-reviewer and that definition becomes your main session. You are talking to it directly. It is an agent.

Let your main session hand the work off instead, and the same definition runs as a subagent: a separate context window with no conversation history, no memory of the files you already read, and no view of what you were just doing. It does the job and hands back a summary. You can force that with an explicit @agent-code-reviewer mention, or let Claude route to it automatically based on the description field.

Claude Code also ships three built-ins you are already using without writing any files: Explore for read-only codebase search, Plan for research during plan mode, and General-purpose for multi-step work. The docs put the defaults at up to twenty subagents running at once and three layers of nesting, both tunable with environment variables.

The separate context window is the entire point

A subagent is not a persona trick. It is a container.

When Claude tails a 4,000-line log in your main session, all 4,000 lines live in your context for the rest of the conversation. When a subagent does it, the log stays in that subagent's window and your session gets a paragraph. That is the whole trade: you give up shared context and get room to keep working.

The second effect is cost, and this is where per-agent model earns its keep. On Anthropic's published API rates, Claude Opus 5 is $5 per million input tokens and $25 per million output, Claude Sonnet 5 is $2 and $10, and Claude Haiku 4.5 is $1 and $5. Same page: a prompt-cache hit costs 0.1x the base input rate. So a grep-and-summarise agent pinned to haiku runs at a fifth of the input rate of the Opus session that called it, and the caller never pays for the transcript it waded through. Pin the reviewer that has to actually reason to opus, and pin the file-finder to haiku.

The third effect is blast radius. A reviewer declared as tools: Read, Grep, Glob physically cannot edit your code, no matter how confidently it decides it should.

Three rules I follow now

One agent per verifiable outcome, not per job title. "Senior architect" produces vibes. "Runs the test suite and reports the first failing assertion with the file and line" produces a result I can check.

Write the description for the router, not for humans. Claude reads that field to decide whether to delegate. Vague descriptions are why people conclude automatic delegation doesn't work.

Restrict tools before you restrict models. A cheap agent that can write files is a worse idea than an expensive one that can only read.

Where should these agents run?

Once the definitions are good, the interesting question moves. Not what the agent is, but which machine wakes it up.

The "it does nothing while you sleep" criticism of Claude Code is out of date, and here is the accurate picture:

Routines are the one to understand properly. Per the docs they run on Anthropic-managed cloud infrastructure, accept schedule, API and GitHub-event triggers, enforce a minimum interval of one hour, clone the GitHub repositories you select on every run, push work to claude/-prefixed branches, and are available on Pro, Max, Team and Enterprise plans with Claude Code on the web enabled, subject to a daily cap on runs. Channels are a research preview that pushes Telegram, Discord or iMessage messages into a session you already have open, which means the session has to be open.

Notice what every row has in common: the unit of work is a repository.

The half of my backlog that has no repo

I write software, and I still spend more of my week outside a git repo than inside one. The quote that needs sending. The Notion database that is three days stale. The email thread that needs a summary before a call. Nothing in that list clones from GitHub, and none of it produces a pull request. Routines are not built for it, and that's fine, because they weren't meant to be.

That gap is why I built Notis the way I did. Same delegation shape you just read about, different substrate: the agent lives in WhatsApp, Telegram, iMessage, email, Slack or the desktop app, and the specialists it hands off to reach Notion, Gmail, Google Calendar, Outlook, Linear, GitHub and Dropbox rather than a working tree. A voice note on a walk becomes a filed Notion row and a drafted reply. There is no repository to select because the deliverable was never a diff.

Two things about how it bills, since the whole point of running specialists is not being surprised. Usage is included in the plan rather than metered on top of it, with $20 of usage a month on Pro, $59 on Pro+ and $149 on Ultra, and a typical task drawing a few cents from it; past the allowance, on-demand usage keeps working and is billed in arrears. And any single pay-per-use call priced above $1.20 to you is refused outright, with the agent told to state the price and ask before retrying. Pro is $13 a month billed annually.

What I'd do this week

If you're new to this: write exactly two agents. A read-only reviewer on haiku or sonnet, and a test-runner with maxTurns set. Delete every persona file you didn't write yourself.

If your agents already work: move one recurring job off your laptop. A nightly routine that reads yesterday's merged PRs and opens a docs-drift PR is a better first candidate than anything interactive.

If most of what drains your week never touches a repo: stop trying to make a coding harness do it. That work needs an agent that lives where you already type.

The file format takes ten minutes to learn. Deciding what deserves its own context window, and which machine should own it, is the part that actually changes your week.