Scoped
File Locks for Concurrent Claude Code Sessions · AI Infrastructure
An MCP server plus a PreToolUse hook that stops two Claude Code sessions from editing the same file at once. The hook blocks the edit itself, so it works even when the model never calls the tools.
View source on GitHubHow it was built
Problem
Running a Claude Code session per issue or per worktree is normal now, and nothing stops two of them from editing the same file. An advisory lock API only helps if the model remembers to call it.
Decisions
- Enforced in a PreToolUse hook rather than relying on tool calls, and made the hook fail open so a bug in the coordinator never blocks real work.
- Kept the lock in local SQLite and posted Linear comments only for visibility, since a network call with no compare-and-swap is the wrong place for the atomic part.
- Tested the race with real OS processes sharing one database. Claims made one after another on a single connection passed; the multi-process tests exposed a check-then-insert race and a hook that ignored the insert result.
Outcome
In the process race tests, every round has exactly one winner and no errors. It has not been measured on a real multi-session fleet yet, and the README says so.
Key features
- A PreToolUse hook denies an Edit or Write on a file another session has claimed, and auto-claims unclaimed files
- A claim tool reserves files before a multi-file change; release, check and status free them early and show who holds what
- Claims live in local SQLite; a unique index on the file path gives each race exactly one winner
Impact
Several agent sessions can work in one repo without one overwriting a file another has claimed through Claude Code's edit tools.
Tech stack
Node.js, SQLite, MCP