Claude Code Agents

Agents are subprocesses spawned by the Task tool. Each agent runs in its own context window -- think of the context window as the amount of information Claude can hold in its working memory during a single conversation, like the size of a desk. Everything on the desk is accessible; anything that falls off is forgotten. Agents each get their own desk, working independently of the main conversation. The main session (the orchestrator) delegates work to agents, receives their results, and synthesises the output without doing the heavy lifting itself.

Why agents exist

When you give Claude a large task -- researching 10 competitors, processing 20 documents, editing files across an entire codebase -- doing it all in one conversation would overflow the desk. Every file Claude reads, every result it processes, accumulates in that single context window. Long before the task is finished, Claude may run out of room to reason about what it has found.

Agents solve this by giving each piece of heavy work its own desk. The orchestrator stays lean, coordinating the work and synthesising results. The agents do the reading and processing. As a rule of thumb: if a task requires three or more independent operations that could run simultaneously, delegate to parallel agents rather than doing them in sequence in the main conversation.

Main conversation (orchestrator)
  ├── spawns Agent A → reads 40 files, writes summary → returns file path
  ├── spawns Agent B → researches topic, writes findings → returns file path
  └── spawns Agent C → processes batch, writes results → returns file path
↓
Orchestrator reads from disk selectively, synthesises final output

A practical example

You ask Claude to research five competitors. Without agents, Claude researches them one by one in the main conversation. Each competitor's research accumulates in the context window, and by the fifth, Claude may have consumed so much space that its reasoning about the final comparison is degraded. With agents, Claude spawns five agents -- one per competitor -- each working in parallel on its own desk. They finish in minutes rather than the time it would take to do them sequentially. Each agent writes its findings to a file on disk and returns only a brief confirmation. The orchestrator reads the five summaries and synthesises a comparison.

The result is faster, uses less of the main conversation's memory, and produces more consistent output because each agent follows the same research process.

Built-in agent types

• Explore -- read-only; optimised for fast codebase search, file discovery, and structure understanding. Cannot write files. Use for research that feeds into later decisions.
• Plan -- analysis and planning; reads files and uses Grep/Glob to design implementation approaches before code is written. Returns structured plans.
• general-purpose -- full tool access; the default for multi-step tasks, batch operations, document generation, and anything requiring writes. Use when Explore or Plan are too limited.

Custom agent types

Define specialised agents for recurring roles -- grading, document preparation, file organisation, research synthesis. Custom agents live at .claude/agents/[name].md and use YAML frontmatter to declare their capabilities:

---
name: assignment-grader
description: Grade student submissions against a rubric and generate Word feedback documents
allowed-tools: Read, Write, Bash
model: claude-sonnet-4-6
---

You are a dedicated grading agent. For each submission:
1. Read the submission file
2. Evaluate against the rubric in $CLAUDE_SKILL_DIR/rubric.md
3. Write a structured feedback document to the output path
4. Return only: Grade, file path, one-line summary

Custom agents are then callable as a named type when spawning a Task tool agent, giving each agent a defined role, toolset, and instruction set rather than starting from blank.

When to delegate vs do it yourself

Not every task warrants spawning an agent. Use this guide to decide:

Business examples

Batch document processing. You have 15 client intake forms in a folder. Rather than reading each one sequentially into the main conversation, Claude spawns 15 agents -- one per form -- each extracting the key fields and writing a structured summary to a standardised output file. The orchestrator collects the summaries and produces a consolidated table.

Parallel research. You're preparing a market analysis covering five competing platforms. Claude assigns one agent per platform. Each agent searches the web, reads the platform's pricing page, and writes a structured profile. Ten minutes later the orchestrator synthesises the five profiles into a comparison document.

Multi-file editing. You need to update a standard clause across 30 contract templates. Claude delegates to agents in batches, each editing a subset of files and returning a list of what was changed. The orchestrator confirms all files were updated and reports any exceptions.

Permission inheritance

Agents inherit the parent session's permission settings by default. The allowed-tools field in an agent definition grants that agent access to specific tools without triggering approval prompts during execution -- scoping permissions to exactly what the agent needs. An agent cannot grant itself permissions that the parent session doesn't already have.

Parallel agent discipline

When spawning three or more agents in parallel, each agent must write its full output to disk and return only a short confirmation to the orchestrator:

# Good agent return (file path + one-line summary)
"Written to /path/to/output.md — research summary on attachment theory"

# Bad agent return
[returns 400 lines of analysis directly into main context]

Returning full content from multiple agents into main context defeats the purpose of delegation and risks context overflow. The orchestrator reads from disk selectively -- only what it needs for the next step. This is the single most important discipline when working with parallel agents.

Worktree isolation

Agents can run in an isolated git worktree -- a temporary copy of the repository where the agent makes changes without affecting the main working tree. This is the default for agents spawned with the isolation: "worktree" option.

How it works:

• Claude Code creates a new git worktree (a separate checkout of the repo at a new branch)
• The agent operates entirely within that worktree -- its file reads, writes, and commands are isolated
• If the agent makes no changes, the worktree is cleaned up automatically on completion
• If changes are made, the worktree path and branch name are returned to the orchestrator for review and merging

Worktree isolation is useful for experimental or potentially destructive operations -- if the agent's work is wrong, you discard the branch rather than reverting changes to main.

Subagent memory

By default, agents do not maintain their own auto memory. If an agent type requires persistent learning across invocations -- for example, a grading agent that remembers marking patterns -- set subagentMemoryEnabled: true in the agent definition. The agent will read and write to its own memory file, separate from the orchestrator's memory.