PlanLock

A convention for coordinating multiple AI agents working on the same repository.

When multiple agents work on one repo simultaneously — whether it's a team using AI assistants or one person running several agents in parallel — they inevitably collide. Same files edited, merge conflicts everywhere, broken assumptions.

PlanLock solves this with a simple convention: declare what you'll touch before you touch it.

No services to run. No tools to install. Just a folder, a markdown file, and a git hook.

How It Works

1. Agent pulls main, reads .plans/active/ to see what's claimed
2. Agent creates a plan file declaring which files it will touch
3. Agent pushes the plan to main — a pre-push hook warns on overlap
4. Agent branches and works freely — no further checks
5. Agent's final commit moves the plan from active/ to done/
6. PR merges, lock is released

The plan file on main acts as an optimistic lock. Other agents see it when they pull. Files stay claimed until the code actually lands.

Setup

1. Add PlanLock to your repo

# Create the plans directories
mkdir -p .plans/active .plans/done

# Add .gitkeep files so git tracks empty directories
touch .plans/active/.gitkeep .plans/done/.gitkeep

# Copy AGENTS.md to your repo root
cp AGENTS.md /path/to/your/repo/AGENTS.md

# Install the pre-push hook
cp hooks/pre-push /path/to/your/repo/.githooks/pre-push
chmod +x /path/to/your/repo/.githooks/pre-push
git config core.hooksPath .githooks

2. Point your agents at AGENTS.md

Add AGENTS.md to whatever context your agent platform reads — Claude Code's CLAUDE.md, Cursor's rules, Copilot's instructions, etc. The content is platform-agnostic.

3. Start working

Run multiple agents. Each one follows the protocol. Conflicts drop dramatically.

Plan File Format

Plans live in .plans/active/ as YAML files named after the branch:

branch: fix/token-refresh
description: Fix token refresh logic for expired sessions
files:
  - src/auth/token.ts
  - src/auth/refresh.ts
  - tests/auth/token.test.ts
started: "2026-02-23T10:00:00Z"

That's the entire schema. Keep it simple.

When Overlap Is Detected

The pre-push hook warns but does not block. You might know the overlap is fine — maybe two agents are editing different functions in the same file, or one is almost done.

The convention is: if the hook warns, the agent should stop and tell the user rather than silently proceeding. The user decides.

FAQ

Does this prevent all merge conflicts? No. It prevents the most common ones — two agents editing the same files. It can't prevent semantic conflicts (Agent A changes a return type, Agent B relies on the old type). That's what CI is for.

What if a plan gets stale? Delete it from .plans/active/ manually. Since there's no automated TTL, a human cleans up abandoned plans. For a single user running multiple agents, this is a 5-second task.

Does this work with a team? Yes. The convention works the same whether it's one person with five agents or five people each running one.

What agent platforms does this work with? Any platform that can read markdown instructions and run git commands. Claude Code, Cursor, Windsurf, Copilot, Aider, etc.

License

MIT License — see LICENSE.