LockRe

File lock + surgical revert for multi-agent collaboration. Stop AI agents from clobbering each other's edits, and undo any single agent's changes line-by-line without touching anyone else's work.

Exposed over MCP (for AI agents) and a plain HTTP API. Pun intended: Lock + Revert (≈ Rock Lee 🥋).

zero dependencies · ~1,280 lines · ~997-token MCP footprint · Node ≥ 22

Why

When several AI agents (or sub-agents) edit the same repository at once, two things go wrong:

1. Lost updates — two agents read, edit, and write the same file; one silently overwrites the other.

2. No clean undo — when one agent's contribution turns out wrong, you want to remove just its lines, not roll back everyone.

LockRe solves both with one tiny standalone service:

• Lock / unlock / queue — an agent reserves a file before editing. Others queue (FIFO) and are served in order.

• Contribution tracking + surgical revert — every edit is attributed by line. Reverting an agent removes only the lines it added, leaving other agents' work intact.

Related MCP server: Shift MCP Server

Design principle: the AI decides, LockRe never silently corrupts

When a revert hits a conflict (another agent built on top of the line you're removing), LockRe does not guess. It returns a structured report — who conflicts, where, and the resolution options — and lets the agent choose. If there's no conflict, the revert just proceeds.

Features

• Lock model — acquire / release / FIFO queue, per-lock token for safe unlock correlation.

• Blocking + poll — an agent can hold the request open until granted, or get a waiting reply (with queue position) and go do other work, then come back and re-check. No external notifier required.

• Surgical revert — remove one agent's added lines across one file or all its files in a single call.

• 4-mode conflict resolution — force / partial1 / partial2 / abort, chosen by the agent from the conflict report.

• Restore — undo a revert (guarded: refuses if the file changed since, or is locked).

• Safety nets — revert respects active locks (won't clobber an agent mid-edit); stale-lock sweep (max-hold + file-mtime); startup clears stale locks; optional FIFO retention to bound the DB.

• Heads-up — locking a recently-reverted file warns the next editor to review it.

• Zero dependencies — pure Node built-ins (node:http, node:sqlite, node:crypto).

Install & run

Requires Node ≥ 22 (uses the built-in node:sqlite).

git clone https://github.com/crsxmd/LockRe-mcp.git
cd LockRe-mcp
node server.js            # starts the HTTP service on 127.0.0.1:8766

Wire it into an MCP client (e.g. Claude Code)

{
  "mcpServers": {
    "lockre": {
      "command": "node",
      "args": ["/absolute/path/to/LockRe-mcp/mcp-stdio.js"],
      "env": { "AGENTLOCK_BLOCKING": "1" }
    }
  }
}

The MCP bridge talks to the same HTTP service, so run server.js once and point every agent's bridge at it.

MCP tools (7)

HTTP API

POST /lock · POST /unlock · POST /revert · POST /restore · GET /contributions · GET /agents · GET /status · GET /health

Conflict model

A conflict exists only when another agent's surviving line incorporates (embeds) a line you're reverting — e.g. you wrote return a, they changed it to return a + b. Pure additions and independent rewrites are not conflicts.

On conflict, revert_agent returns the report and four modes:

• force — remove all of the agent's lines, including the conflict zone (may corrupt; use when leftovers are safe to strip).

• partial1 — revert only the non-conflicted files; leave conflicted files for you to fix.

• partial2 — also revert conflict-free lines inside conflicted files, keeping the conflict-tied line.

• abort — change nothing.

Known limit (by design): detection is line-level, not semantic. A revert can be clean line-wise yet break at runtime if another agent's surviving code references a symbol the removed lines defined (e.g. a function/variable). LockRe surfaces a verify hint and a heads_up on the next lock so the agent checks — it does not run your code.

Configuration (env)

Env vars use the AGENTLOCK_ prefix (the project's original internal name).

Security

LockRe binds to 127.0.0.1 and has no authentication — it is designed for local, single-machine multi-agent use. Do not expose the port to a public network.

Quality & testing

LockRe is validated by two independent layers (test files are not shipped in this repo):

• Deterministic suite — 100 checks, all green: lock-engine units, revert-mode classification, runtime revert (files actually re-run with node), the MCP bridge, a concurrency/stress harness (no-lost-update under 50+ concurrent ops, queue fairness, disconnect chaos, revert-respects-lock), and DB retention.

• Genuine multi-agent re-run — 17 scenarios, all passing: each conflict is created by 2–5 separate real agents (each with its own server-minted id, locking/writing via the service), then reverted by another agent that inspects and decides. Coverage includes 4-agent concurrent no-lost-update, extend / upstream / replace / three-way / deep-chain / cross-agent-duplicate conflicts, all four revert modes, multi-file revert (whole + partial), revert→restore round-trips, the semantic-dependency limit, revert-respects-active-lock, and the post-revert heads-up. Every result cross-verified with curl / node.

License

MIT — free to use, modify, and distribute.

ภาษาไทย (สรุป)

LockRe = ระบบ ล็อกไฟล์ + ย้อน (revert) แบบ surgical สำหรับงานที่มี AI agent หลายตัวแก้โค้ดพร้อมกัน เปิดผ่าน MCP (สำหรับ agent) และ HTTP ชื่อพ้องเสียง Rock Lee (Lock + Revert)

แก้ 2 ปัญหา: (1) agent หลายตัวแก้ไฟล์เดียวกันแล้วเขียนทับกัน (lost update) (2) อยากย้อนงานของ agent ตัวเดียวโดยไม่กระทบคนอื่น

หลักการ: ตอน revert เจอ conflict ระบบ ไม่ตัดสินแทน — ส่ง report + ตัวเลือก (4 โหมด: force / partial1 / partial2 / abort) ให้ AI เลือกเอง ไม่เคย corrupt เงียบ

เบา: zero dependency, ~1,280 บรรทัด, MCP footprint ~997 tokens, Node ≥ 22

ความปลอดภัย: bind 127.0.0.1 ไม่มี auth — ใช้ภายในเครื่อง ห้าม expose ออกเน็ต

ทดสอบ: deterministic suite 100 เช็ค + genuine multi-agent 17 เคส (แต่ละเคสใช้ agent จริง 2–5 ตัวสร้าง conflict แล้ว revert) ผ่านหมด cross-verify ด้วย curl/node (ไฟล์เทสไม่ได้รวมใน repo นี้)

License: MIT