Skip to main content
Glama
Sign In
agnt-lock

agnt-lock

by codewithriza
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

The Context Traffic Controller for Multi-Agent Repositories

Stop AI agents from destroying each other's work.

MIT License Build MCP Compatible Node.js TypeScript

Quick Start · How It Works · MCP Config · CLI Usage · Contributing

💥 The Problem: Agentic Collision

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.

What goes wrong:

  • 🔄 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

Related MCP server: asynkor

✅ The Solution: AGNT-LOCK

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

How it works:

  1. Before editing, an agent calls acquire_lock(filepath, agent_name, intent)

  2. If the file is free → lock is granted, intent is logged

  3. If the file is locked by another agent → request is blocked with details about who holds it and why

  4. After editing, the agent calls release_lock(filepath) to free the file

  5. Any agent can call get_repo_state() to see the full coordination map

🚀 Quick Start

Install

# Clone the repository
git clone https://github.com/codewithriza/AGNT-LOCK.git
cd AGNT-LOCK

# Install dependencies
npm install

# Build
npm run build

Run as MCP Server

# Start the MCP server (stdio transport)
node dist/index.js

Install globally (CLI)

npm install -g .
agnt-lock status

⚙️ MCP Configuration

For Claude Desktop / Claude Code

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "agnt-lock": {
      "command": "node",
      "args": ["/absolute/path/to/AGNT-LOCK/dist/index.js"],
      "env": {}
    }
  }
}

For Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "agnt-lock": {
      "command": "node",
      "args": ["/absolute/path/to/AGNT-LOCK/dist/index.js"]
    }
  }
}

For Roo Code (VS Code)

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-LOCK with the actual path where you cloned the repo.

🛠️ MCP Tools

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.

acquire_lock

// 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": { ... }
}

get_repo_state

📊 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"

💻 CLI Usage

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 serve

📁 Project Structure

AGNT-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

🔒 How the Lock System Works

┌──────────────────────────────────────────────────────────────┐
│                    .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)  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Key Design Decisions:

  • 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

🤝 Contributing

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

Ideas for contributions:

  • 🌐 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

Available Tools

4 tools
acquire_lockA

Acquire an exclusive lock on a file before editing. Prevents other AI agents from modifying the same file simultaneously. Returns lock status and blocker info if already locked.

Inputs: intent (required), filepath (required), agent_name (required).

force_release_allA

Emergency: Force-release ALL active locks. Use only when agents are stuck or locks are stale. This will free every locked file in the repository.

Inputs: no named parameters.

get_repo_stateA

Get the current coordination state of the repository. Shows all active locks, which agents are working, and recent intent history. Use this before starting work to understand what other agents are doing.

Inputs: no named parameters.

release_lockA

Release a previously acquired lock on a file. Call this after finishing edits to allow other agents to work on the file. The intent is committed to session history.

Inputs: filepath (required), agent_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: acquiring, releasing, viewing state, and emergency release. The only potential overlap is between release_lock and force_release_all, but their scopes (single vs. all) and contexts (normal vs. emergency) make them unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: acquire_lock, release_lock, get_repo_state, force_release_all. The verbs and nouns are descriptive and match their functionality, making the set predictable and coherent.

    Tool Count5/5

    With 4 tools, the server is well-scoped for a lock management purpose. Each tool covers a necessary operation without redundancy, and the count falls comfortably within the ideal 3-15 range.

    Completeness4/5

    The server covers the full lock lifecycle: acquire, release, query state, and emergency cleanup. The only minor gap is a lack of a per-file lock check endpoint, but get_repo_state provides sufficient visibility into lock status.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • asynkor

      asynkorofficial

      asynkor
      A
      license
      Not graded
      quality
      D
      maintenance
      Coordination layer for AI coding agents working on the same codebase. Adds file locks, shared project memory, and cross-machine file sync so Claude Code, Cursor, Windsurf, and other MCP agents stop overwriting each other.
      52
      Apache 2.0