AI coding agents · Claude Code · Codex · Configuration

Configuring AI Coding Agents: Subagents, Agent Teams, JSON and Markdown Files

One coding agent in one chat is a good start. When the job grows (review a whole app, investigate a bug with several theories, build a feature across layers) you want helpers: small agents with their own instructions, tools and context. This article shows how to define them three ways (in the terminal, in JSON, and in Markdown or TOML files), how to run them, and how to arrange them into a team that does not trip over itself.

1. The mental model: one agent, subagents, teams

An agent is a language model running in a loop with tools: it reads files, runs commands, and decides what to do next. The problem with a single agent is its context window. Every file it reads and every log line it sees stays in the conversation, so a long task fills the window and quality drops. Helpers solve that by doing messy work somewhere else.

2. Three ways to configure an agent

Where the definition lives decides who can use it and which one wins when two share a name.

For Claude Code the lookup order, from strongest to weakest, is:

1. Managed settings (set by an organisation).
2. The --agents flag for this session.
3. .claude/agents/ in the project (the folder closest to your working directory wins).
4. ~/.claude/agents/ for all your projects.
5. Plugins, which ship their own agents/ folder.

3. Markdown files (Claude Code)

A subagent is a Markdown file. The part between the --- lines is YAML configuration; everything after it is the agent’s system prompt.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for bugs, security and maintainability. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer.
Review the changes you are pointed at. Report findings with file paths and line numbers,
ordered by severity. Do not modify files. If everything looks fine, say so briefly.

Save the file and it is picked up while the session runs (the very first agent file in a brand-new agents folder may need a restart). Only name and description are required.

The header fields you will actually use

Fields change between versions, so treat this table as a map and check the subagent reference for your installed version.

Example: a read-only agent that cannot be talked into editing

---
name: db-reader
description: Runs read-only database queries to answer questions about data.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---
You answer data questions by running SELECT queries only.

The script receives the pending command as JSON on standard input. Exiting with code 2 blocks the call. That is a real guard, unlike a sentence in the prompt.

Example: an agent that works in its own worktree

---
name: refactorer
description: Performs one mechanical refactor in an isolated branch checkout.
isolation: worktree
model: sonnet
maxTurns: 40
---
Apply the requested refactor. Run the unit tests. Summarise what changed.

With isolation: worktree the agent edits a temporary copy of the repository, so it can run beside your own work. The same idea is explained for people in the Git and branching guide (git worktree).

Where the prompt body goes

• State the role, the steps, and the shape of the answer (“findings with file paths and line numbers”). The caller only sees that final message.
• Say what not to do (“do not modify files”), and back it up with tools.
• Keep it short. A subagent starts with a fresh context and does not see your conversation, so include everything it needs in the task you give it.

4. JSON and settings (Claude Code)

Define agents for one session with --agents

Each top-level key is an agent name. prompt takes the place of the Markdown body.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Find root causes and propose fixes."
  }
}'

The same fields as the Markdown header are accepted (description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, memory, effort, background, isolation and a few more). color is ignored. In non-interactive runs (-p) newer versions also accept a file path:

claude -p "Review the staged changes" --agents ./agents.json

Because --agents outranks files on disk, it is a handy way to override an agent for a CI job without touching the repository. On Windows PowerShell use a here-string (@'...'@) to avoid quote trouble.

Make an agent the default with settings.json

To run the whole session as an agent (its prompt, tools and model replace the defaults), use the --agent flag, or set a project default:

// .claude/settings.json
{
  "agent": "code-reviewer"
}

The command-line flag claude --agent code-reviewer overrides the setting.

Control delegation with permissions and environment variables

// .claude/settings.json
{
  "permissions": {
    "deny": ["Agent(Explore)"]          // block one agent; deny "Agent" to block all delegation
  },
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet",          // default model when the file names none
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "6",     // default is 20 at once
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"      // 1 turns off subagents spawning subagents
  }
}

Which model does a subagent end up with? In order: the model named for that one call, then the model in the agent file (inherit means the main conversation’s), then CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation’s model.

5. Running and managing agents in the terminal

Three ways to call an agent

Claude also delegates on its own when a task matches an agent’s description. Three built-in agents are always there: Explore (read-only search, with quick, medium and very thorough levels), Plan (read-only research for plan mode) and general-purpose (all tools). A file of your own with the name Explore replaces the built-in one.

Watching and steering

• /tasks lists running and finished subagents and the model each used. Press x on a row to stop one.
• Ctrl+B sends a running subagent to the background so you can keep typing. Subagents Claude starts from the main conversation run in the background by default, and their permission prompts appear in your main session.
• Resume: each call is a new instance, but you can say “continue that code review and now look at authorization” and Claude resumes it with its history. Explore and Plan are one-shot and cannot be resumed.
• Transcripts are stored under ~/.claude/projects/…/subagents/ and are cleaned up after the retention period (30 days by default).
• /agents: on current versions it only reminds you to ask Claude or edit the folders. Older versions (2.1.197 and earlier) opened a wizard for creating and editing agents.

Quick start: a parallel read-only review, no files needed

Use subagents to review this project in parallel.

- Agent 1: find bugs and edge cases.
- Agent 2: review architecture and maintainability.
- Agent 3: review unit test coverage.
- Agent 4: identify performance and memory issues.

Return findings with file paths and line numbers. Do not modify files.

This is the safest first experiment: the agents only read, so there is nothing to conflict, and you get four independent opinions back as short summaries.

6. Setting up a team of subagents

A “team” of subagents is not a feature switch. It is a set of well-separated roles plus a rule for how work flows between them. Three patterns cover most needs.

Step 1: split by role, not by file count

Good roles have one job, a narrow tool list and a clear output. A reasonable starter set for an Android or backend project:

Step 2: write the files

.claude/agents/explorer.md
---
name: explorer
description: Read-only codebase explorer. Use to locate code, trace a call path or list affected files.
tools: Read, Glob, Grep
model: haiku
---
Find what was asked and answer with file paths and one-line explanations.
Never edit files. Keep the answer under 40 lines.

.claude/agents/implementer.md
---
name: implementer
description: Implements one well-defined change in the files it is given. Use after the plan is agreed.
tools: Read, Edit, Write, Bash
model: sonnet
isolation: worktree
---
Make the smallest change that satisfies the task. Touch only the files named in the task.
Run the relevant tests before you finish. Report what changed and what you did not do.

.claude/agents/reviewer.md
---
name: reviewer
description: Independent reviewer of a diff. Use proactively after any implementation.
tools: Read, Glob, Grep, Bash
model: opus
---
Review the diff for correctness, security and missing tests. Use git diff to see it.
Report findings by severity with file and line. Do not edit files.

Step 3: give the orchestrating prompt

Add retry with backoff to the upload client.

1. Use the explorer subagent to list every file involved in uploads.
2. Propose a plan and wait for my OK.
3. Use the implementer subagent for the change, and test-writer for the tests.
   They must not edit the same file.
4. Finish with the reviewer subagent on the full diff and summarise its findings.

Do not commit, push or open a PR without my approval.

Step 4: keep agents from colliding

• One owner per file. Two agents writing the same file means one overwrites the other.
• Prefer worktrees for parallel writers. isolation: worktree (Claude Code) or git worktree add by hand gives each writer its own checkout and branch. Merge them one by one afterwards, as described in the branching guide.
• Read in parallel, write in sequence. It is the cheapest way to get speed without conflicts.
• Limit depth and count. A small cap on concurrent agents and a spawn depth of 1 or 2 keeps cost and confusion predictable.

7. Agent teams (Claude Code, experimental)

Agent teams go beyond subagents. One session is the lead. It spawns teammates, each a full Claude Code session with its own context. They share a task list and can message each other, and you can talk to any of them directly. The feature is experimental and disabled by default, with known limits around resuming sessions and shutdown.

Turn it on

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

You can also export the variable in your shell. Teams need an interactive session; with claude -p and in SDK sessions no teammates are spawned.

What each value does

The variable is a plain on/off switch, not a number of teammates. Only a few words count as “on”; everything else, including bigger numbers, leaves teams off. This was checked against Claude Code 2.1.307, so re-test after big upgrades.

• Accepted “on” words: 1, true, yes, on (case does not matter, spaces around the value are ignored). Accepted “off” words: 0, false, no, off.
• A silent failure: a typo or a number such as "10" does not raise an error. Teams just never appear, which is easy to mistake for a bug. If no teammates show up, check this value first.
• The command-line flag --agent-teams also turns the feature on for one run, even when the variable is off.
• To choose how many teammates, say so in the prompt (“Spawn 4 teammates…”). Start with 3 to 5.

Start a team with a prompt

There is no team configuration file. You describe the roles in plain language, and Claude creates the team, the task list and the teammates.

Create an agent team to investigate and improve this Android project.

Roles:
1. Lead developer: coordinate, inspect the architecture, integrate the findings.
2. Code reviewer: look for bugs, concurrency issues and architectural problems. Do not modify files.
3. Test engineer: find missing unit tests and implement tests for the agreed changes.
4. Android specialist: review Kotlin, coroutines, lifecycle handling and Android best practices.

First inspect the repository and make a plan. Give independent tasks to teammates and let
them work in parallel. Avoid having several agents edit the same files. Review their
findings, run the relevant tests and summarise the final changes.

Do not commit, push or open a PR without my approval.

Two more prompts that suit teams well:

Spawn three teammates to review PR #142: one for security, one for performance, one for test coverage.
Have them each review and report findings.

Users report the app exits after one message. Spawn 5 teammates to investigate different
hypotheses. Have them try to disprove each other's theories, then update the findings doc
with whatever consensus emerges.

The second one shows why teams exist: several investigators arguing beats one agent that stops at the first plausible cause.

Choose how teammates are displayed

// ~/.claude/settings.json
{
  "teammateMode": "auto"
}

# or for one session
claude --teammate-mode auto

Split panes do not work in VS Code’s integrated terminal, Windows Terminal or Ghostty. If panes do not appear, check which tmux, and kill leftovers with tmux ls and tmux kill-session -t <name>.

Control the team

• Number and models: “Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each.” Start with 3 to 5.
• Names: tell the lead what to call each teammate, so you can say “ask the researcher to shut down” later.
• Plan first: put the lead in plan mode before spawning a teammate, and that teammate plans in read-only mode before it implements.
• Reuse your subagent files: “Spawn a teammate using the security-reviewer agent type to audit the auth module.” Its tools and model apply, and the body is added to its instructions. Define a role once, use it both ways. (The definition’s skills are not applied to teammates.)
• Tasks: pending, in progress, completed, with dependencies. Teammates can claim the next free task themselves; claims use file locking so two cannot take the same one.
• Talk to a teammate: select it and type, or click its pane. x stops it, Ctrl+T toggles the task list.
• Stuck lead: if the lead starts doing the work itself, say “Wait for your teammates to complete their tasks before proceeding.”

Quality gates with hooks

For example, a TaskCompleted hook can run the unit tests and refuse to close a task while they fail.

How it behaves

• Teammates start with the lead’s permission mode (except dontAsk). Their permission prompts show up in the lead’s session. Pre-approve common safe commands first to cut interruptions.
• A teammate loads CLAUDE.md, MCP servers and skills like any session, but not the lead’s conversation. Put task details in the spawn prompt.
• A message from another agent is never treated as your approval.
• Team state lives under ~/.claude/teams/ and ~/.claude/tasks/. Do not hand-edit the team config; it is rewritten constantly. A project file such as .claude/teams/teams.json is not recognised.

8. Codex: TOML agent files

Codex also splits work across parallel agents and gathers the results into one reply. It handles the delegation itself when you ask for it or when your AGENTS.md or a skill says so. There is no separate “team” mode; you describe how to split the work.

Ask for parallel work

Review this branch with parallel subagents. Spawn one subagent for security risks, one for
test gaps, and one for maintainability. Wait for all three, then summarize the findings
by category with file references.

A good prompt says how to split the work, whether to wait for all agents, and what to return. In the CLI, /subagents lets you inspect and switch between agent threads; in an IDE the background-agent panel shows status and can stop them all.

Built-in agents

A custom agent with one of these names takes precedence.

Custom agents: one TOML file each

Put personal agents in ~/.codex/agents/ and project agents in .codex/agents/. The name field is what counts; matching the file name is only a convention.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings and include reproduction steps when possible.
"""

Global limits in config.toml

# .codex/config.toml
[agents]
max_concurrent_threads_per_session = 8     # older name: max_threads
# enabled = true                          # turn multi-agent tools off with false
# default_subagent_model = "..."
# default_subagent_reasoning_effort = "medium"

Start with parallel read-heavy tasks. Parallel writes are riskier because of edit conflicts, and each subagent does its own model and tool work, so costs go up.

9. Claude Code and Codex side by side

Both tools read a project instructions file, and every agent you start loads it. Put shared rules there (commands to build and test, style, “never commit without asking”) instead of repeating them in each agent. If you use both tools, many teams keep one source of truth and point the other file to it. The two series on this site cover those files in depth: start with the Claude Code and Codex series.

10. Pros and cons: parallel vs serial

Short answer: yes, parallel agents can make a job finish sooner, but only when the pieces are independent. Run dependent steps in parallel and it gets slower, costlier and messier than doing them one after another. Speed is not the only measure, so here is the full picture.

Why parallel helps

Why serial still has a place

When one agent must wait for another

Many agents do not mean many things happening at once. If every step needs the output of the step before it, the agents take turns, and the total time is the sum of all steps, plus the cost of handing work over. Having five agents in that line is not faster than one; it is usually slower, because each hand-off adds setup, a fresh context and a summary to write and read.

A real example is the pipeline in Building Effective Agents in Practice. A Jira ticket, a plain spec or a Crashlytics crash goes through intake, an automatic prompt, the agent, checks, a draft pull request, a person’s review, merge and release, and finally monitoring. Each stage needs what the previous one produced, so for one ticket the stages run in a line.

Why it is slow: the critical path

The critical path is the longest chain of steps where each one needs the one before. It sets the minimum time for the whole job, no matter how many agents you add. If a task has 60 minutes that must run in order and 20 minutes that could run side by side, even a hundred agents cannot finish it in under 60 minutes. This is the idea behind Amdahl’s law: the part that must stay sequential limits the speed-up. Each extra agent on the sequential part only adds hand-off cost.

Everyday examples of one agent waiting for another

What you can still do about a serial chain

• Keep the chain short. Cut stages that add little. Five hand-offs cost more than two.
• Use one agent for tightly linked steps. A single agent keeps the context from step to step. Split off only where a fresh context pays for itself, for example an independent reviewer.
• Overlap the independent bits. While the implementer works, an explorer can already gather the files for the next step, and a docs agent can draft the changelog.
• Run many chains at once. Ten tickets can each go through their own pipeline in parallel worktrees. This raises throughput, though no single ticket gets faster.
• Make hand-offs small and structured. Pass a short plan or a diff with file paths, not a long story. The Jira pipeline does this by turning every input into one task format first.
• Shorten the human wait. Small pull requests, clear descriptions and automatic checks make review quicker than any agent trick.

A simple rule for choosing

Ask: does task B need anything produced by task A? If no, they can run in parallel. If yes, run them in order. Speed-up is limited by the part that must stay sequential, so adding more agents has diminishing returns.

One honest caveat: the real gain depends on the task, the model and your setup, so measure on your own work. Time one task done serially and in parallel, count the tokens, and include the time you spend reading and merging the results.

11. Safety, cost and habits

• Least privilege. Give each agent only the tools it needs. A reviewer does not need Edit.
• Enforce, do not ask. For “never touch this” use tools, hooks or the sandbox. Instructions can be ignored; a blocked tool cannot.
• Human gates. Say “do not commit, push or open a PR without my approval” and keep branch protection on the server, so the repository enforces it too.
• Trust the folder. Agent files in a repository can carry hooks and MCP servers. Treat a cloned repository’s .claude/agents/ like code you are about to run, and review it first.
• Review the result. An agent’s summary describes what it intended. Read the diff, and run the tests yourself.
• Commit the agent files. Project agents in .claude/agents/ or .codex/agents/ go through pull requests like any other code, so the team improves them together.
• Start small. One read-only agent, then two in parallel, then a pipeline, then a team. Add a role only when you see a gap.

12. Common mistakes

• A vague description. The agent never gets picked, or gets picked for everything. Say what it does and when to use it.
• Assuming the helper knows the conversation. Subagents and teammates start fresh. Give file paths, goals and constraints in the task.
• Two writers on one file. Divide by file or use worktrees.
• Too many agents for a small task. Coordination can cost more than the work. Three focused agents usually beat five scattered ones.
• Using a team where subagents suffice. If agents never need to talk to each other, subagents are cheaper and simpler.
• A broken header. The opening --- must be on line 1; wrong field case or bad YAML means the file is skipped silently. Check with claude --debug.
• Trusting “do not edit”. Remove the Edit and Write tools, or use a read-only sandbox.
• Letting the lead implement. If the lead starts coding instead of coordinating, tell it to wait for its teammates.
• Forgetting the version. Agent features, fields and flags change quickly. Check the docs for your installed version.

13. Takeaways and glossary

• Subagents protect your main context and let work run in parallel. Define them as Markdown (Claude Code) or TOML (Codex), or pass JSON with --agents for one session.
• Write a precise description, a narrow tools list and a short prompt that says what to return.
• Build a team of subagents from roles: explorer, implementer, test-writer, reviewer. Fan out for read-only work, pipeline for hand-offs, and one owner per file.
• Agent teams are for work that needs agents to talk to each other. They are experimental and cost more.
• Parallel agents are faster only when tasks are independent; dependent steps run in parallel cost more and can be slower. Parallel to read, serial to write.
• Agents inherit your permissions. Enforce limits with tools, hooks and sandboxes, and keep a human gate before commit and push.

Links and further reading

• Claude Code: create custom subagents · Orchestrate teams of Claude Code sessions
• Codex: subagents
• Building effective agents (Anthropic) · Building Effective Agents in Practice
• Git, branching and worktrees · Claude Code series, part 6 · Codex series, part 6