Blog

April 9, 2026 | 6 minute read

Running Multiple Claude Code Sessions Without Conflicts: A Practical Deconfliction Guide

Claude Code is powerful enough on its own. Running three sessions in parallel across different parts of a codebase turns a single engineer into a small team. But without coordination, parallel sessions will stomp on each other's work—two agents editing the same file simultaneously means lost changes and broken commits. This guide presents a lightweight, file-based deconfliction system that enforces safe multi-session workflows with zero overhead.

The Problem: Concurrent Writes

Each Claude Code session operates independently. It has no awareness of other sessions running in adjacent terminal windows. When two sessions modify the same file, the last write wins—silently overwriting the other session's changes. Similarly, concurrent git operations in the same repository (simultaneous commits, rebases, or branch switches) can corrupt state. Read operations are safe; only writes cause conflicts.

The solution is straightforward: establish exclusive write access per directory, enforce it with tooling, and teach every session to check before editing.

Architecture: Three Layers of Protection

The deconfliction system has three components that work together:

1. Lock Manager (claude-lock) — A shell script that manages PID-based lock files. Sessions claim directories before editing and release them on exit. Stale locks from crashed sessions are automatically detected via PID liveness checks.
2. Session Launcher (claude-session) — A wrapper script that claims the lock before launching Claude Code and releases it on exit using a shell trap. This makes locking automatic—the engineer doesn't need to remember manual lock/unlock steps.
3. Global Rules (CLAUDE.md) — A configuration file that every Claude Code session reads on startup. It instructs the AI to check lock status before writing to any directory and refuse edits to locked paths.

How the Lock Manager Works

Lock files live in a dedicated directory (~/.claude/locks/). Each lock file stores five fields: the owning process ID, a human-readable label, the terminal (TTY), the claim timestamp, and the absolute path of the locked directory.

The key operations:

• claude-lock claim <dir> <label> — Creates a lock file for the directory. If a lock already exists, it checks whether the owning PID is still alive. Live PID means the lock is valid and the claim is rejected. Dead PID means the lock is stale and gets replaced.
• claude-lock check <dir> — Returns whether a directory is free, locked (with owner details), or stale. This is what sessions call before editing.
• claude-lock status — Lists all active locks with their owners, terminals, and timestamps. Useful for the engineer to see which sessions are running where.
• claude-lock release <dir> — Removes the lock file. Called automatically by the session launcher's exit trap.
• claude-lock clean — Scans all locks and removes any whose owning PID no longer exists. Handles the case where a terminal was killed without a clean exit.

Three-Session Workflow

The recommended setup uses three terminal sessions, each dedicated to a different project or domain directory. Here is a concrete example:

# Terminal 1 — Project A
cd ~/project-alpha && claude-session alpha

# Terminal 2 — Project B
cd ~/project-beta && claude-session beta

# Terminal 3 — Project C
cd ~/project-gamma && claude-session gamma

Each session owns its directory exclusively. If the engineer asks the session in Terminal 1 to modify a file under ~/project-beta/, the session will check the lock, find it owned by Terminal 2, and refuse—directing the engineer to use the correct terminal instead.

The Rules Every Session Follows

The CLAUDE.md global configuration establishes five rules that every session enforces:

1. Check before writing. Before editing any file, run claude-lock check on the target directory. If locked by another session, stop and inform the user.
2. Claim before proceeding. If the directory is free and the session needs to edit there, claim it first.
3. Scope is recursive. A lock on a directory covers all subdirectories. Locking ~/project-alpha protects ~/project-alpha/src/utils/helper.ts.
4. Reads are always safe. Any session can read files in any directory regardless of locks. Only writes are gated.
5. Shared files need coordination. Certain files (ecosystem configuration, shared memory indexes) may be referenced by multiple sessions. These require explicit user coordination.

Handling Edge Cases

Session crash or forced kill: The exit trap in claude-session handles normal exits and SIGINT/SIGTERM. If the terminal process is killed with SIGKILL (kill -9), the trap doesn't fire and the lock persists. Running claude-lock clean from any terminal detects the dead PID and removes the stale lock.

Cross-directory tasks: Sometimes a task genuinely requires editing files across two locked directories. The correct approach is to finish and release one session, then expand the other's scope—or have the engineer coordinate by pausing one session while the other makes the cross-cutting change.

Same-session re-entry: If a session tries to claim a directory it already owns (same PID), the lock manager recognizes this and succeeds without error. This prevents false rejections when the session launcher is restarted within the same shell.

Verification

A quick smoke test confirms the system works:

# Check nothing is locked
claude-lock status
# → No active locks.

# Claim a directory
claude-lock claim ~/project-alpha alpha
# → Claimed: /home/user/project-alpha (alpha)

# Try to claim from a different process
claude-lock check ~/project-alpha
# → LOCKED by PID 12345 (alpha) since 2026-04-09 14:30:00

# Release and verify
claude-lock release ~/project-alpha
claude-lock status
# → No active locks.

Key Takeaway

Running multiple Claude Code sessions in parallel is a force multiplier, but only when each session has clear, enforced boundaries. The deconfliction system described here—PID-based file locks, automatic claim/release lifecycle, and global session rules—adds negligible overhead while eliminating the class of bugs caused by concurrent writes. The principle is borrowed directly from distributed systems: coordinate access to shared resources, or accept data corruption as a consequence. For AI-assisted development at scale, this is table stakes.