How to run multiple Claude Code sessions
Updated 2026-09-13
Start a second session in a second terminal
To run multiple Claude Code sessions, open a second terminal tab, change to the directory for its task, and run claude there. That is a second independent session. Repeat for additional tasks. Terminal tabs or tmux panes are the baseline; you do not need a special workspace app to start multiple Claude Code instances.
For example, after creating two separate project checkouts or worktrees, run this in the first terminal:
cd ../repo-feature-x
claudeIn the second terminal, run:
cd ../repo-feature-y
claudeSessions using the same subscription share that subscription and its rate limits. Opening ten terminals does not create ten usage allowances. Independent conversations also do not establish file isolation: two sessions in the same checkout can overwrite each other's edits. Separate worktrees give each implementer its own working files and branch.
Start with two bounded tasks before scaling the arrangement.
If both agents need to rewrite the same interface, settle that interface first or run the tasks sequentially.
Give each implementer a directory and an owner
For Claude Code parallel agents, assign one writing agent to each checkout. Different subdirectories within one checkout can reduce overlap, but shared files such as package.json and the lockfile remain exposed. Use separate repositories for unrelated projects or a worktree per implementer for branches of the same project.
Write down the branch, allowed paths, acceptance check, and files the agent must leave alone. A useful assignment is specific enough to review without reading the whole conversation:
Implement the empty search state on feature/search-empty.
Work in src/search/ and its existing tests.
Do not change package.json or shared navigation.
Finish with changed paths, checks run, and unresolved questions.SpeakCode does not create or manage worktrees.
Create them yourself using the parallel worktrees guide, then point each terminal at the intended directory. Before starting an agent, run pwd and git branch --show-current in its shell. A card name is a useful reminder, but the shell's actual directory determines which files the session sees.
Put one agent on each SpeakCode terminal card
SpeakCode hosts the real Claude Code CLI in terminal cards on a canvas. The desktop app requires macOS 26 or later and costs $20/month or $200/year, with no free trial. Your provider account supplies the AI usage separately. The parallel agents overview describes the workspace around these terminals.
Create one terminal card per agent, enter its worktree directory, and launch claude. Name cards after their assignment, such as feature/search-empty, rather than leaving yourself to remember which of several identical prompts owns a change. Add the role when two cards inspect the same branch: review/search-empty is distinct from its implementer.
In the tool rail, choose Arrange menu → card spacing → Small to fit more cards per viewport. Small packs cards edge-to-edge and affects arrangement and placement. Drag the cards into groups that match your assignments.
Zoom out to navigate the group. Below a zoom threshold, level-of-detail rendering replaces live terminal views with lightweight placeholder cards. Zoom back in to read output and type into a particular terminal. The placeholders help you navigate a larger canvas; they are not a substitute for reading a review or permission request.
Build a realistic ten agent layout
Use a ten agent layout as a capacity plan, with ten terminal cards: six implementers, two reviewers, one test shell, and one scratch shell. This example runs eight agent sessions and two ordinary shells. If you need ten actual agent processes, add their isolated assignments separately; the shells do not become agents because they occupy cards.
| Cards | Assignment | Directory rule |
|---|---|---|
| 1–6 | Six bounded implementation tasks | Six separate worktrees and branches |
| 7–8 | Review completed changes | Inspect the assigned worktree after its writer pauses |
| 9 | Run one branch's test command | Same worktree as the selected implementer |
| 10 | Inspect Git state and prepare commands | Main checkout, with no concurrent editing agent |
Place the six implementers in two rows of three, the reviewers beside them, and the shells below. These are suggested positions, not a built-in layout preset. Start two implementers first, inspect their first results, then start more only when the assignments remain independent.
Give each reviewer one completed change at a time. Ask it to report findings without editing, and keep the implementing agent paused while that review runs. Before moving a reviewer or the test shell to another branch, finish the current process and verify the new working directory. Do not connect all six implementers to a single busy test shell and expect serialized delivery.
Read status before interrupting a session
Each terminal has an idle, working, waiting, or exited phase indicator.
The agent inbox gathers agents waiting on you across cards, with a standup-style summary. Use it to find the next session that needs attention, then read that session's terminal before answering.
The node's Activity feed provides the event detail. A waiting phase alone cannot tell you whether a turn completed, output became quiet, or the agent requested input. Without explicit hooks, quiet-output settling is an estimate and can fire during a pause.
Enable Claude Code's Stop and Notification hooks using the agent status hooks guide. These make completion and notification events explicit. Verify one completed turn and one real input notification before depending on them across six implementers. A completion event establishes that the turn ended; it does not establish that the task succeeded.
Chain a test run after one agent finishes
Start a shell in the same worktree as the selected implementer. For a project whose test script is npm test, run it manually once from the package directory so you know the dependencies and command work there.
Connect the implementer's sending belt port to that shell card. Open the belt inspector, select Run command, and enter:
npm testLeave the shell running at an available prompt. When the agent finishes its turn, the belt submits the fixed command plus Enter. Press Enter can instead submit a command you already typed, while Deliver output sends the last 40 non-blank lines of captured screen text. Use the fixed command mode for repeatable tests.
Read the belt handoff guide before extending this recipe. Delivery is dropped if the target is stopped, and a belt does not wait for a busy target. Recheck the destination before another source turn. A green test result still needs to be read in the context of the branch and changes tested.
Stop adding sessions when review becomes the bottleneck
Six simultaneous implementers can consume a shared provider allowance faster and produce six changes needing review at once. Rate limits, local CPU and memory, and your attention can each set a lower useful concurrency than the number of cards that fit on screen. Reduce active work when sessions spend more time waiting than completing useful tasks.
Treat review debt as unfinished work. If 4 branches are waiting for review, pause new implementation and clear those branches before opening another session. Record which checks ran against which branch, especially when one test shell serves several tasks sequentially.
Keep worktree creation and cleanup in your Git workflow; SpeakCode does not manage that lifecycle. Begin with two isolated sessions, verified hooks, and one observed test handoff. Expand the arrangement when you can still explain who owns each branch and what must happen before it is ready to merge.
Questions
Can I run multiple Claude Code sessions on one subscription?
Yes. Sessions using the same subscription share its usage allowance and rate limits; opening another terminal does not add capacity.
Does SpeakCode create a worktree for each agent?
No. Create and manage worktrees yourself, then change each terminal to the directory assigned to its agent.
Does the ten-card recipe run ten AI agents?
It uses eight agent sessions: six implementers and two reviewers. The remaining two cards are a test shell and a scratch shell.
Will a belt wait until the test shell is free?
No. Keep the target running and ready at a prompt. Delivery is dropped when the target is stopped, and a busy target is not queued.