Can I run two Claude Code sessions in the same folder?

Yes, Claude Code will start, but both sessions edit the same files and see each other’s half-finished changes. Give each session its own git worktree, or at least a strict folder boundary.

Do multiple Claude Code agents share one usage limit?

Yes. Every session signed in to the same account draws from the same 5-hour and weekly limits, so four agents use them up roughly four times faster.

How many Claude Code agents can I run at once?

There is no hard cap in Claude Code itself. In practice two to four is what one person can follow; limits and review time are the real ceiling.

How do I merge the work of parallel Claude Code agents?

Treat each worktree as a normal branch: run the tests there, push it and open a pull request, or merge it locally. Merge one branch at a time and rerun the tests after each.

How to run multiple Claude Code agents in parallel

One Claude Code session works through a task step by step. While it reads files and runs tests, you wait. Running several Claude Code agents in parallel turns that waiting time into work: one agent builds the API, another writes the tests, a third fixes a bug that has nothing to do with either.

This post goes from the simplest setup to the most comfortable one: plain terminals, tmux, git worktrees, Claude Code’s own parallel sessions and finally AgentVera. Each step adds something the previous one lacked. At the end there’s a list of the pitfalls that usually bite: merge conflicts, limits and tokens.

Can you run more than one Claude Code agent at a time?

Yes. Claude Code is a CLI; every time you run claude you start an independent session with its own conversation and context. Nothing stops you from starting five. What can go wrong is not starting them but coordinating them: two sessions in the same folder will happily edit the same file, and all sessions signed in to one account share its limits.

So the real question is how to keep them apart and how to follow them.

Option 1: separate terminal windows

The quickest setup is a terminal tab per agent:

# tab 1
cd ~/code/acme-web && claude
# tab 2
cd ~/code/acme-web && claude

It works for small, clearly separated tasks. Tell each agent in its first message which folders it may touch (“only src/api/”, “only tests/”).

The downsides show up fast: you can’t see which tab is waiting for approval, both sessions share one working copy, and when one agent runs git checkout, the other is suddenly on a different branch.

Option 2: tmux

tmux keeps sessions alive when you close the terminal and lets you see several panes at once:

tmux new-session -d -s agents -c ~/code/acme-web
tmux split-window -h -t agents -c ~/code/acme-web
tmux send-keys -t agents:0.0 'claude' Enter
tmux send-keys -t agents:0.1 'claude' Enter
tmux attach -t agents

Now both agents are visible side by side and survive a closed laptop lid (as long as the machine stays on). tmux solves visibility, not isolation: both panes still edit the same folder.

Option 3: a git worktree per agent

Git worktrees are the standard answer to “two agents, one repository”. A worktree is a second working folder on its own branch, sharing the same .git history:

cd ~/code/acme-web
git worktree add ../acme-web-api -b feat/api
git worktree add ../acme-web-tests -b feat/tests

cd ../acme-web-api && claude     # agent 1
cd ../acme-web-tests && claude   # agent 2

Each agent now has its own files and branch. One agent’s git checkout or half-written file doesn’t affect the other. When an agent is done, its branch is merged like any feature branch.

A few practical notes:

Install dependencies per worktree. node_modules, virtualenvs and build output are not shared. Run pnpm install (or equivalent) in each new folder.
Copy local config. .env files are usually ignored by git, so they don’t appear in a new worktree.
Ports collide. Two dev servers on port 3000 won’t start; give each worktree its own port.
Clean up. git worktree remove ../acme-web-api when the branch is merged, and git worktree prune for folders you deleted by hand.

The details are in git worktrees for parallel agents.

Option 4: Claude Code’s own parallel sessions

Anthropic’s Claude Code desktop app can run parallel Claude sessions, each in its own worktree, without you typing the git commands. If you only use Claude and want the official tool, this is a reasonable stop. It covers isolation and a basic overview.

What it doesn’t try to do: run other CLIs such as Codex or Gemini CLI next to Claude, pass one agent’s output to another automatically, or move an agent to a different account when a limit runs out. That’s where a dedicated multi-agent app comes in. For a comparison of the options, see best tools to run multiple AI coding agents in parallel.

Option 5: AgentVera

AgentVera opens the claude command on your machine in real terminals and lays the agents out in a grid per project. It uses Claude Code’s own login, so your Pro or Max plan works as it is. Here’s how the earlier problems map to its features:

Problem	In AgentVera
Can’t see which agent needs you	Grid from 1×1 to 5×4; each pane shows status and live context size; agents waiting for approval are listed in the status bar
Agents edit the same files	Worktree panel: create a worktree from a branch and start an agent directly in it
Two agents touch one file anyway	A file-conflict warning: when two agents edit the same file in the same folder, both the agent and you are told; nothing is blocked
Output has to be copied by hand	Flows send one agent’s reply to another through a template
Limit runs out mid-task	Account switching moves the agent to the next Claude account and copies the conversation
Context grows every turn	Automatic `/compact` at a threshold you set, plus context profiles

Step by step

Add the project folder. Pick it from the projects screen. A Git repository is recommended.
Create worktrees. In the right panel, open the worktree list and create one per task from a new branch, for example feat/api and feat/tests.

Open the agents. Under New agent, pick Claude Code, choose the worktree, and give the agent a name, model, effort and a short role:

Work only under src/api/. Don't change tests.
Run pnpm test api after each change.
Finish with a bullet list of what you changed.

Lay out the grid. A 2×2 layout fits two Claude agents, a Codex reviewer and a terminal running the dev server.
Connect them if needed. A flow can send the API agent’s final summary to the test agent when its turn ends. A turn limit stops two agents from looping.
Review and merge. Automatic code review checks each finished turn. The Git panel shows each worktree’s changes and how far it is ahead of main; merge one branch at a time.

The grid, worktrees and code review are on the free plan. Flows and account switching are on Pro.

Pitfalls and how to avoid them

Merge conflicts

Worktrees prevent agents from overwriting each other while they work; they don’t prevent conflicts when you merge. Two agents that both edit src/routes.ts on different branches will still conflict at the end.

Split tasks by folder or module, not just by branch.
Keep shared files (route tables, schemas, lockfiles) with one agent.
Merge the smaller branch first, then rebase the other worktree on main and let its agent fix the conflict: git rebase main inside that worktree, then ask the agent to resolve and rerun the tests.

Usage limits

All sessions on one account share the same 5-hour and weekly limits. Four agents don’t get four times the quota; they reach the limit four times faster. Check /usage in Claude Code regularly, and plan heavy parallel sessions early in a limit window. If you legitimately have more than one account (say, personal and work) and the provider’s terms allow it, account switching keeps a task going when one runs out. Read more in Claude Code usage limits.

Token use

Each agent carries its own context: system prompt, tool definitions, CLAUDE.md, MCP servers and every file it has read. That baseline is re-read on every turn, per agent.

Give agents narrow, concrete tasks so they read fewer files.
Run /compact before a long conversation gets expensive, or let it run automatically at a threshold.
Turn off MCP servers an agent doesn’t need.
When passing output between agents, send the summary, not the whole transcript.

Measured numbers are in cutting Claude Code token usage.

Approvals that block

An agent waiting for permission stops while the others keep going. With five panes it’s easy to miss one. Either keep an eye on the status, use notifications, or allow safe actions (reading files, running tests) in your Claude Code permission settings so agents ask less.

Too many agents, too soon

The bottleneck moves from the agents to you. Reviewing four branches takes longer than reviewing one. Start with two agents on clearly separate tasks, and add a third once that works.

A minimal checklist

One worktree per agent that might touch shared code
Dependencies installed and .env copied in each worktree
Each agent’s role names its folders and its goal
Separate ports for dev servers
A plan for merging: which branch first, who resolves conflicts
An eye on /usage and context size

Wrapping up

Running several Claude Code agents in parallel is mostly about isolation and attention. Worktrees give each agent its own files; tmux or a grid lets you see them all; short roles and a merge plan keep the result reviewable. Plain terminals and worktrees are enough to start. When you want a grid, flows between agents and help with limits, download AgentVera for free and open your first two Claude Code agents. For the general method, see parallel coding agents.