Claude Code Parallel Sessions: Task Isolation and Handoffs
Suppose one repository has two jobs waiting: fix a CSV import crash when amount is empty, and add a --dry-run flag to the CLI. The first job touches parser/ and import tests. The second touches cmd/ and CLI tests. They are reasonable candidates for two parallel Claude Code sessions.
If both jobs need to change parser/schema.ts, do not start them in parallel. Give that shared file one owner, finish the first change, and hand the result to the second task. Separate chats do not prevent conflicting edits.
1. Map each task to files and a result
Write one row for each task before opening Claude Code:
| Task | Allowed files | Done when |
|---|---|---|
Empty amount
|
parser/, tests/import/
|
the focused test returns a validation error instead of crashing |
--dry-run flag |
cmd/, tests/cli/
|
the command prints the import plan and writes no data |
An overlapping file means the tasks need sequencing or a clearly assigned owner. If the rows stay separate, create a worktree for each edit.
2. Create isolated worktrees and launch sessions
Inspect the current checkout first:
git status --short
Do not hide or discard changes you do not recognize. Confirm who owns them before branching from this state.
Create two isolated working directories and branches:
git worktree add ../project-fix-empty-amount -b fix/empty-amount
git worktree add ../project-cli-dry-run -b feat/cli-dry-run
Open two separate terminal windows or tabs and launch Claude Code in each directory:
Terminal 1 (parser fix):
cd ../project-fix-empty-amount
claude
Terminal 2 (dry-run CLI):
cd ../project-cli-dry-run
claude
The worktree isolates files and branches on disk; the Claude Code session isolates conversation history and context; a background test process only isolates execution time. Effective parallel work requires keeping all three boundaries intact.
3. Give each session a task-sized prompt
In the first terminal, provide a focused prompt:
Fix the CSV import crash when amount is empty.
Work only in parser/ and tests/import/.
Do not change the public CSV format.
Reproduce the failure with a focused test, make the smallest fix,
then rerun that test. Report changed files and the exact command.
In the second terminal, provide the boundary for the second task:
Add --dry-run to the import CLI.
Work only in cmd/ and tests/cli/; do not edit parser/.
Dry-run mode must not write data.
Add a focused test and report the command used to verify it.
If the second session discovers that it must modify parser/schema.ts, it should stop and record that blocker instead of silently expanding its scope.
4. Hand off reproducible state
Before handing off the parser change, verify the state in its worktree:
git status --short
git diff --check
npm test -- tests/import/empty-amount.test.ts
Then record the state of the work, not the chat transcript:
Task: empty amount returns a validation error without writing data
Worktree / branch: ../project-fix-empty-amount / fix/empty-amount
Changed: parser/amount.ts, tests/import/empty-amount.test.ts
Verified: npm test -- tests/import/empty-amount.test.ts -> passed
Not verified: full integration test suite
Blocker: none
Next step: review the diff and run the parser test group before merge
5. How the next session resumes from the handoff
The receiving session or reviewing engineer does not read the full conversation log. Recovery happens through concrete action:
- Switch to the target directory:
cd ../project-fix-empty-amount. - Inspect changed files:
git status --short. - Rerun the recorded verification command:
npm test -- tests/import/empty-amount.test.ts. - If the test passes and file boundaries match, proceed to the action in "Next step".
Without a reproducible verification command, the change remains unverified even if the diff looks plausible.
6. Resolve overlap under one owner
If both branches changed parser/schema.ts, choose one owner for the final schema. That person reads both diffs, carries the second behavior into one branch, resolves the conflict against expected behavior, and runs both the empty-amount and dry-run tests before merge.
Parallel sessions are useful because they allow independent progress while another branch waits for lengthy tests or reviews. They do not speed up code design itself, nor do they eliminate the need for manual conflict resolution when files overlap.
7. Keep secrets out of the handoff
Do not place API keys, cookies, .env contents, personal data, or complete sensitive logs in a handoff. A timestamp, status code, safe request ID, variable name without its value, and a short symptom are usually enough for diagnostics.
For a separate Claude Code API workflow, the next session should receive credentials through the normal secret mechanism. BetterToken provides Anthropic-compatible API access with the user own account and API key; it is not a Claude subscription or a shared account. Check the current Claude Code setup in BetterToken Docs, create a key in your account, and keep its value out of the handoff.
Checklist before merge
- [ ] Changed files are listed and diff is reviewed.
- [ ] Narrow target test is executed and documented.
- [ ] Unverified areas and risks are explicitly noted.
- [ ] No API keys or secrets exist in the handoff card or commits.
The split worked when another session can reproduce the recorded check without reading the old conversation. If it needs the entire transcript, the task boundary was too broad.
Sources
Originally published on the BetterToken blog.
BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.
Top comments (0)