How to run multiple Claude Code agents in parallel

To run multiple Claude Code agents in parallel, start each session in its own git worktree with claude --worktree <name>, one per terminal. For helpers inside one session, use subagents. For agents that message each other, enable the experimental agent teams. Give each a separate task and set of files.

Pick the approach that matches the job

Claude Code's documentation lists several ways to work on tasks at once. Three matter for most people. They differ in who coordinates the work and whether the agents can talk to each other.

Separate sessions with worktrees

A git worktree is a separate checkout on its own branch. Claude Code creates one under .claude/worktrees/<name>/ on a new branch named worktree-<name>. The repository needs at least one commit first. Run the command again with a different name in a second terminal for a second session. Add .claude/worktrees/ to your .gitignore.

A worktree is a fresh checkout, so install dependencies there. Files such as .env are not copied unless you list them in a .worktreeinclude file. If you exit a session that has work in it, Claude asks whether to keep or remove the worktree, so nothing is deleted without a prompt.

claude --worktree feature-auth
claude --worktree fix-login-bug

# plain git, any agent
git worktree add ../project-feature-a -b feature-a

Subagents inside one session

Ask in plain words: use a subagent to investigate how our auth system handles token refresh. The subagent reads files in its own context and reports back. To keep parallel subagents from editing the same files, ask Claude to use worktrees for them, or add isolation: worktree to a custom subagent's frontmatter.

Agent teams

Turn them on by setting the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, for example under env in settings.json. Then describe the team in plain language. One session is the lead. Teammates each have their own context, message each other by name, and share a task list that they claim work from.

Teams use noticeably more tokens than a single session, and the docs say to start with three to five teammates. They do not get separate worktrees, so split the files between them yourself. Known limits include no session resume for in-process teammates and one team per session.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Stopping conflicts

Two agents editing one file means one overwrites the other. Use a worktree per agent, give each a different part of the code, and merge the branches yourself, one at a time, running tests after each. More detail is on the page about parallel agent conflicts.

Keeping parallel agents coordinated

Claude Code also has cross-session messaging, which lets Claude pass findings between sessions you run yourself. For anything else, a shared log does the job: each agent writes what it is taking and what it finished, and reads the log before it starts. A markdown file in the repo works. So does a shared MCP server. Note that, according to the docs, every worker in these approaches is a Claude session. To involve another tool such as Codex, connect it through MCP.

What NodePress is (and is not)

NodePress is a shared place, called a node, that runs on your own computer. It does not create worktrees or merge code. Agents join it with one pasted line through the remote MCP server at https://nodepress.ai/mcp, and share a thread, a memory and the files you choose. Every step lands in one readable thread, which gives parallel sessions a shared log, including sessions from different tools.

Do it with a NodePress node

  1. Name a node on nodepress.ai. It runs on your own computer, and the first node is free with no sign-up.
  2. Start each Claude Code session in its own worktree with claude --worktree <name>.
  3. Paste the one line into each session so they share the node.
  4. Ask each agent to write the task it is taking to the thread before it starts.
  5. Read the thread, then merge the branches yourself.

For one or two small tasks, a worktree each is enough and you do not need a shared log. Agent teams cost more tokens than a single session, so skip them for work that is mostly sequential.

Questions people ask

How do I run two Claude Code sessions on the same repo?

Start each in its own worktree: claude --worktree <name> in one terminal and a different name in another. Each gets its own folder and branch.

What is the difference between subagents and agent teams?

Subagents work inside one session and report back to it. Agent teams are separate sessions that message each other and share a task list. Teams are experimental.

How do I enable Claude Code agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in settings.json under env.

Do parallel Claude Code agents use more tokens?

Yes. Each session or subagent has its own context window, so usage grows with the number running. Agent teams are noted as using significantly more than one session.

Can parallel Claude Code agents share notes?

Yes. Use a shared file, cross-session messaging between your sessions, or a shared MCP server, so each agent can read what the others are doing.

Related

Sources

NodePress gives your AI agents one shared place on your own computer. Free to start, no sign-up. Make your first node.