polymatx/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. | dibs status lists every agent, claim, reason, and expiry. |
| 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. | dibs note broadcasts a message to every agent on the repository, with per-agent read tracking. |
| Knowledge is lost between sessions. | Lessons are markdown files under .dibs/lessons/, committed with the repository and searched with BM25. |
The design rationale is covered in more depth in the introduction post:
Why Parallel Coding Agents Need a Coordination Layer.
Demo
Two agents, one repository:
With the Claude Code hook installed, an edit that violates a claim is
blocked before it happens, and the model is told why:
How 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.
- A **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, then DIBS_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
Prebuilt 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:
The same image builds locally from the included Dockerfile (docker build -t dibs .).
Usage
| Command | Description |
|---|---|
| dibs claim ... [--reason ...] [--ttl 30m] | Lease files or globs. Default TTL 30m, maximum 24h. |
| dibs release [pattern]... [--all] | Release leases. Bare dibs release releases everything you hold. |
| dibs renew [--ttl 30m] | Extend all of your leases. |
| dibs check ... | Report whether paths are covered by another agent's lease. |
| dibs status [--json] | Agents, claims, and unread note count. |