Seven People Editing One Repo Without Collisions: My Parallel Sessions Protocol

The problem: multiple AI sessions developing the same repo, how do they avoid stepping on each other?

I run multiple Claude Code / Codex sessions in parallel on the same git repo. At first I thought just use separate branches. Then one day: two tracks claimed the same decision number, four tracks editing shared ledger files caused merge conflicts, git add -A swept another track's four uncommitted files into my commit, and someone asked a question that had been resolved three hours ago — because they hadn't checked the latest state.

That day's tally: 7 simultaneous worktrees, 8 merged PRs, 6 collisions of different kinds.

parallel-sessions-protocol grew out of that incident report.

Mechanism 1: Register before you code (the board)

Before writing any code:

1. git fetch origin + gh pr list --state open — see the whole board first.
2. Branch from latest origin/main; take an exclusive working directory (the main checkout counts as one — at most one session may own it at a time).
3. Immediately open a draft PR with three fixed sections:

- Claimed scope — directories/files this track will touch - Claimed numbers — sequential resources taken; write none if none - Current status — one line, updated at milestones

4. When the track ends (merged or abandoned), the PR closes and the board self-cleans.

The board is gh pr list. Spawned/background sessions follow the same rule.

Mechanism 2: Claim before you use

Mechanism 3: Ledger writes only at merge time

Shared ledger docs are where parallel tracks collide by construction:

1. Never touch shared ledger files while the track is alive. Process notes go in the track's own files — zero conflict.
2. As the final step before merge: rebase onto latest main, then append your ledger entries, then request merge immediately.
3. Merges are serial, so ledger writes become serial too — conflicts go from guaranteed to rare.
4. If one still happens: the only correct resolution is keep both sides in full. Dropping either side erases another track's accounting.

Mechanism 4: Merge discipline

• Merges are serial. Who may merge what follows the project's own rules.
• Always preview locally before merging: git merge origin/main --no-commit --no-ff. GitHub's MERGEABLE flag lags behind latest main and has reported CLEAN on branches that actually conflict — verified in production.
• Never park a worktree on the main branch — it blocks every other session's operations that need to check out main.
• **Never git add -A** when tracks run in parallel; always add explicit paths. A blanket add sweeps other tracks' uncommitted files into your commit, and if their content happens to match main you won't even notice.
• After rebasing a pushed branch, push with --force-with-lease (plain push is rejected; plain --force can destroy a concurrent update).

Mechanism 5: Refresh at three checkpoints + CI glance

Run git fetch + gh pr list at: start of work, before asking the owner anything or reporting a major conclusion, and before merging.

At start of work, also glance at CI: gh run list --limit 5. If main is red, report it before starting anything new — a red cron once ran 45 consecutive failures over four days because every session assumed someone else was watching.

Mechanism 6: Register at end of work (teardown)

When the session stops — done for now, paused, or interrupted — while the track lives on:

1. Push or declare. Push unmerged work to the track's branch. If you cannot push, write a WIP declaration into the draft PR.
2. Worktree hygiene. Remove your worktree when done; if you must leave it, log why in the PR. Orphan worktrees accumulate silently.
3. Refresh the board. Update the draft PR's Current status line.
4. Write back triggered items. Any pending item whose trigger condition has already fired gets closed now, not later.

Real incidents vs the mechanisms that killed them

Install

bash git clone https://github.com/laojin1900/365Skill.git ./install.sh parallel-sessions-protocol

Repo: github.com/laojin1900/365Skill/tree/main/skills/parallel-sessions-protocol