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.
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.
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.
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.
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
The receiving session or reviewing engineer does not read the full conversation log. Recovery happens through concrete action:
cd ../project-fix-empty-amount
.git status --short
.npm test -- tests/import/empty-amount.test.ts
.Without a reproducible verification command, the change remains unverified even if the diff looks plausible.
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.
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.
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.
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.