LockRe

An open-source MCP server (MIT). Drop it into any MCP client (Claude Code, etc.) — no account, no service to sign up for, no telemetry. Clone it, point your client at it, done.

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) with an optional HTTP API. Pun intended: Lock + Revert (≈ Rock Lee 🥋).

v0.2 is daemon-less by default — the MCP bridge talks to a shared SQLite directly (cross-process-safe via WAL + atomic transactions), so there's no server to keep running.

zero dependencies · daemon-less · multi-process safe · ~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.

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.
• Daemon-less by default — the MCP bridge opens the shared SQLite directly; multiple bridge processes stay correct via WAL + BEGIN IMMEDIATE atomic transactions. An optional HTTP daemon mode remains for shared/cross-machine setups.
• Zero dependencies — pure Node built-ins (node:sqlite, node:crypto; node:http only for the optional daemon).

---

Install & run

Requires Node ≥ 22 (uses the built-in node:sqlite). Since v0.2 there is no daemon to run — the MCP bridge opens a shared SQLite database directly, so every agent just spawns the bridge on demand.

git clone https://github.com/crsxmd/LockRe-mcp.git

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

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

That's the whole setup — no port, no background process. All bridges share one lockre.db (auto-created on first use; CREATE TABLE IF NOT EXISTS + migrations run every start, so it's safe to delete and recreate). Cross-process correctness comes from SQLite WAL + BEGIN IMMEDIATE atomic transactions. Waiting on a held lock is bridge-internal polling — the model sees a single tool call, so it costs no extra tokens while waiting.

Optional: HTTP daemon mode

For a shared or cross-machine setup (e.g. a dashboard), run the HTTP server and point bridges at it instead:

node server.js     # HTTP service on 127.0.0.1:8766 (also auto-creates lockre.db)

then add "env": { "LOCKRE_URL": "http://127.0.0.1:8766" } to the MCP config. The bridge will use the daemon rather than opening the DB directly.

v0.1 (HTTP-daemon-first) is preserved at the git tag v0.1.0 — git checkout v0.1.0.

---

MCP tools (7)

tool	purpose
lock	Reserve a file before editing (acquire / queue / wait).
unlock	Release a file (records the contribution diff).
revert_agent	Remove one agent's added lines; returns a conflict report + modes when needed.
restore_revert	Undo a revert by revert_uid.
get_contributions	See, in time order, what each agent changed in a file.
list_agents	List agents that edited, most-recent first.
agent_journey	One agent's full edit journey (every file, + / − per edit).

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)

All configuration is via LOCKRE_* environment variables (all optional).

var	default	meaning
LOCKRE_PORT	8766	HTTP port (binds 127.0.0.1).
LOCKRE_DB	lockre.db	SQLite file (auto-created on first use).
LOCKRE_BLOCKING	off	Hold /lock open until granted (chunked); recommended for agents.
LOCKRE_WAIT_CHUNK_MS	50000	Per-chunk wait before returning a waiting reply.
LOCKRE_MAX_HOLD_MS	1800000	Absolute cap on any lock (leaked-lock backstop).
LOCKRE_FILE_MTIME_MS	300000	Auto-release a file lock unmodified this long.
LOCKRE_GRACE_MS	120000	Idle-holder grace.
LOCKRE_MAX_CONTRIBUTIONS	0 (off)	FIFO retention cap on stored contributions.
LOCKRE_EVICT_BATCH	cap/5	Rows evicted (oldest first) when over the cap.

---

Security

For local, single-machine multi-agent use. The daemon-less default uses local files only (no network). The optional HTTP daemon binds to 127.0.0.1 with no authentication — do not expose that port to a public network.

---

Quality & testing

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

• Deterministic suite — 117 checks, all green: lock-engine units, revert-mode classification, runtime revert (files actually re-run with node), the MCP bridge (HTTP + embedded), a concurrency/stress harness (no-lost-update under 50+ concurrent ops, queue fairness, disconnect chaos, revert-respects-lock), DB retention, and the embedded reschedule flow.
• Cross-process atomicity (daemon-less) — 600/600: 20 separate OS processes share one SQLite DB and hammer the same lock through a read-increment-write critical section → zero lost updates, no leaked locks (proves WAL + BEGIN IMMEDIATE mutual exclusion across processes).
• Genuine multi-agent — 17 scenarios (+ a v0.2 re-run), all passing: each conflict is created by 2–5 separate real agents (each with its own server-minted id), then reverted by another agent that inspects and decides. Coverage includes 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.

---

<a name="thai"></a>

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

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 เงียบ

daemon-less (v0.2): ไม่ต้องรัน server — bridge เปิด SQLite ที่แชร์กันตรงๆ (atomic ข้าม process ด้วย WAL + BEGIN IMMEDIATE), ตั้ง MCP config แค่ node mcp-stdio.js พอ. HTTP daemon เป็น optional (ตั้ง LOCKRE_URL). v0.1 เก็บไว้ที่ tag v0.1.0

เบา: zero dependency, daemon-less, multi-process safe, MCP footprint ~997 tokens, Node ≥ 22 · open-source MIT

ความปลอดภัย: 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