Mastering Parallel Claude Code Sessions: A Guide to Multi-Agent Workflows

You start a task in one terminal. It is going to take five minutes, so you open a second tab and start something else. Then a third, because why not. Twenty minutes later you have six terminals open, one of them has been sitting blocked on an approval prompt for the last four minutes, and you have no idea which one it is or which branch it is working on.

The bottleneck in parallel Claude Code sessions is not the agents. It is you. Every agent you add is another piece of state you have to hold in your head: what you asked it to do, which branch it is on, whether it finished, whether it is waiting on you right now. The agents scale. Your attention does not.

We call this context thrashing. You are not writing code anymore, and you are not really supervising agents either. You are tabbing through terminal windows trying to find the one that beeped.

This guide is about making parallel Claude Code sessions survivable: giving every agent a stable address you can find it at, keeping sessions alive and named so you can navigate them, and cutting down the number of times an agent has to stop and ask you something. It also covers the point where hand-rolled tooling stops scaling and you want a cockpit instead, which is the reason we built fleet.

Why Single-Session Claude Code is a Bottleneck

Software development is naturally parallel. You are waiting on a slow integration suite, or a deployment, or a code review. In a single-threaded workflow, you are blocked.

With Claude Code, one agent runs in a loop: it reads, thinks, edits, and tests. While it works through a ten-minute task, that terminal belongs to it. You cannot easily ask it to fix an unrelated bug or start drafting tests for another feature without interrupting the run.

So you open a second tab. This is the correct instinct, and it is where the trouble starts. You have traded a throughput problem for an attention problem, and the second one is harder to notice because it feels like progress.

How do I run multiple Claude Code sessions at once?

Nothing stops you. Open a new terminal tab and run claude again. Claude Code does not lock a directory or prevent concurrent sessions, so you can run as many as your machine and your API limits allow.

Starting them is trivial. Keeping track of them is the actual work, and it is why the rest of this guide exists. Running several agents in one directory has a secondary problem too, which is that they will overwrite each other's uncommitted changes. Isolation solves that, but it also solves something more valuable: it gives you a way to tell your agents apart.

The Context Thrashing Problem

Every running agent carries state that lives in your head. What did you ask it for? Which branch is it on? Has it finished, or is it mid-loop? Is it blocked on an approval right now?

A terminal gives you none of this. It gives you tabs. A tab is a rectangle of scrollback with no label describing what the agent inside it is doing, so the only way to answer any of those questions is to switch to it and read.

That switch is the expensive part. Every time you jump into an agent's terminal, you have to reconstruct the task from its scrollback before you can judge whether its last step was right. Do that six times in a row and you have spent ten minutes doing nothing but reloading context, which is exactly the cost you were trying to avoid by parallelizing in the first place.

The failure mode this produces is idle agents. An agent hits an approval prompt and stops. You do not notice, because you are three tabs away reconstructing what a different agent was doing. It sits there, finished with its real work, waiting on a keystroke. Your throughput quietly drops back to one agent at a time while you keep paying for six. Nothing in a terminal tells you this is happening. Something has to be watching the sessions for you.

The Parallel Powerhouse: Using Git Worktrees with Claude Code

The first fix is to give every agent its own address. This is what git worktrees are for.

Can Claude Code use git worktrees?

Yes, and it is the cleanest way to run parallel Claude Code sessions.

A git worktree lets you have several working directories attached to one repository. Each is a real directory on disk with its own checked-out branch, but they all share the same .git directory.

The obvious benefit is isolation: agents cannot corrupt each other's uncommitted work, and one agent's commit cannot accidentally sweep up another's half-finished changes. The benefit that matters more day to day is legibility. One agent, one directory, one branch, one task. The directory name tells you what the agent inside it is doing, and git worktree list becomes a roster of everything you currently have in flight.

Some developers reach for VS Code multi-root workspaces instead. That works for browsing several folders at once, but Claude Code is a command-line tool, and a terminal-centric worktree setup keeps each agent in its own shell where you can run its tests in isolation and jump between them by name.

How to set up your first worktree

Use git worktree add, which creates the directory and checks out a new branch in one step.

Name the directory after the task, not the ticket number. ../fix-checkout-timeout tells you what the agent is doing at a glance; ../feature-4412 sends you back to your issue tracker to find out.

1. Create a new worktree directory and branch: git worktree add ../fix-checkout-timeout -b fix/checkout-timeout
2. Navigate into the new worktree: cd ../fix-checkout-timeout
3. Start your parallel Claude Code session: claude
4. When the task is merged, remove the worktree: git worktree remove ../fix-checkout-timeout

Repeat for each task you want running concurrently. Each agent now has a stable home you can return to, and a branch you can review independently.

That is four commands for every agent you start, and you will run them a lot. Fleet collapses the whole sequence into one keystroke, which we get to below.

How do I manage context across parallel Claude Code agents?

The goal is to make any agent cheap to pick back up, so that switching to it does not require reading its entire scrollback.

Each worktree is a separate directory, and Claude Code scopes a session's history to the directory it was started in, so agents do not share conversation context or tool call history with each other. That isolation is what you want. What you do not want is for every agent to need a different explanation of how your project works.

1. Use CLAUDE.md for project rules: Put a CLAUDE.md at the root of the repository with your build commands, test commands, and conventions. Every worktree picks it up automatically, so you never re-explain the basics to a new agent.
2. Isolate environment variables with direnv: Use direnv to load per-worktree environment variables such as database URLs or ports when you enter the directory, so two agents do not fight over the same local service.
3. Keep tasks small and scoped: A task an agent can finish in ten minutes is a task you can evaluate in thirty seconds. Open-ended assignments produce long transcripts that are expensive to re-enter, and they burn context window until the agent starts forgetting its own earlier decisions.

Session Persistence with Tmux and Claude

Worktrees give each agent an address. Tmux gives you a way to navigate to it.

Does Claude Code support tmux?

Yes, Claude Code runs fine inside tmux, and pairing the two is what makes a parallel setup navigable.

Two things change once your sessions live in tmux. First, they survive. A long agentic loop no longer dies because you closed a window or your SSH connection dropped. Second, and more importantly, every session gets a name.

Give each tmux window the name of its worktree. Now your agents are addressable: instead of clicking through six anonymous tabs to find the one that beeped, you jump straight to the one you want by name. You can also split a window into panes so an agent's session and a live tail of your test output sit side by side, which removes one of the most common reasons to switch away in the first place.

Check on an agent, answer its prompt, and jump back, all without hunting through tabs.

This is the floor, not the ceiling. Tmux gives your sessions names, but it has no idea what is inside them. A window called fix-checkout-timeout looks identical whether the agent in it is mid-edit, blocked on an approval, or finished ten minutes ago. To find out, you still have to attach and read, which is the exact cost you were trying to remove.

Fleet: One Cockpit for All Your Parallel Sessions

What is missing is something that knows the state of every agent without you having to go and look. That is what we built fleet for. It is an open-source terminal cockpit that puts every session's status in one sidebar — running, waiting on you, finished, idle, error — grouped under the repo it belongs to, so the whole picture is on one screen instead of in your head. It supports Claude Code, Codex, and OpenCode, and you choose the agent per session, so a Claude Code session and a Codex session can run side by side in the same repo.

How do I know which Claude Code agent is waiting on me?

Fleet reads it from the agent itself. Claude Code emits hook events as it works, and fleet listens to them, so a session flips to waiting the moment the agent stops to ask you something, and back to running the moment you answer. Codex and OpenCode report the same way. Most session managers scrape the terminal pane and infer state from what the text looks like, which is why they lag and misreport. Five states — running, waiting, finished, idle, error — sitting in the sidebar next to each session, reliable enough to act on without opening anything.

Then the loop gets short. Space jumps to the next session that needs attention. Enter drops you in to approve or steer, Ctrl+Q detaches, and you are on to the next one. If you already trust what it is asking for, Y approves it without attaching at all. The tab hunt from the top of this article stops existing.

The rest of it works toward the same end, which is keeping you out of terminals you have no reason to be in:

1. Any of three agents, per session: a starts a session with your default agent, A opens a picker for Claude Code, Codex, or OpenCode. Status, resume, and auto-naming behave identically across the three, because each one is read through its own hook events rather than a generic keystroke shim.
2. Worktree sessions in one keystroke: w opens a branch picker, creates the worktree, and starts an agent inside it. Same git plumbing as above, none of the typing.
3. PR state on the repo header: branch, dirty state, CI result, review state, and unresolved threads, so you can tell a finished agent apart from a mergeable one. Needs the gh CLI, and is optional.
4. Forking a session: f branches the agent's conversation at that point, so you can try a second approach without throwing away the first. Both keep running.
5. Resume that actually resumes: r restarts a session where it left off through the agent's own resume, by session ID, not a replayed transcript.
6. Agents that open their own sessions: run fleet skill install once and your agents learn fleet's command line. After that, when one of them reaches a piece of work that can run independently, it opens a fresh worktree session and hands the job off itself with fleet wt fix-242 -p "…", or messages a session already running with fleet send, instead of stopping to tell you to go and do it. It is opt-in, and fleet skill uninstall takes it back out.

It runs on tmux underneath, so nothing in the previous section is wasted work. Install it and start it:

brew install brizzai/tap/fleet
fleet

Apache 2.0, macOS and Linux, and the source is on GitHub.

Scaling with MCP and Parallel Agents

The other way to reduce context switching is to reduce how often an agent needs you at all.

Every time an agent lacks information, it either stops and asks or wastes turns searching for it. The Model Context Protocol (MCP) is an open standard for connecting AI models to data sources, and running an MCP server lets your agents fetch what they need directly instead of interrupting you or reading half your codebase into context.

1. Shared database schemas: Agents query the live schema through a tool call rather than reading migration files and guessing at the current state.
2. Centralized documentation: Internal API definitions live in one place that every parallel session can reach, so you are not pasting the same reference into six terminals.
3. Live system status: Agents check environment health or test results themselves instead of stopping to ask whether something is up.

Each of these removes a reason for an agent to go idle waiting on you, which is the specific failure that makes parallel sessions underperform.

Fewer interruptions is the other half of the answer. Worktrees make your agents distinguishable, fleet makes them legible, and MCP means they need you less often to begin with. There is more on where the cockpit idea came from in mission control for Claude Code.

Observing the Chaos: Analytics for Parallel Agents

Once several agents run at once, your development environment is a distributed system, and you need to answer questions about it that scrollback cannot answer. Which agents are burning tokens without converging? Which tools fail often enough to stall a run? Where did the last hour of spend actually go?

Traditional monitoring does not help much here. It tracks latency and request counts, not whether an agent chose a sensible tool or made progress on the task. At Brizz we work on AI agent analytics for exactly this. When running parallel Claude Code sessions, the things worth watching are:

1. Tool error rates: A tool that returns vague failures makes agents retry blindly and stall. See the AI agent error handling contract for what a good failure response looks like.
2. Token spend per session: Parallel sessions multiply cost as fast as they multiply output. Catch runaway loops before the invoice does.
3. Session outcomes: Did the agent solve the problem, or did it produce code that compiles and passes lint while breaking the actual behavior?

Best Practices for Parallel AI Development

Parallel agents are fast, but only with guardrails that keep the coordination cost off your shoulders.

Is parallel vibe coding safe?

Not by default, but the risks are ordinary concurrency risks and they respond to ordinary discipline. Unsupervised agents on a shared branch produce broken builds and painful merges. Isolated agents on scoped tasks with frequent commits do not.

1. One agent, one worktree, one branch: Never run an agent directly on your main branch, and never run two in the same directory.
2. Name worktrees after tasks: Your directory list should be readable as a status board without opening anything.
3. Keep tasks small and commit often: Small units are easy to review and cheap to roll back when an agent takes a wrong turn.
4. Check in on a cadence, not on every beep: Sweep your sessions every few minutes instead of reacting to each notification. Reacting is what turns six agents into six interruptions.
5. Give yourself one place to look: past three or four agents, checking in on a cadence only works if a single screen shows you all of them at once. That is the entire job fleet does.
6. Instruct, then enforce: Ask for the test suite after significant edits in your CLAUDE.md. If it actually has to happen every time, wire it as a hook rather than a request.

The Bottom Line

Running parallel Claude Code sessions is easy to start and surprisingly hard to sustain, because the limit is your attention rather than your tooling. Give every agent a worktree so you can tell them apart, keep them in named tmux sessions so they survive and stay reachable, use MCP so they interrupt you less, and measure what they are doing so you are not guessing. Then stop carrying the whole picture in your head. Run brew install brizzai/tap/fleet, start fleet, and let it tell you which agent needs you.