How to run multiple Claude Code agents at once

Four ways to run Claude Code agents in parallel

Subagents: parallel helpers inside one session

A subagent has its own context window, system prompt and tools. It doesn't see your conversation, and only its summary comes back, which keeps the main session's context small. Claude Code ships with built-in ones like Explore (read-only) and Plan, and you can add your own.

1. Define a subagent

   Create a Markdown file in .claude/agents/ (shared with the project) or ~/.claude/agents/ (just you). Only name and description are required; tools limits what it can use and model picks the model.

   ---
   name: code-reviewer
   description: Reviews code for quality and best practices
   tools: Read, Glob, Grep
   model: sonnet
   ---
   
   You are a code reviewer. When invoked, analyze the code and give
   specific, actionable feedback on quality, security and best practices.

2. Let Claude run several at once

   Ask for the work in parallel, e.g. “review the auth, billing and search modules in parallel.” Subagents Claude spawns start in the background by default, up to 20 at a time, and report back when they finish. Type /tasks to see them.

3. Give file-editing subagents their own worktree

   Add isolation: worktree to the subagent's frontmatter, or ask Claude to use worktrees for its agents. Each then edits a temporary copy of the repo, which is removed if it made no changes.

Run parallel Claude Code sessions in git worktrees

1. Ignore the worktrees folder

   Claude Code creates worktrees in .claude/worktrees/ at the repo root. The repo needs at least one commit.

   echo ".claude/worktrees/" >> .gitignore

2. Start one session per task

   In each terminal, run claude --worktree (or -w) with a different name. Each gets its own folder and a branch named worktree-<name>, based on the default branch.

   # terminal 1
   claude --worktree feature-auth
   
   # terminal 2
   claude --worktree bugfix-login

3. Copy untracked files you need

   A new worktree has only tracked files. List files like .env in a .worktreeinclude file (gitignore syntax) and Claude Code copies them in.

   .env
   .env.local

4. Merge and clean up

   When a session ends, a worktree without changes is removed with its branch; one with changes asks whether to keep it. Merge the branches as you would any other. Headless -p runs don't prompt, so remove those with git worktree remove.

5. Or use the desktop app

   Press Cmd+N (Ctrl+N on Windows) for a new session and turn on Worktree before starting it; it's off by default. Sessions can sit side by side in split view.

Source: Anthropic's worktrees docs

Background sessions with --bg and agent view

claude --bg "<prompt>" starts a session in the background and returns right away, so you can start several in a row. Each one moves into its own worktree before it edits anything. claude agents lists them; claude logs <id>, claude attach <id> and claude stop <id> manage one.

They keep running after you close the terminal, but not after the computer shuts down. Agent view is a research preview. For more on unattended runs, see how to run Claude Code background agents.

Agent teams: agents that talk to each other

Agent teams are experimental and off by default. Turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell or in the env block of settings.json, then ask Claude to “spawn three teammates” for a task. Teammates share a task list and message each other; they show in the terminal, or in split panes with tmux or iTerm2.

• Interactive sessions only: -p and the Agent SDK don't spawn teammates.
• One team per session, no nested teams, and in-process teammates aren't restored by /resume.
• Teammates share one checkout, so give each a different set of files.
• They cost far more: Anthropic's docs put a team at roughly 7 times the tokens of a single session when teammates run in plan mode.

Keep parallel agents from overwriting each other

• If two agents might touch the same files, give each its own worktree. A session in a worktree can't edit the main checkout, and neither can its subagents.
• In an agent team, split the work by files: two teammates editing one file overwrite each other.
• Every subagent and session draws on the same usage limits, so running several multiplies usage. Use model: haiku for simple subagents.
• Agents that run the same tests or dev server can collide on ports; give each its own port.

Turn parallel agents into a team with jobs

Worktrees and agent teams split one task you're watching. Crewmark runs several Claude Code or Codex sessions as employees with their own roles, goals and working hours, and gives them work on one board.

1. One employee per role

   An SEO specialist, a software engineer and a UI designer each live in their own conversation, with their own instructions and goal.

2. One board for all of them

   Assign issues to whichever employee fits. Each wakes on its heartbeat, takes its next issue and comments as it goes, so you see who's doing what.

3. They ask you, not each other

   When an employee needs a review or a permission, it messages you and moves on. Read what an AI employee is.

Multiple Claude Code agents FAQ