Claude Code Agents: The Four Things People Mean

“Claude Code agents” means four different things. Subagents spawned inside a session. Separate Claude Code sessions running at once. Work handed off to run in the background. And the agent definition files in .claude/agents/. Advice written for one of these usually fails when applied to another.

That’s why so much of what you find doesn’t work. Someone asks how to run agents in parallel, gets an answer about subagents, and ends up with one session doing three things instead of three sessions doing one thing each. Those are different mechanisms with different failure modes, and the fix for one won’t help the other.

Here’s each one, what it actually is, and when to reach for it.

The four, at a glance

What people call it	What it actually is	Context	Use it when
Subagents	A worker spawned inside your session	Its own window, returns a summary	You want research or a scoped task done without polluting your main context
Parallel sessions	Multiple full Claude Code instances	Fully separate, nothing shared	Two or more independent pieces of work, usually on different branches
Background tasks	Work that keeps running while you do something else	Depends which mechanism	The task is long and you don’t want to sit and watch it
Agent files	Markdown definitions in .claude/agents/	Not a runtime thing at all	You want a reusable persona, tool set, and model for a subagent

The fourth one is the source of most confusion, because an agent file is not a running thing. It’s a config file that shapes one of the other three.

1. Subagents

A subagent is a worker Claude Code spawns from inside your current session. It gets its own context window and its own system prompt, does its work, and returns a summary to the parent conversation. You never see its intermediate steps unless you go looking.

That last part is the whole point and the whole catch. The isolation is what makes subagents useful: a subagent can read forty files and burn a hundred thousand tokens, and your main session only ever receives the conclusion. It’s also what makes them frustrating: when a subagent gets something wrong, the reasoning that produced the wrong answer is not in front of you.

You invoke one three ways:

• Name it in your prompt. “Use the code-reviewer subagent on this diff.” Claude decides whether to delegate.
• @-mention it. Type @ and pick from the list. This one guarantees the delegation happens.
• Run the whole session as one. claude --agent code-reviewer starts the session in that agent’s persona.

Subagents run in parallel when the work is independent. Ask for three modules researched at once and you get three subagents going at the same time rather than one working through a list. They can also spawn their own subagents, and there are three limits worth knowing:

• 20 running at once. Past that, spawning fails with a concurrent-limit error.
• 200 spawned per session, counting nested ones, forks, and resumes. /clear resets the count.
• Three layers of nesting below your main conversation. At the limit the Agent tool is removed from the subagent’s tool set, so the tree stops growing rather than erroring out.

All three are defaults you can raise with environment variables, and all three have moved between releases, so treat them as the current shape rather than a permanent contract.

In recent versions of Claude Code, subagents run in the background by default, and any permission prompt a subagent hits surfaces in your main session naming which subagent asked. Claude runs one in the foreground only when it needs the answer before it can continue.

Use this when: the task has a clear, self-contained question and a short answer. Codebase research. A review pass. Sweeping many files to find one thing. Anything where the process is long and the result is small.

Don’t use this when: you need to watch and steer. If you’d want to interrupt halfway through and redirect, a subagent is the wrong shape, because by the time you see anything it’s finished. Reach for a separate session instead.

Full detail in Claude Code subagents explained.

2. Parallel sessions

This is the plainest version and the one most people actually want when they say “agents”. You run several complete Claude Code instances at the same time, each with its own conversation, its own context, and its own working directory.

Nothing is shared between them, which is the point. Each session is a full peer, not a worker reporting to a parent, so you can talk to any of them at any point, interrupt, redirect, and read everything each one has done.

The problem parallel sessions create is not compute, it’s the filesystem. Two agents editing the same repo at the same time will clobber each other’s work. The standard fix is a git worktree per session, so each agent gets its own checked-out copy of the repo on its own branch, all backed by one .git directory:

git worktree add ../myapp-auth -b feature/auth
git worktree add ../myapp-tests -b chore/tests

Then start a session in each directory. Claude Code can also do it for you: claude --worktree creates a worktree for the session, optionally named, and claude --worktree --tmux creates a tmux session for it at the same time.

Sessions persist. claude --continue resumes the most recent one in the current directory, claude --resume opens a picker, and --fork-session resumes with a new session ID so the original stays untouched.

Use this when: the pieces of work are genuinely independent and each one is big enough to deserve a conversation. Building a feature while another agent fixes an unrelated bug. Running the same task two ways to compare results.

Don’t use this when: the tasks touch the same files. Two sessions in one working tree is the fastest way to lose an hour, and no amount of prompting fixes it. See two agents, same repo for what that looks like when it goes wrong.

The real ceiling on parallel sessions isn’t your machine. It’s you: every session that stops to ask a question is a session waiting on your attention. More on that in managing multiple AI sessions and parallel sessions.

3. Background agents

Background work is a handoff. You start something, stop watching it, and pick the result up later. Claude Code gives you several mechanisms and they’re not the same thing:

• Ctrl+B while a task is running moves that task to the background.
• claude --bg "investigate the flaky test" starts the session as a background agent and returns to your shell immediately.
• claude agents is Agent View: one screen for dispatching and monitoring background sessions. --json prints them for scripting, --all includes completed ones.
• /tasks lists what’s running and what’s finished inside the current session, and lets you stop or dismiss them.

Setting background: true in an agent file makes that agent always run this way.

Subagents are also background work by default now, which is where the vocabulary collides. A background subagent is a subagent that happens to be async. A background session is a whole conversation running without you. They feel similar and behave very differently: the subagent reports back into your session, the session doesn’t report anywhere at all.

Use this when: the task is long, the scope is clear, and you have something else to do. Test suites. Large refactors. Anything where the interesting part is the diff at the end.

Don’t use this when: the task needs judgment calls you haven’t pre-answered. A background agent that hits an approval gate stops and waits, and the silence looks exactly like the silence of an agent working. Twenty minutes of nothing is the usual cost of finding out. Running Claude Code in the background covers how to structure tasks so it doesn’t happen.

4. Custom agent files

An agent file is a markdown file with YAML frontmatter that defines a subagent: what it’s for, which tools it can touch, which model it runs on, and what its system prompt says. It doesn’t run anything by itself. It’s the definition that the other mechanisms use.

They live in two places, project first:

.claude/agents/       # project-scoped, checked into the repo
~/.claude/agents/     # user-scoped, available in every project

Both directories are scanned recursively, so subfolders are fine. Project agents are discovered by walking up from your working directory, which means every .claude/agents/ between there and the repo root gets scanned, not only the one at the top.

Plugins ship agents too, under their own agents/ directory, and they end up namespaced as plugin-name:agent-name. Separately, --agents takes a JSON object that defines agents inline for one session rather than pointing at files, using the same fields with prompt where a file would use its markdown body.

When the same name appears twice, precedence runs: managed definitions deployed by an org admin beat everything, then --agents, then project files, then user files, then plugins. Among project files, the one closest to your working directory wins.

Only two fields are required:

---
name: researcher
description: Searches and analyzes codebases
tools: Read, Grep, Glob, WebSearch
model: sonnet
---

You are a codebase researcher. Search files, understand patterns,
and report what you found. Be specific about file paths and line numbers.

name and description are mandatory. The description is not documentation, it’s the routing signal: it’s what Claude reads when deciding whether to delegate a given task to this agent, so write it as a trigger condition, not a summary.

The rest is optional and worth knowing:

• tools is an allowlist. Omit it and the subagent inherits the tools available to it from the parent session. A research agent with Read, Grep, Glob and no Write cannot damage anything, which makes it safe to run unattended.
• disallowedTools subtracts from the inherited set instead, which is often the shorter way to say the same thing.
• model takes an alias (sonnet, opus, haiku, fable), a full model ID, or inherit. Default is to inherit the parent’s model. A cheap model on a search agent is one of the easiest cost wins available.

There’s more available in frontmatter (permission mode, turn limits, preloaded skills, scoped MCP servers, isolation) but those four fields cover most of what people actually write.

Two things trip people up. The markdown body becomes the agent’s system prompt outright rather than being appended to Claude Code’s default one, so an agent file that says only “be concise” gets you an agent whose entire instruction set is “be concise”. And in recent versions /agents no longer opens an interactive creation wizard; it prints a reminder pointing you at the two directories. Ask Claude to write the file, or write it yourself.

Use this when: you find yourself pasting the same framing into a subagent prompt more than twice, or when a repeated task deserves a narrower tool set than your main session has.

Don’t use this when: the instruction is about how work gets done in this project generally. That belongs in CLAUDE.md, where every session reads it, not in an agent file that only applies when that one agent runs. crystl’s agent instruction files editor handles both, along with the equivalents for other CLI agents.

The equivalents in other agents

The four categories aren’t Claude-specific. The vocabulary is.

Codex has a non-interactive mode for handing off a task without sitting in a session with it, and Antigravity CLI has its own project instruction file. Every serious CLI agent ends up needing the same four things: a way to scope work into a fresh context, a way to run more than one at a time, a way to walk away, and a way to save a configuration you’ll reuse.

What doesn’t travel is the syntax. Frontmatter fields, slash commands, and flags are per-agent, so check the tool you’re actually running rather than assuming a blog post about one applies to the other.

Where the four run out

Each mechanism solves its own problem well. What none of them solve is the layer above: knowing what all your agents are doing at once.

A subagent’s context is invisible by design. A parallel session on another branch is in another window. A background agent that stopped for an approval is indistinguishable from a background agent that’s working. Any one of those is fine on its own. Six at a time and you’re tab-hunting to work out which one needs you, which is what running agents at scale actually feels like day to day.

That’s the gap crystl is built for. It’s a macOS terminal where sessions are grouped by project rather than scattered across tabs, approval prompts float as panels instead of hiding inside one of eight scrolling streams, isolated sessions get real git worktrees so parallel agents can’t collide, and every session’s history stays searchable after you close it. When one agent should hand work to another, orchestration and the multi-agent quest workflow give them a way to talk instead of a way to overlap.

Picking the right one

Work backwards from what you need to see:

• You want an answer, not a process. Subagent.
• You want to watch and steer. Separate session.
• You want to leave and come back. Background.
• You want the same setup again next week. Agent file, applied to one of the first three.

Most real workflows use all four. A morning might be two parallel sessions on separate worktrees, each spawning research subagents, with a long test run in the background and a reviewer agent file that gets pulled in before anything merges. They stack as layers rather than competing as alternatives, and most of the frustration people report comes from reaching for the wrong layer and then blaming the tool.

Related reading

• Claude Code subagents explained: the deep version of section 1
• Git worktrees for parallel development: the mechanic that makes parallel sessions safe
• Managing multiple AI sessions: why the ceiling is your attention, not your machine
• Running Claude Code in the background: structuring tasks for async handoff
• Multi-agent development: for when agents need to coordinate rather than merely coexist
• Parallel sessions and orchestration in crystl