Multi-CLI Parallelism & Conflict Prevention

Pillar: multi-cli-coordination | Date: April 2026
Scope: Worktree-per-CLI vs branch-per-issue vs shared-main + locks: what real teams have settled on with evidence. Concurrent in-flight edit detection across agents beyond git merge conflicts. Issue tracker patterns: SQLite local vs GitHub Issues vs hybrid, with production evidence. Lock-free coordination patterns from real multi-agent systems. Pre-push hooks and merge-gate patterns that have shipped successfully. Evidence from teams running 4+ parallel CLI agents simultaneously.
Sources: 15 gathered, consolidated, synthesized.

Table of Contents

1. Isolation Architecture: The Worktree-Per-CLI Consensus
2. Technical Foundations of Git Worktree Isolation
3. Shared Resources Not Isolated by Worktrees
4. Concurrent Edit Conflicts: Scale and Measurement
5. Semantic Intent Divergence: Beyond Textual Conflicts
6. Issue Tracker Architecture: SQLite vs GitHub Issues vs Hybrid
7. Atomic Claim Patterns and Race Condition Prevention
8. Lock-Free Coordination from Real Multi-Agent Systems
9. Pre-Push and Merge Gate Architecture
10. Production Concurrency Limits and Evidence
11. Agent Coordination Models and Orchestration Patterns
12. AGENTS.md and CLAUDE.md as Coordination Contracts
13. Practitioner Tooling Survey

Section 1: Isolation Architecture — The Worktree-Per-CLI Consensus

The dominant pattern across practitioner sources and production deployments is unambiguous: one task = one branch = one worktree = one agent. Running multiple Claude Code sessions against the same working directory without filesystem isolation causes agents to overwrite each other's edits and corrupt each other's context — described by one practitioner as "all hell breaks loose."^[14][11] No surveyed source advocates shared-main with file locks as a preferred approach.

Key finding: The second write wins in any shared-main scenario — both agents read identical file state, make independent decisions, and write back to the same paths, producing undetected data loss with no merge conflict raised.^[2]

Isolation Strategy Comparison

The branch-per-issue, shared checkout approach fails because all agents share the same working directory: a checkout by one agent changes what all other agents are reading and writing, causing silent context corruption regardless of branch-level isolation.^[2][14]

Section 2: Technical Foundations of Git Worktree Isolation

Git worktrees create separate checked-out copies that share a single .git object store. Each agent has an independent working directory, index, and branch reference, while disk usage remains lower than full clones because objects are shared.^[1][2]

Native Claude Code Support (v2.1.50+)

Claude Code added native worktree support in v2.1.50 via the --worktree flag. The flag auto-creates named worktrees at .claude/worktrees/<name>/, branching from the default remote as worktree-<name>.^[1][15][3]

Worktree Lifecycle Commands

Cleanup Behavior

Worktrees with no changes are automatically deleted upon session completion. Modified worktrees persist for human review. Teams add .claude/worktrees/ to .gitignore to prevent version control pollution.^[1][15] See Section 8 for heartbeat-based stale detection and automatic work reclamation patterns.

Section 3: Shared Resources Not Isolated by Worktrees

Worktrees isolate the filesystem only. Teams running 4+ parallel agents frequently collide on other shared resources. mindstudio.ai documents five resource categories requiring explicit per-agent isolation beyond worktrees.^[12]

Key finding: Filesystem isolation via worktrees is necessary but not sufficient — agents colliding on ports, databases, or Redis namespaces produce failures indistinguishable from code bugs.^[12]

Resource Isolation Requirements per Agent

Section 4: Concurrent Edit Conflicts — Scale and Measurement

The AgenticFlict dataset provides the most rigorous production measurement of AI-generated merge conflicts to date: 107,026 simulated AI-generated pull requests across 59,000+ repositories, revealing a 27.67% overall conflict rate.^[4]

AgenticFlict Dataset: Key Statistics

The ~2× variance in conflict rates between AI systems (Copilot 15.24% vs. Codex 31.85%) indicates that the choice of coding agent substantially affects coordination overhead — not just code quality.^[4] The near-linear relationship between PR size and conflict rate provides a strong empirical argument for small, scoped tasks.

Key finding: Standard git merge conflict detection is necessary but not sufficient — roughly 1 in 4 AI-generated PRs on the same codebase will produce a textual conflict, and textual conflicts represent only the detectable subset of coordination failures.^[4]

File Claim Coordination: Pre-Write vs Post-Write Detection

The parallel-cc project implements file claim coordination as a pre-write registry — agents declare file ownership before writing, preventing concurrent writes from being attempted at all.^[11] This operates upstream of git's post-write conflict detection. Additionally, parallel-cc uses AST analysis — not just line-level diffs — for merge conflict detection, understanding code structure rather than text changes.^[11]

Section 5: Semantic Intent Divergence — Beyond Textual Conflicts

The Semantic Consensus paper identifies a failure mode orthogonal to git merge conflicts: Semantic Intent Divergence (SID), where agents develop conflicting interpretations of shared objectives even when their file edits do not textually conflict.^[5] Across 600 experimental runs (controlled simulations on AutoGen, CrewAI, and LangGraph — academic research, not live production deployments), multi-agent workflows failed at rates ranging from 41% (best-performing framework) to 86.7% (worst-performing) across the three frameworks tested.^[5] No evidence of the Semantic Consensus Framework being deployed in production CLI-scale workflows appears in the research corpus.

Semantic Consensus Framework (SCF): Experimental Results

Source: Semantic Consensus paper, 600 controlled experimental runs. Per-framework baseline failure rates: AutoGen, CrewAI, and LangGraph showed 41–86.7% workflow failure rates (13–59% completion) without coordination, depending on framework — context that makes the SCF’s 100% completion result meaningful. (Academic research context; no production CLI-scale deployments confirmed.)^[5]

SCF Root Cause Attribution

Of all multi-agent failures analyzed, 79% stem from specification and coordination issues, not model capability limitations.^[5] The SCF conflict detection achieves 65.2% recall with 27.9% precision, deliberately biased toward conservative blocking to prevent downstream cascade failures.^[5]

SCF Architecture Components

Key finding: 79% of multi-agent failures originate from specification and coordination gaps, not model capability — meaning coordination infrastructure, not better models, is the primary lever for improving parallel agent reliability.^[5]

Section 6: Issue Tracker Architecture — SQLite vs GitHub Issues vs Hybrid

Multiple independent implementations have converged on the same conclusion: agent-native issue tracking belongs in local SQLite, not GitHub Issues. The argument is both structural (network latency, API rate limits) and behavioral (agents query work at high frequency; GitHub Issues is not optimized for programmatic access patterns).^[6][11]

Tracker Architecture Comparison

Beads Hybrid Architecture (SQLite + JSONL)

Beads implements a two-store architecture that separates performance from collaboration:^[6]

• SQLite (.beads/beads.db): Primary local database for fast agent queries, atomic claims, state transitions
• JSONL (.beads/issues.jsonl): Git-tracked for team collaboration and distributed consistency; enables offline-first workflow with periodic sync
• Two-way sync daemon: Keeps both stores consistent automatically

High-Concurrency: Dolt Server Mode

When multiple agents write concurrently (beyond standard WAL mode), Beads recommends Dolt server mode:^[7]

• bd dolt set mode server enables concurrent writes from multiple processes
• Cell-level merge resolves most conflicts automatically
• Hash-based IDs prevent collision when multiple branches create issues simultaneously^[7]
• Assignee filtering (bd ready --assignee agent-name) reduces coordination overhead by letting agents query only their own work^[7]

Key finding: Agent-native issue tracking should be local-first SQLite, not GitHub Issues — the rate limit and network latency constraints of GitHub's API make it unsuitable as the primary coordination store for high-frequency multi-agent workflows.^[6]

Section 7: Atomic Claim Patterns and Race Condition Prevention

Two independent implementations — Beads and parallel-cc — converged on the same minimal coordination primitive: the atomic claim. The pattern uses SQLite's UNIQUE constraint as the synchronization mechanism, providing TOCTOU-safe work assignment without polling or locking.^[7][11]

Atomic Claim Protocol

Two-Layer Claim Architecture

The production implementation uses a two-layer design separating atomicity from read performance:^[7]

• SQL layer: UNIQUE constraint provides atomic INSERT; prevents TOCTOU races at the database layer
• Lane JSON files: Fast local reads without touching the DB; updated after successful SQL claim

This design means agents reading their own state can use filesystem reads (fast), while coordination safety is enforced by the SQL layer (atomic).^[7]

Beads provides explicit API support for the full claim workflow:^[6][7]

• bd ready --json: Structured work discovery
• bd update <id> --claim --assignee agent-name: Atomic claiming
• bd ready --assignee agent-name: Filtered queue for claiming agent only

Section 8: Lock-Free Coordination from Real Multi-Agent Systems

The Kleisli.IO analysis frames the core insight: "Multi-session AI agent workflows are concurrent processes with private state, independent failure modes, and shared mutable resources."^[9] This reframe — treating multi-agent AI as a distributed systems problem — motivates lock-free approaches over pessimistic locking, which is inappropriate for agents that may crash, get rate-limited, or run for unpredictable durations.

Key finding: A dead agent holding a pessimistic lock blocks all work indefinitely. A dead agent in an event-sourced system simply stops producing events — its claimed work is reclaimed via heartbeat timeout without human intervention.^[9][11]

Lock-Free Coordination Mechanisms

Three Distributed Coordination Query Types

The Kleisli framework identifies three fundamental coordination query patterns that any multi-agent system must address:^[9]

1. Structural queries: Traversing task dependencies through typed edges
2. Temporal queries: Reconstructing causal ordering between sessions
3. Coordination queries: Detecting conflicts and managing concurrent writes

Cross-Session Knowledge Transfer via Stigmergy

The kli system validated stigmergic coordination in production: Session 1 discovered an "alist/plist mismatch that silently broke WebSocket communication." Subsequent sessions inherited the diagnostic reasoning, not just the fixed code. This demonstrates that lock-free systems can transfer analytical context across sessions without direct inter-session communication.^[9]

Section 9: Pre-Push and Merge Gate Architecture

The recce.hq 4-gate architecture documents a shipped configuration that increased weekly commits from 20–50 to 100–200+ while maintaining code quality standards.^[8] The architecture is additive — each gate layer handles a distinct class of failure.

4-Gate Architecture: Shipped Configuration

Key finding: "Hooks are binary — agents cannot rationalize exceptions." This is the core value proposition of pre-push hooks over instruction-file approaches alone. An AI agent can decide to ignore a CLAUDE.md rule; it cannot decide to make a failing test suite pass.^[8]

Generator-Verifier at the Merge Gate Level

The Anthropic coordination patterns document describes the Generator-Verifier pattern applied at the PR level: one agent produces output, another validates against explicit criteria.^[10] Applied to merge gates, this means a dedicated verification agent runs against every PR before merge is allowed. Weakness: vague verification criteria break the pattern — explicit, measurable criteria are required.^[10]

Measured Impact of Gate Architecture

Section 10: Production Concurrency Limits and Evidence

Three independent sources converge on a practical ceiling of 5–8 concurrent agents on the same codebase. The limiting factor is not compute, disk, or coordination overhead — it is human review capacity.^[2][3][12]

Concurrent Agent Ceiling: Multi-Source Summary

Production Case Studies

Note on the Cherny anomaly: Cherny's 10–15 simultaneous sessions appear to contradict the 5–8 ceiling. The resolution: Cherny's sessions include browser/mobile sessions on independent tasks, whereas the 5–8 ceiling refers specifically to simultaneous code-writing agents on the same codebase requiring human review and merge.^[3][13]

Resource Budget for Concurrent Worktrees

Each worktree consumes approximately 5 GB on a 2 GB codebase.^[2] Six concurrent agents require 30+ GB of disk. This is a non-trivial infrastructure constraint for on-device development.

Practitioner Skepticism: Real Costs

One practitioner (Dev.to) reports that parallel development "sucks up tokens" to the point of exceeding Claude Pro subscription limits.^[14] The same practitioner describes the human coordination overhead as "endlessly ping-ponging between rooms" and states that parallel development has not become their default workflow despite theoretical benefits.^[14]

Section 11: Agent Coordination Models and Orchestration Patterns

Anthropic documents five production multi-agent patterns with distinct coordination architectures.^[10] The Agent Teams pattern maps directly to multiple concurrent Claude Code CLIs on the same repository.

Anthropic's Five Production Coordination Patterns

Anthropic recommendation: Start with Orchestrator-Subagent — handles the widest range of tasks with minimal overhead. Evolve to other patterns as limitations emerge.^[10]

Three Practical Coordination Models (mindstudio.ai)

Task Decomposition as Conflict Prevention

appxlab.io documents a three-principle decomposition checklist that measurably reduces coordination conflicts:^[2]

1. File exclusivity: No overlapping writes across agents
2. Interface stability: No conflicting signature changes
3. Bounded scope: Clearly defined directory limits per agent

appxlab.io also reports that "incorporating architectural documentation into agent context produces measurable gains in functional correctness" — agents given explicit scope boundaries produce fewer coordination failures than agents given only task descriptions.^[2]

PR Merge Strategy for Parallel Branches

appxlab.io recommends: open draft PRs immediately to surface scope overlap early; merge in dependency order; use lead-agent orchestration for speed (requires clean decomposition) or human review gates for production safety.^[2]

Section 12: AGENTS.md and CLAUDE.md as Coordination Contracts

Four independent sources converge on instruction files as the first layer of coordination infrastructure — establishing explicit rules for file ownership, prohibited zones, build commands, and code conventions before code is written.^{[8][2][3][12]}

Three-Layer CLAUDE.md Architecture

A critical property: all worktrees share the auto-memory directory, enabling cross-session learning without explicit synchronization.^[3][13]

Coordination Contract Contents (AGENTS.md Pattern)

recce.hq documents the AGENTS.md coordination contract as Gate 1 in their shipped architecture, with content organized around explicit boundaries:^[8]

• File ownership rules: which agents own which directories
• Prohibited zones: directories no agent may touch without human review
• Build commands: canonical test/build invocations
• State file rules: "Do NOT commit state files"
• Cross-version rules: "Always test across versions"
• LLM-specific extensions in CLAUDE.md that extend AGENTS.md

Key finding: Instruction files are the lowest-cost coordination layer but also the weakest — agents can rationalize exceptions to text rules. They are necessary as human-readable documentation but must be backed by binary enforcement (pre-commit hooks, pre-push hooks) for reliability.^[8]

Section 13: Practitioner Tooling Survey

Three dedicated tooling systems address multi-CLI coordination with distinct architectural philosophies: parallel-cc (filesystem + SQLite), Beads (issue tracker + atomic claims), and kli (event sourcing + CRDTs).

Tool Comparison: Capability Matrix

parallel-cc: Shipped Feature Summary

Installation: ./scripts/install.sh --all, creates ~/.parallel-cc/ database directory. Requirements: Node.js 20+, gtr, jq, git.^[11] Key features beyond coordination:

• Configurable concurrency (v2.1+)
• E2B sandbox integration: isolated cloud VMs with 1-hour sessions, preventing local resource exhaustion
• Git Live mode: automatic PR creation on branch push
• AST-level conflict analysis (not just line diff)

Beads: Agent Context Window Management

Beads addresses a coordination problem not explicitly covered by worktree isolation: agent "dementia" — context window exhaustion causing agents to forget their task state every ~10 minutes.^[6] Fine-grained Beads issues keep agents early in their context windows, where decision quality is highest. This is a coordination problem because an agent that forgets its scope will re-explore and potentially overlap with other agents' work.^[6]

kli: No-Dependency Architecture

The kli system's defining characteristic is zero external dependencies — "plain files under version control."^[9] This makes it reproducible and auditable but limits query expressiveness compared to SQLite-backed systems. CRDTs ensure that any two sessions can merge their state without coordination, at the cost of additional per-operation overhead that becomes significant for solo developers.^[9]

Home