Claude Code Parallel Sessions: How to Work on Multiple Projects Simultaneously
Claude Code now supports parallel sessions with split-panel views and a built-in terminal. Here's how to use them to ship faster across multiple repos.
Why Most Developers Are Still Working Sequentially
Most developers using Claude Code work one project at a time. One terminal, one session, one task. They finish a feature, switch repos, start fresh.
That approach is fine — until you’re maintaining multiple services, shipping across different repos, or waiting on an agent to finish something slow before you can start the next thing. At that point, sequential work becomes the bottleneck.
Claude Code parallel sessions fix this. The feature gives you split-panel views, a built-in terminal, and the ability to run independent Claude Code sessions side by side — all without juggling multiple terminal windows or losing context on any of them.
This guide covers how it works, how to set it up, and how to use it effectively across multiple projects.
What Parallel Sessions Actually Are
A Claude Code parallel session isn’t just two terminal windows open at once. It’s two fully independent AI agent contexts running simultaneously, each with its own:
- Working directory and file context
- Conversation history
- Tool permissions
- Active tasks
Each session operates independently. One can be refactoring a payment service while the other is writing tests for an authentication module. They don’t share memory, they don’t interfere with each other, and you can switch between them instantly.
The split-panel view is the UI layer that makes this manageable. Instead of alt-tabbing between terminal windows or managing multiple tmux panes manually, you get a native two-up view inside Claude Code itself — both sessions visible at the same time, with the built-in terminal available in either pane.
This is different from running multiple Claude Code instances in parallel browser agents, which is a more advanced setup requiring external orchestration. Native parallel sessions are built in — no extra tooling required.
The Split-Panel View: How It Works
Opening a Second Session
To open a second session alongside your current one, use the panel split control in the Claude Code UI. In most configurations, this is a button in the top bar or accessible via a keyboard shortcut (Cmd+\ on Mac, Ctrl+\ on Windows/Linux).
When you split the panel:
- Your current session stays in the left pane, exactly as it was
- A new session initializes in the right pane
- You can immediately set a working directory and start a new task in the right pane
The two sessions are fully independent from the moment the split happens. Changing directories, running commands, or making edits in one pane has no effect on the other.
Switching Focus Between Panes
Click anywhere inside a pane to focus it. Your keyboard input, commands, and prompts go to whichever pane is focused. The unfocused pane stays visible and continues running — it’s not paused.
This is the key advantage over alt-tabbing between windows. You can watch one session finish a task in your peripheral vision while actively working in the other. If you see the first session hit an error or complete a step, you can immediately focus it and respond.
Resizing the Panel Split
You can drag the divider between panels to adjust how much screen space each one gets. If one session is running a long autonomous task and you’re mostly just monitoring it, give it a smaller slice. When you need to actively read output or write prompts for it, drag it wider.
On a single monitor, a 50/50 split is workable but tight. On a wide or ultrawide monitor, parallel sessions start to feel genuinely comfortable — each pane has enough room to read code and output without scrolling constantly.
The Built-In Terminal: Why It Matters
Claude Code’s built-in terminal is available directly within each session pane. You don’t need to open a separate terminal application to run commands alongside your AI session — the terminal lives right there.
What You Can Do With It
The built-in terminal lets you:
- Run shell commands in the same working directory as the session
- Inspect file output, run test suites, or check git status without context switching
- Pipe results directly into your next prompt
- Monitor long-running processes (builds, test watchers, dev servers) while Claude works on something else
This is more useful than it sounds. Previously, the workflow was: give Claude an instruction, wait, open a terminal, check something, copy results back into the chat. The built-in terminal collapses that loop significantly.
Using the Terminal Alongside the Agent
The terminal and the Claude agent in each pane share the same working directory by default. If Claude navigates to a subdirectory or creates a file, the terminal reflects that immediately.
A common pattern: have Claude write a feature, then switch to the terminal to run your test suite, then paste the failing test output back into the chat. The tight integration makes that loop fast.
Setting Up Parallel Sessions for Multiple Projects
Here’s how to structure a practical multi-project workflow using Claude Code parallel sessions.
Prerequisites
Before you start:
- Claude Code installed and running (see the complete installation guide for Mac and Windows if you haven’t set it up yet)
- Two or more repos cloned locally (or use git worktrees — more on that below)
- A clear idea of what each session will be doing
Having vague tasks in multiple sessions is worse than having one focused session. The parallel setup amplifies both good and bad task definitions.
Step 1: Start Your First Session
Open Claude Code in your primary project. Set the working directory, add any relevant CLAUDE.md context, and give the agent a specific task to work on. If the task is autonomous and long-running, prompt Claude to proceed without asking for confirmation at each step.
Good candidates for the “background session” role:
- Running a full test suite and fixing failures
- Refactoring a specific module with a clear spec
- Writing documentation from existing code
- Updating dependencies and resolving conflicts
Step 2: Split the Panel and Set Up the Second Session
Once the first session is running, split the panel. In the new pane, navigate to your second project and start a different task.
Good candidates for the “active session” role (the one you’re interacting with more frequently):
- Feature development where you’re guiding decisions
- Code review and iteration
- Architecture decisions where you want to stay in the loop
Step 3: Alternate Your Attention
The rhythm of parallel sessions is: give one session a task long enough that it can run autonomously for several minutes, then switch to the other and work there. When the first session needs input or finishes, respond to it, give it the next task, and switch back.
You’re not managing two things simultaneously — you’re interleaving two workflows so that AI processing time in one session overlaps with your active work in the other.
This is especially powerful for tasks that involve waiting: builds, test runs, code generation for large files. The time Claude spends generating isn’t dead time anymore.
Combining Parallel Sessions With Git Worktrees
Parallel sessions work particularly well when paired with Claude Code’s git worktree support for parallel feature branches. Here’s why.
Each git worktree gives you a separate checkout of the same repository in a different directory. This means two sessions can work on two branches of the same repo simultaneously, without either one affecting the other’s working files.
Without worktrees, you’d have to commit or stash changes before switching branches — and if both sessions share the same checkout, they’d conflict. With worktrees, each session has its own directory, its own branch, and its own uncommitted state.
Setting Up Worktrees for Parallel Sessions
# From your main repo directory
git worktree add ../myapp-feature-auth feature/auth-refactor
git worktree add ../myapp-feature-payments feature/payment-apiNow point each Claude Code session to a different worktree directory. Session one works in ../myapp-feature-auth, session two works in ../myapp-feature-payments. They’re completely isolated even though they share git history.
When both branches are ready, you merge them normally. The parallel session work and the git branching strategy reinforce each other well.
Parallel Sessions vs. Agent Teams
Parallel sessions and Claude Code Agent Teams are different tools for different situations. Knowing which one to use saves a lot of confusion.
Parallel sessions are for independent work. Two separate tasks in two separate codebases (or branches). They don’t coordinate, they don’t share a task list, and neither knows what the other is doing. That’s fine — they don’t need to.
Agent Teams are for coordinated work on the same project. One orchestrator delegates sub-tasks to multiple agents that share context and a task list. The results get merged back into a coherent output.
If you’re working on a shared task list where multiple agents coordinate in real time, that’s Agent Teams territory. If you’re just doing two independent things at once, parallel sessions are simpler and require no setup overhead.
Think of it this way: parallel sessions are two developers working at separate desks on separate things. Agent Teams are a team in a war room working on the same problem from different angles.
Token and Context Management in Parallel Sessions
Running two sessions at once means two sets of context windows consuming tokens. This is worth being deliberate about, especially if you’re on a plan with usage limits.
A few practical guidelines:
Keep sessions focused. A session with a narrow task and a short context window is cheaper and faster than one that’s been chatting for an hour and accumulated a massive history. Start fresh sessions for new tasks rather than extending old ones.
Watch for context bloat. Long file inclusions, large diffs, and verbose tool outputs all expand the context window fast. In a single session you might not notice — across two, it adds up. There’s a deeper look at this in why your Claude Code session drains faster than it should.
Use /compact or /clear when appropriate. If a session has finished its task and you’re starting something new in the same pane, compact or clear the context before prompting again. You don’t need the old conversation to carry forward.
Assign effort levels intentionally. Not every session needs maximum reasoning depth. If one session is doing something mechanical (formatting, renaming, boilerplate), set it to a lower effort level to save tokens for the session that needs deeper reasoning.
Common Patterns That Work Well
These are real workflows that benefit meaningfully from parallel sessions.
Pattern 1: Active Development + Background Testing
One session writes new features while a second session runs the test suite on the codebase and reports failures. You write code in session one, periodically check session two, and incorporate test feedback into session one’s next prompt.
Pattern 2: Frontend + Backend Simultaneously
Frontend session works on the UI components. Backend session builds or updates the API endpoints the frontend will consume. If you’ve agreed on the API contract upfront (or let session one define it and pass it to session two via a shared spec file), they can progress in parallel.
Pattern 3: Refactor + Documentation
One session refactors a module. The other writes or updates documentation for the already-stable parts of the codebase. Documentation is a great background task — it doesn’t block anything, but it’s valuable and tends to get deprioritized.
Pattern 4: Experimental Branch + Stable Branch
One session maintains a stable main branch — hotfixes, dependency updates, minor improvements. The second session experiments on a feature branch. If the experiment fails, you haven’t touched main. If it succeeds, merge it in.
This pattern pairs especially well with the split-and-merge approach where sub-agents explore options independently before results get consolidated.
What Doesn’t Work Well in Parallel Sessions
Parallel sessions aren’t a fit for every situation. Knowing the limits saves you from frustration.
Shared file conflicts. If both sessions are writing to the same files at the same time without a worktree setup, you’ll get conflicts. Use worktrees, or make sure sessions operate on clearly separate parts of the codebase.
Dependent tasks. If session two’s task depends on session one finishing first, sequential is better. Parallel sessions don’t block or wait for each other. You’d have to manually coordinate the handoff.
Monitoring-heavy tasks. If both sessions need your constant attention, you’re not gaining anything. The value of parallel sessions is that at least one of them can run with minimal supervision. If both need you every two minutes, you’ll spend more time switching than working.
Context-heavy large codebases. Two sessions, each holding a large codebase in context, can hit rate limits faster than expected. For very large codebases, consider sub-agents for codebase analysis instead of loading everything into a session context.
Where Remy Fits in This Picture
Claude Code parallel sessions solve a real problem: working across multiple codebases simultaneously without losing your mind. But they still require you to have those codebases, manage that infrastructure, and maintain those sessions.
Remy takes a step back from that layer entirely. Instead of managing code, you write a spec — a structured markdown document that describes what your application does. Remy compiles that into a full-stack app: backend, database, auth, frontend, deployment. The spec is the source of truth. The code is the compiled output.
If you’re running parallel sessions because you’re managing multiple services, multiple repos, and multiple feature branches, Remy addresses the root cause. A single spec stays in sync with the application as it evolves. You’re not context-switching between branches — you’re working from a document that represents the whole thing.
It’s a different level of abstraction. Claude Code sessions work at the code level. Remy works at the application definition level. For teams building full-stack applications, that shift matters.
You can see what that looks like at mindstudio.ai/remy.
Frequently Asked Questions
Can I run more than two sessions in parallel?
Yes. Claude Code isn’t technically limited to two panels. You can open additional panes depending on your screen setup and Claude Code version. In practice, most developers find two to be the manageable limit — three or more starts to require more attention-switching than it saves. If you need more than three concurrent agents working on the same project, look at Claude Code Agent Teams for coordinated multi-agent orchestration.
Do parallel sessions share any context or memory?
No. Each session is fully independent. They don’t share conversation history, they don’t see each other’s tool calls, and they don’t coordinate unless you manually copy information between them. This is by design — it prevents interference and keeps each session focused on its own task.
Does running two sessions cost twice as many tokens?
Roughly, yes. Each session maintains its own context and makes its own API calls. The total token usage is approximately additive. How much this matters depends on your plan. If you’re concerned about usage, check out token management techniques for Claude Code and keep both sessions lean.
Can parallel sessions work across different machines or repositories?
Within the native parallel session UI, both panes run on your local machine. They can point to different local directories (different repos or different worktrees of the same repo). For running sessions on separate machines or in cloud environments, you’d need a setup like Claude Code headless mode or a remote agent configuration.
How is this different from just having two terminal windows open?
The split-panel view keeps both sessions visible simultaneously without alt-tabbing. More importantly, the built-in terminal integration means each pane is a full AI-plus-shell environment, not just a shell. You get the agent, the context, and the terminal in one place per pane. It’s meaningfully more organized than managing multiple terminal windows, especially once both sessions are actively generating output.
What’s the best way to hand off work between sessions?
A shared file works well. Have session one write its output, plan, or API contract to a markdown file in the project. Session two reads that file as context when it starts its task. This is more reliable than trying to copy-paste between chat windows and gives you a persistent record of what was agreed on.
Key Takeaways
- Claude Code parallel sessions let you run two independent AI agent contexts side by side in a split-panel view.
- Each session has its own directory, conversation history, and tool access — no interference.
- The built-in terminal in each pane collapses the context-switching loop between agent prompts and shell commands.
- Git worktrees are a natural complement: one worktree per session, one branch per feature.
- Parallel sessions work best when at least one session can run autonomously for several minutes at a stretch.
- Token usage is roughly additive — keep sessions focused and use
/compactto manage context. - For coordinated multi-agent work on a shared task list, Agent Teams is the better fit.
If you’re building full-stack applications and want to work from a higher level of abstraction than individual sessions and codebases, Remy is worth a look — spec-driven development that compiles annotated markdown into complete, deployed applications.
