AGENTS.md

1# Agents
2 
3Agents are isolated Claude instances you create and configure for specialised tasks. They come in two forms: [subagents](^Focused workers that run inside your session, do a job, and return a summary) that operate within your session, and [agent teams](^Multiple independent Claude Code sessions coordinating through a shared task list) that coordinate across separate sessions.
4 
5## Quick Start
6 
71. Run `/agents` inside Claude Code to open the interactive agent manager
82. Select **Create new agent**, then choose a scope (project or user)
93. Use **Generate with Claude** and describe what the agent should do
104. Select which tools the agent can access, pick a model, and save
11 
12Your agent is available immediately. Try it: "Use the my-agent agent to review this module."
13 
14## How Subagents Work
15 
16Subagents are `.md` files with YAML frontmatter for configuration and a Markdown body that becomes the system prompt. Each subagent runs in its own context window, uses only the tools you allow, and returns a summary to your main conversation.
17 
181. Claude matches your request to a subagent's `description` field
192. A new context window is created with the subagent's system prompt
203. The subagent works independently (reading files, running commands, etc.)
214. Results are summarised back to your main conversation
22 
23Subagents can run in the foreground (blocking) or background (concurrent). Press `Ctrl+B` to send a running task to the background.
24 
25## Where Agents Live
26 
27| Location | Scope | Priority |
28|----------|-------|----------|
29| `--agents` CLI flag | Current session only | 1 (highest) |
30| `.claude/agents/` | This project (check into version control) | 2 |
31| `~/.claude/agents/` | All your projects | 3 |
32| Plugin `agents/` directory | Where the plugin is enabled | 4 (lowest) |
33 
34When multiple agents share the same name, the higher-priority location wins.
35 
36## Built-in Subagents
37 
38Claude Code ships with subagents it uses automatically:
39 
40- **Explore**: fast, read-only codebase search (runs on Haiku)
41- **Plan**: structured planning and analysis
42- **General-purpose**: flexible helper for miscellaneous delegation
43 
44You can create custom agents that override built-ins by using the same name at a higher priority scope.
45 
46## Frontmatter Reference
47 
48| Field | Required | Purpose |
49|-------|----------|---------|
50| `name` | Yes | Unique identifier (lowercase, hyphens) |
51| `description` | Yes | When Claude should delegate to this agent |
52| `tools` | No | Allowlist of tools (inherits all if omitted) |
53| `disallowedTools` | No | Denylist removed from inherited tools |
54| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` (default) |
55| `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
56| `maxTurns` | No | Maximum agentic turns before the agent stops |
57| `skills` | No | Skills to inject into the agent's context at startup |
58| `mcpServers` | No | MCP servers available to this agent |
59| `hooks` | No | Lifecycle hooks scoped to this agent |
60| `memory` | No | Persistent memory scope: `user`, `project`, or `local` |
61| `background` | No | Set `true` to always run as a background task |
62| `isolation` | No | Set `worktree` to run in a temporary git worktree |
63 
64## Agent Teams
65 
66Agent teams coordinate multiple independent Claude Code sessions working in parallel. One session acts as the lead; others are teammates with their own context windows.
67 
68Agent teams are experimental. Enable them in `settings.json`:
69 
70```json
71{
72  "env": {
73    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
74  }
75}
76```
77 
78Then describe the team structure in natural language:
79 
80```
81Create an agent team to review PR #142. Spawn three reviewers:
82one focused on security, one checking performance, one validating tests.
83```
84 
85### Subagents vs Agent Teams
86 
87| | Subagents | Agent Teams |
88|---|-----------|-------------|
89| Communication | Report results back to caller only | Teammates message each other directly |
90| Context | Own window; results return to main session | Own window; fully independent |
91| Coordination | Main agent manages all work | Shared task list with self-coordination |
92| Best for | Focused tasks where only the result matters | Complex work requiring discussion |
93| Token cost | Lower (results summarised back) | Higher (each teammate is a separate instance) |
94 
95Use subagents for quick, focused workers. Use agent teams when teammates need to share findings and coordinate on their own.
96 
97## Common Patterns
98 
99- **Isolate verbose output**: delegate test runs or log analysis to a subagent so the output stays out of your main context
100- **Parallel research**: spawn multiple subagents to investigate different parts of a codebase simultaneously
101- **Chain subagents**: use one for analysis, pass its findings to another for implementation
102- **Competing hypotheses**: spawn agent team members to investigate different theories and debate each other
103 
104## Tips
105 
106- Write detailed `description` fields so Claude knows when to delegate. Include "use proactively" for agents you want used automatically
107- Grant only the tools an agent needs. A read-only reviewer should not have Write or Edit
108- Subagents cannot spawn other subagents. For nested delegation, use skills or chain from the main conversation
109- Use `memory: user` to let agents build knowledge across sessions. Ask them to "check your memory" before starting and "save what you learned" after finishing
110- Agent teams work best with 3-5 teammates and 5-6 tasks each. More teammates means more coordination overhead
111- Teammates load `CLAUDE.md` from the working directory, so project conventions apply to the whole team