Run multiple Claude Code instances at once

You have Claude Code running in one terminal and another job waiting. The obvious move is a second terminal window and a second claude. That works. It is the same binary and the same login, and every pane runs against the CLI account you connected, so parallel sessions draw on that one account in parallel. DeckSpace cannot pool or raise a provider allowance, and its own usage total is not your provider's invoice.

The problem is not the second process. It is the shared working directory. Two agents editing one checkout have no view of each other: each reads a file, decides what to change, and writes back over whatever landed in between. More terminals scale that hazard linearly. Isolation fixes it, and isolation means separate checkouts, not separate windows.

What a second terminal gives you, and what it does not

Both sessions run properly. Each is its own process with its own conversation, its own context and its own permission prompts. What is missing is everything between them.

• No shared view. Neither session can tell you what the other changed. You find out by reading the diff afterwards.
• One index, one HEAD. Both sessions stage into the same git index. A broad git add from one picks up the other's half-finished work, and the commit that follows carries it.
• Overlapping writes. When two agents own the same file, the second write wins, and the first agent is now planning against a file that no longer says what it read.
• No way to throw one away. Undoing one agent's work means unpicking it out of a tree that also holds the other's.

DeckSpace treats the last point as the important one. A swarm builder never works in your project directory: each task gets its own branch and its own git worktree, so a run you do not want is deleted rather than unpicked.

What a pane is

A pane is a terminal. A pane running an agent is the same terminal with an agent CLI as its process. Underneath, each pane is backed by a real pseudo-terminal, running either a plain shell or the agent binary itself.

DeckSpace ships no model and proxies nothing. It resolves the command on your login-shell PATH and spawns it, so your authentication, your config and your subscription come along unchanged. It is your CLI running, on your machine.

The two launch paths differ. Launching into an existing pane types the command into a shell that is already running, so your profile is sourced as usual. Launching into a new pane makes the CLI the pane's own process, which never sources your profile; the missing variables are injected instead.

How to open several Claude Code panes at once

Open the workspace wizard from the + button in the left rail. It has four steps, and two of them matter here.

• Start. Name the workspace and leave the type on Standard, which is the terminal grid.
• Layout. Pick the project folder, then how many terminals. The buttons offer 1, 2, 4, 6, 8, 10 and 12.
• Agents. Pick one detected CLI — Claude Code, if it resolved on your PATH — and, if you want, a first prompt.
• Finish with Open with <agent> in every pane. DeckSpace waits for each pane's terminal to come up, then types that agent's launch command into it. Open empty workspace gives you the same grid with plain shells to type into yourself.

One CLI is chosen for the whole grid; the wizard has no per-pane picker. Panes whose terminal does not register within eight seconds are skipped, and the pane is there and usable, it just never receives the launch. Afterwards you add panes one at a time with the split buttons in a pane header, or from the command palette, whose layout presets are 1, 2, 4, 6, 8 and 12 with Add pane for anything else.

The pane ceiling

A workspace holds up to 16 panes. Sixteen tile four by four, twelve tile four by three. The two split buttons in a pane header, split right for a new column and split down for one stacked below it, both go disabled once the workspace holds 16.

What happens when you ask for a seventeenth depends on which launcher you used. Every manual path tells you what it did. A swarm launch is the exception, and it is covered below.

• Launching into a new pane falls back to launching into the active pane.
• The orchestrator logs that the pane limit is reached and waits for a task to finish.
• Voice and Team error back to you and say the grid is full.
• A portable handoff or a saved-session recovery refuses outright and preserves the original, rather than landing in an agent that is already busy.

Closing a pane kills its shell and any agent inside it, which is how you free a slot. Panes belong to a workspace rather than to the app, so switching workspaces swaps the grid and leaves the hidden one running.

Panes in one directory, or a worktree each

Panes in a single folder are the right shape when the work does not overlap on disk: one agent writing a feature, another reading the test output, a shell you drive yourself for git. They share your checkout because you want them to.

The moment two of them need to write, give them separate checkouts. Swarm splits a goal into tasks and, for each one, runs git worktree add with a new branch pointed at HEAD, then points that builder's pane at the new checkout. Discarding a builder runs git worktree remove --force and then deletes the branch. That flag overrides git's own refusal to remove a worktree with modified files, so a discard throws away uncommitted work with no second prompt. Merge goes the other way: it commits the worktree, writes a checkpoint snapshot of your repo, then merges.

Some limits before you plan around it.

• The builder list is truncated to 12 before any worktree is created, and the roster field clamps to the same number.
• Planning, scouting, reviewing and PR writing run as headless Claude Code calls. Without Claude Code among your detected CLIs the planner returns a single task, your goal verbatim, and you get one builder however many you asked for. The only warning is a log line reading Plan: 1 builder task(s). Builders themselves can be any detected CLI.
• If the grid is already at 16 when a swarm launches, the extra panes are not created. The branch and the worktree still exist and the task still appears, and the log says the pane did not start in time.
• Builders launch at auto-edit, or at full when the app-wide walk-away toggle is on. They never launch in plan mode.
• The Sandbox checkbox is passed to the headless calls, not to the builder panes.
• A builder's working directory is a path under your system temp directory, not your project root. Anything you write that groups or filters panes by directory will miss every worker.
• Starting a swarm run needs an active subscription. Opening the room and reading a previous run does not.

What is still yours to do

Overlap warnings are advisory. Before dispatch, DeckSpace counts how many tasks claim each path and logs a line for any path claimed twice. It is a log line: it does not stop the launch, and it compares only what the planner declared, not what the builders go on to edit.

The real collision check happens later. At review time the merge is predicted with git merge-tree --write-tree against your current HEAD, without mutating anything, and the conflicting paths are listed on the task card. Choosing which implementation wins is yours. Nothing merges on its own.

Two things are worth planning around. Panes and their processes die with the app, so reopening a swarm run adopts it rather than restarting it: the plan, the branches and the worktrees come back, and nothing is spawned. And because worktrees live under the temp directory, macOS reaps them after a few days; a task whose worktree is gone loses its Review, PR and Merge buttons.