dibs
dibs is a coordination MCP server that lets parallel coding agents claim files, avoid collisions, hand off notes, and share lessons through a git repo — with no server or database.
Claim files or glob patterns (
dibs_claim) before editing, with a reason and TTL; returns GRANTED with an expiry or DENIED naming the holder, their reason, and when it expires. Re-claiming renews your lease.Check whether paths are free (
dibs_check) — FREE means safe to edit, HELD tells you who has them and until when.Release claims (
dibs_release) when done, either specific patterns or everything you hold, so others can proceed (leases also expire on their own).See the whole picture (
dibs_status) — active agents, every live claim with expiry, and your unread note count.Broadcast handoff notes (
dibs_note) to every agent on the repo for heads-ups that affect others.Read notes from other agents (
dibs_notes), which marks them read; check at session start and before new work.Save lessons (
dibs_lesson_add) as markdown under.dibs/lessons/, committed with the repo and shared via git — for gotchas, conventions, and hard-won fixes rather than routine work logs.Search lessons (
dibs_lesson_search) with ranked BM25 matches and snippets, to learn from previous agents before working in unfamiliar territory.
dibs
Call dibs on files. Run parallel coding agents without collisions.
dibs is a coordination layer for AI coding agents that share a repository: file claims with expiry, enforcement hooks, agent presence, handoff notes, and a git-native knowledge base. One static binary — no server, no database, no background processes.
Overview · Demo · How it works · Installation · Usage · Enforcement · Lessons · MCP server · Comparison · FAQ

Overview
Running several coding agents — Claude Code, Codex, Cline, Cursor — against one repository in parallel is now a common workflow, typically with one git worktree per agent. The sessions share no state: an agent cannot see what its peers are doing, and two agents that touch the same files produce silent overwrites and unmergeable diffs.
dibs provides the missing coordination primitives:
Problem | What dibs does |
Two agents edit the same file; last write wins. | Claims are checked before editing, and hooks can block colliding edits outright. |
No visibility into other sessions. |
|
A crashed agent leaves stale locks. | Claims are leases with a TTL. They expire on their own; there is nothing to clean up and no way to deadlock. |
Handoffs between agents are ad hoc. |
|
Knowledge is lost between sessions. | Lessons are markdown files under |
The design rationale is covered in more depth in the introduction post: Why Parallel Coding Agents Need a Coordination Layer.
Related MCP server: SameTree
Demo
Two agents, one repository:
$ dibs claim src/auth --reason "refactor auth" --agent alice
✓ claimed src/auth/** — lease 82fead6e as alice, expires in 29m
$ dibs claim src/auth/token.go --agent bob --reason "fix token bug"
✗ denied
src/auth/token.go held by alice (refactor auth), expires in 29m
wait, work elsewhere, or coordinate: dibs note "..."
$ echo $?
2
$ dibs claim src/api --agent bob --reason "new endpoints"
✓ claimed src/api/** — lease b7d31a5b as bob, expires in 29m
$ dibs status
agents
bob (you) active 0s ago on main — new endpoints
alice active 0s ago on main — refactor auth
claims
● src/auth/** alice (refactor auth) expires in 29m
● src/api/** bob (you) (new endpoints) expires in 29mWith the Claude Code hook installed, an edit that violates a claim is blocked before it happens, and the model is told why:
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"src/auth/token.go"}}' | dibs hook claude
dibs: src/auth/token.go is claimed by alice (refactor auth) — the claim expires in 29m.
Coordinate instead of colliding: wait for the lease, message them with `dibs note`,
or work on files outside their claim. Run `dibs status` to see all active claims.
$ echo $?
2How it works
dibs relies on a property of git worktrees: every worktree of a repository
shares a single common directory (git rev-parse --git-common-dir). State
written there is visible to all worktrees immediately, without commits, and
never appears in git status.
repo/.git/dibs/ coordination state — leases, presence, notes, journal
machine-local, shared by every worktree of the repo,
invisible to git
repo/.dibs/ knowledge — lessons/*.md
committed and reviewed like any other file, shared
with the team and CI through git itselfA claim is a JSON file containing an agent name, a set of patterns, a reason, and an expiry. Conflict checks run under an advisory lock; expiry is evaluated lazily at read time. No daemon is required.
Identity is resolved from
--agent, thenDIBS_AGENT, then a stable name derived from the worktree path — so each worktree has a consistent identity with zero configuration.Patterns are doublestar globs relative to the repository root (absolute paths are resolved into it). Claiming a directory claims its subtree, and a path that does not exist yet is treated the same way. Only existing regular files are claimed literally. Glob-to-glob conflict detection is conservative: two globs whose static prefixes are nested are treated as conflicting. Precise claims produce precise conflicts.
Every claim, denial, release, expiry, and note is appended to a JSONL journal (
dibs log).
Installation
go install github.com/polymatx/dibs/cmd/dibs@latestPrebuilt binaries for Linux, macOS, and Windows (amd64/arm64) are on the releases page. Building from source requires Go 1.26+; runtime requires git.
A multi-arch container image is published to GHCR — mount your repository
at /workspace:
docker run --rm -i -v "$PWD":/workspace ghcr.io/polymatx/dibs:latest mcpThe same image builds locally from the included Dockerfile (docker build -t dibs .).
Usage
cd your-repo
dibs init # create .dibs/, print next steps
dibs init --agents-md # append the coordination protocol to AGENTS.md
dibs hook install claude # enforce claims in Claude Code
dibs hook install pre-commit # enforce claims at commit time (any agent)Command | Description |
| Lease files or globs. Default TTL 30m, maximum 24h. |
| Release leases. Bare |
| Extend all of your leases. |
| Report whether paths are covered by another agent's lease. |
| Agents, claims, and unread note count. |
| Broadcast a note to all agents on the repository. |
| Read notes and mark them read. |
| Show recent journal events. |
| Manage the lessons knowledge base. |
| Run the MCP server on stdio. |
| Manage enforcement hooks. |
| Identity and build information. |
Exit codes: 0 ok/free · 1 error · 2 denied or held by another agent.
All state-reading commands accept --json for scripting.
Enforcement
Protocol adherence that depends on a model remembering instructions degrades under context pressure. dibs therefore supports enforcement at two levels, both opt-in:
Claude Code —
dibs hook install clauderegisters aPreToolUsehook. When an agent attempts to edit a file covered by another agent's claim, the tool call is blocked (exit code 2) and the model receives a message naming the holder, their reason, and the expiry. Agents consistently adjust course when given this context.Any agent —
dibs hook install pre-commitregisters a git hook that rejects commits touching files claimed by another agent.
Hook installation is additive and idempotent: existing entries in
.claude/settings.json and existing git hooks are preserved, and
dibs hook uninstall claude removes exactly what was added. Both hooks
fail open — if dibs cannot run, editing and committing proceed normally.
Lessons
Lessons capture what an agent learned so the next session does not rediscover it:
dibs lesson add "rate-limit middleware must register after auth" \
--body "The limiter reads ctx.User set by the auth guard. Registering it earlier panics." \
--tags middleware,auth
dibs lesson search "why does the rate limiter panic"
1.91 rate-limit middleware must register after auth [rate-limit-middleware-...]
The limiter reads ctx.User set by the auth guard. Registering it earlier panics...Lessons are markdown files with YAML frontmatter under .dibs/lessons/:
Shared through git — the whole team and CI receive them via
git pull; there is no per-machine database to synchronize.Reviewable — knowledge changes go through the same pull-request review as code, and can be corrected or reverted like code.
Searchable without infrastructure — BM25 ranking with light stemming over title, tags, and body, computed in memory per query. At the scale of a repository's accumulated lessons, lexical search is instant and requires no embedding model or vector store.
MCP server
dibs mcp runs a stdio MCP server, so agents coordinate through typed
tools rather than shell commands. The server instructions and tool
descriptions encode the protocol (claim before editing, release when done,
leave notes, record lessons):
Tool | Purpose |
| Claim patterns with a reason and TTL; returns GRANTED or DENIED with holder details. |
| Report whether paths are free or held. |
| Release claims. |
| Agents, claims, and unread notes. |
| Broadcast and read handoff notes. |
| Write and search the knowledge base. |
Client configuration:
# Claude Code
claude mcp add dibs -- dibs mcp# Codex (~/.codex/config.toml)
[mcp_servers.dibs]
command = "dibs"
args = ["mcp"]Any MCP client with stdio transport is supported.
Comparison
Adjacent tools solve different problems; the table shows where dibs fits.
dibs | Server-based orchestration platforms | beads | claude-squad / vibe-kanban | |
Primary job | coordination + shared lessons | memory + orchestration suites | issue tracking as agent memory | running and managing sessions |
File claims with expiry | ✅ | ✅ via a central server | ❌ | ❌ |
Blocks colliding edits | ✅ hooks | ❌ advisory | ❌ | ❌ (isolation via worktrees) |
Cross-worktree visibility | ✅ instant, via | while the server is running | n/a | creates the worktrees |
Runtime dependencies | none | server + web UI + database | none | varies |
Memory search | BM25 over in-repo files | vector embeddings | issue graph | ❌ |
Installation | single static binary | docker compose stack | single binary | binary / app |
dibs composes with these tools rather than replacing them. It pairs
naturally with beads for task
tracking (dibs claim src/auth --reason "bd-142: refactor auth") and with
any session manager, since coordination is independent of how sessions are
launched.
Design principles and limitations
No infrastructure. No daemon, no server, no database, no telemetry. All state is plain JSON and markdown on disk. If dibs is removed, a repository is left exactly as it was, minus one directory.
Leases, not locks. Every claim expires. A crashed or abandoned agent cannot block a repository.
Fail-open enforcement. A malfunctioning hook must never prevent legitimate work; enforcement errs on the side of allowing edits.
Cooperative trust model. dibs coordinates well-behaved agents and enforces claims inside Claude Code and at commit time. It is not a security boundary against a process that deliberately bypasses it.
Machine-local coordination. Live claims are per machine, which matches the dominant workflow of parallel agents on one workstation. Lessons travel across machines through git. Cross-machine live coordination is on the roadmap.
Conservative conflict detection. Overlapping glob prefixes are treated as conflicts even when the globs could be disjoint. False positives are cheap; silent collisions are not.
FAQ
What if an agent never calls dibs at all? Install the hooks. The Claude Code hook checks every file-modifying tool call regardless of what the model remembers; the pre-commit hook catches everything else at commit time.
What happens when an agent crashes while holding a claim? The claim expires after its TTL (default 30 minutes). The expiry is recorded in the journal.
Is dibs useful with a single agent? Yes, in a reduced role: lessons provide persistent knowledge across sessions, and the journal provides an audit trail of what was claimed and when.
Why not git lfs locks or lock files committed to the repository?
LFS locks require a server and do not expire; committed lock files create
commit noise and are invisible to uncommitted worktrees. Neither supports
glob patterns or communicates context to the blocked agent.
Roadmap
dibs tui— live terminal dashboard of agents and claimsdibs claim --wait— block until a lease becomes freenpm wrapper package for
npx dibsand MCP registry listingCross-machine coordination backend (opt-in)
Cursor and OpenCode enforcement recipes
Contributing
Contributions are welcome. The project intentionally stays small: stdlib plus three dependencies, no daemons, no databases. See CONTRIBUTING.md for guidelines and docs/protocol.md for the full coordination protocol.
License
Available Tools
8 toolsdibs_checkA
Check whether files are claimed by another agent. FREE means safe to edit; HELD tells you who has them and until when.
Inputs: paths (required).
dibs_claimA
Claim files or glob patterns before editing them, so parallel agents don't collide. Returns GRANTED with an expiry, or DENIED with who holds the files, why, and until when. Re-claiming the same patterns renews your lease.
Inputs: patterns (required), ttl, reason.
dibs_lesson_addA
Save a lesson for future agents as a markdown file under .dibs/lessons/ (committed with the repo, shared via git). Record gotchas, conventions, and hard-won fixes — not routine work logs.
Inputs: body (required), title (required), tags.
dibs_lesson_searchA
Search lessons recorded by previous agents before working in unfamiliar territory. Returns ranked matches with snippets.
Inputs: query (required), limit.
dibs_noteA
Broadcast a short note to every agent working on this repo. Use it for handoffs and heads-ups that affect others.
Inputs: message (required).
dibs_notesA
Read notes from other agents (marks them read). Check at the start of a session and before starting new work.
dibs_releaseA
Release your claims when you finish working on an area, so other agents can proceed. Leases also expire on their own.
Inputs: all, patterns.
dibs_statusA
See the whole picture: active agents on this repo, every live claim with expiry, and your unread note count. Call this at the start of a session.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool addresses a distinct coordination task—claim management, status overview, lessons, and notes—with no overlap. An agent can easily tell which tool to use for claiming, checking, releasing, or communicating.
All tools share the 'dibs_' prefix and use snake_case, but 'dibs_status' and 'dibs_notes' are nouns while most others are verbs (release, check, claim, etc.). This minor inconsistency is easy to overlook given the clear prefix and short names.
With 8 tools, the server is well-scoped for its purpose: 4 for claim/status management, 2 for lessons, and 2 for notes. Each tool earns its place without redundancy or bloat.
The tool surface fully covers the coordination domain: claim, release, check, status, lesson add/search, and note broadcast/read. There are no obvious missing operations—manual expiry is unnecessary because leases auto-expire, and release complements claim.
Maintenance
Related MCP Connectors
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Source control for coding agents: declare an intent, settle overlaps before code, verify each push.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Related MCP Servers
- AlicenseBqualityAmaintenanceA coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. Uses Git for human-auditable artifacts and SQLite for fast queries, enabling multiple agents to collaborate across projects without stepping on each other.412,240MIT
- AlicenseNot gradedqualityCmaintenanceLocal coordination for coding agents that share a Git working tree.6 npm2MIT
- AlicenseBqualityBmaintenanceEnables multiple coding agents sharing one repository to coordinate their work through time-limited directory and file leases, an enforced pre-tool-use hook, shared presence tracking, messaging, and an audit history, so they never edit or run each other's files concurrently.1558 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI coding agents to coordinate on a shared software project by registering, claiming tasks, declaring file intents, publishing structured change reports, and handing off context, with a local dashboard showing state in near real time.MIT