Stop AI agents from destroying each other's work.
Quick Start · How It Works · MCP Config · CLI Usage · Contributing
You're running multiple AI agents on the same codebase. Maybe Claude Code is refactoring your auth module while Aider is updating your API routes. Everything seems fine until:
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 🤖 Agent A (Claude Code) 🤖 Agent B (Aider) │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Reading auth.ts... │ │ Reading auth.ts... │ │
│ │ Planning refactor │ │ Planning new routes │ │
│ └────────┬────────────┘ └────────┬────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Writing auth.ts... │ │ Writing auth.ts... │ │
│ │ ✅ Refactor done! │ │ ✅ Routes added! │ │
│ └────────┬────────────┘ └────────┬────────────┘ │
│ │ │ │
│ └───────────┐ ┌─────────────────┘ │
│ ▼ ▼ │
│ ┌──────────────┐ │
│ │ 💀 auth.ts │ │
│ │ CORRUPTED │ │
│ │ Build: FAIL │ │
│ └──────────────┘ │
│ │
│ Agent A's refactor is GONE. Agent B overwrote it. │
│ Neither agent knows the other existed. │
│ │
└─────────────────────────────────────────────────────────────────┘
This is "Agentic Collision" — and it's the #1 reason multi-agent workflows fail silently.
- 🔄 Silent overwrites — Agent B nukes Agent A's changes with zero warning
- 🧠 Context loss — Each agent hallucinates that it's the only one working
- 🔁 Infinite loops — Agents "fix" each other's changes back and forth forever
- 💀 Broken builds — The repo ends up in a state no single agent intended
AGNT-LOCK is a lightweight coordination layer that sits between your AI agents and your repository. It uses the Model Context Protocol (MCP) to give every agent awareness of what other agents are doing.
graph TB
subgraph Agents
A[🤖 Claude Code]
B[🤖 Roo Code]
C[🤖 Aider]
D[🤖 Cursor]
end
subgraph AGNT-LOCK
MCP[🔐 MCP Server]
SM[📋 State Manager]
IL[📝 Intent Log]
end
subgraph Repository
F1[📄 auth.ts]
F2[📄 routes.ts]
F3[📄 config.ts]
end
A -->|acquire_lock| MCP
B -->|acquire_lock| MCP
C -->|get_repo_state| MCP
D -->|release_lock| MCP
MCP --> SM
SM --> IL
SM -->|✅ Grant / 🔒 Block| Agents
SM -.->|tracks| Repository
- Before editing, an agent calls
acquire_lock(filepath, agent_name, intent) - If the file is free → lock is granted, intent is logged
- If the file is locked by another agent → request is blocked with details about who holds it and why
- After editing, the agent calls
release_lock(filepath)to free the file - Any agent can call
get_repo_state()to see the full coordination map
# Clone the repository
git clone https://github.com/codewithriza/AGNT-LOCK.git
cd AGNT-LOCK
# Install dependencies
npm install
# Build
npm run build# Start the MCP server (stdio transport)
node dist/index.jsnpm install -g .
agnt-lock statusAdd to your claude_desktop_config.json:
{
"mcpServers": {
"agnt-lock": {
"command": "node",
"args": ["/absolute/path/to/AGNT-LOCK/dist/index.js"],
"env": {}
}
}
}Add to your .cursor/mcp.json:
{
"mcpServers": {
"agnt-lock": {
"command": "node",
"args": ["/absolute/path/to/AGNT-LOCK/dist/index.js"]
}
}
}Add to your MCP settings in Roo Code:
{
"mcpServers": {
"agnt-lock": {
"command": "node",
"args": ["/absolute/path/to/AGNT-LOCK/dist/index.js"],
"disabled": false,
"alwaysAllow": ["acquire_lock", "release_lock", "get_repo_state"]
}
}
}💡 Tip: Replace
/absolute/path/to/AGNT-LOCKwith the actual path where you cloned the repo.
AGNT-LOCK exposes 4 tools via the Model Context Protocol:
| Tool | Description |
|---|---|
acquire_lock |
Lock a file before editing. Blocks if already locked by another agent. |
release_lock |
Release a file lock after editing. Commits intent to session history. |
get_repo_state |
Get the full coordination map: active locks, agents, recent activity. |
force_release_all |
Emergency reset: force-release all locks in the repository. |
// Parameters
{
filepath: "src/auth.ts", // File to lock
agent_name: "claude-code", // Who's locking it
intent: "Refactoring auth middleware to use JWT" // Why
}
// Response (success)
{
"success": true,
"message": "✅ Lock acquired on \"src/auth.ts\" by \"claude-code\".",
"lock": {
"filepath": "src/auth.ts",
"agent_name": "claude-code",
"intent": "Refactoring auth middleware to use JWT",
"acquired_at": "2026-03-15T10:30:00.000Z",
"expires_at": "2026-03-15T10:45:00.000Z"
}
}
// Response (blocked)
{
"success": false,
"message": "🔒 BLOCKED: File \"src/auth.ts\" is locked by agent \"aider\"...",
"blocked_by": { ... }
}📊 AGNT-LOCK Repository State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: session_20260315_a3f8k2
Active Locks: 2
Active Agents: claude-code, aider
🔒 Locked Files:
• src/auth.ts → claude-code (intent: "Refactoring auth middleware")
• src/routes.ts → aider (intent: "Adding new API endpoints")
📝 Recent Activity:
🔐 claude-code → acquire "src/auth.ts"
🔐 aider → acquire "src/routes.ts"
🔓 roo-code → release "src/config.ts"
AGNT-LOCK also includes a CLI for manual coordination and debugging:
# Check repository coordination state
agnt-lock status
# Manually lock a file
agnt-lock lock src/index.ts my-agent "Updating the main entry point"
# Release a lock
agnt-lock unlock src/index.ts my-agent
# Emergency: release all locks
agnt-lock reset
# Start MCP server from CLI
agnt-lock serveAGNT-LOCK/
├── src/
│ ├── index.ts # MCP server entry point (stdio transport)
│ ├── server.ts # MCP tool definitions (acquire, release, state)
│ ├── state-manager.ts # Core .agentlock state engine
│ └── cli.ts # Color-coded CLI dashboard
├── tests/
│ └── state-manager.test.ts # Vitest unit tests (9 tests)
├── website/ # Next.js + Tailwind landing page
│ ├── app/
│ │ ├── page.tsx # Dark-mode landing page
│ │ ├── layout.tsx # Root layout with metadata
│ │ └── globals.css # Tailwind + custom styles
│ └── package.json
├── dist/ # Compiled JavaScript (after build)
├── .agentlock/ # Runtime state directory (auto-created, gitignored)
│ └── state.json # Current locks & intent log
├── vitest.config.ts # Test configuration
├── package.json
├── tsconfig.json
├── LICENSE # MIT
└── README.md
┌──────────────────────────────────────────────────────────────┐
│ .agentlock/state.json │
├──────────────────────────────────────────────────────────────┤
│ │
│ active_locks: { │
│ "src/auth.ts": { │
│ agent_name: "claude-code", │
│ intent: "Refactoring auth middleware", │
│ acquired_at: "2026-03-15T10:30:00Z", │
│ expires_at: "2026-03-15T10:45:00Z" ← Auto-expiry │
│ } │
│ } │
│ │
│ intent_log: [ │
│ { agent: "roo-code", action: "acquire", file: "..." }, │
│ { agent: "roo-code", action: "release", file: "..." }, │
│ { agent: "claude-code", action: "acquire", file: "..." } │
│ ] ↑ Rolling log (max 500 entries) │
│ │
└──────────────────────────────────────────────────────────────┘
- File-level locking — Granular enough to allow parallel work, broad enough to prevent conflicts
- 15-minute TTL — Locks auto-expire to prevent deadlocks from crashed agents
- Intent logging — Every lock/unlock is logged with why the agent needed the file
- Zero external dependencies — State is a single JSON file, no database required
- Ownership verification — Only the locking agent (or force-release) can unlock a file
Contributions are welcome! Here's how to get started:
# Fork and clone
git clone https://github.com/YOUR_USERNAME/AGNT-LOCK.git
cd AGNT-LOCK
# Install dependencies
npm install
# Build
npm run build
# Test the CLI
node dist/cli.js status- 🌐 HTTP/SSE transport (for remote agent coordination)
- 📊 Web dashboard for visualizing lock state
- 🔔 Webhook notifications when locks are contested
- 🧪 Test suite
- 📦 npm package publishing
- 🐳 Docker container