dibs

Overview

Running several coding agents — Claude Code, Codex, Cline, Cursor — againstone repository in parallel is now a common workflow, typically with one gitworktree per agent. The sessions share no state: an agent cannot see whatits peers are doing, and two agents that touch the same files producesilent overwrites and unmergeable diffs.

dibs provides the missing coordination primitives:

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:

$ 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 29m

With the Claude Code hook installed, an edit that violates a claim isblocked 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 $?
2

How it works

dibs relies on a property of git worktrees: every worktree of a repositoryshares a single common directory (git rev-parse --git-common-dir). Statewritten there is visible to all worktrees immediately, without commits, andnever 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 itself

• A claim is a JSON file containing an agent name, a set of patterns, areason, and an expiry. Conflict checks run under an advisory lock; expiryis evaluated lazily at read time. No daemon is required.
• Identity is resolved from --agent, then DIBS_AGENT, then a stablename derived from the worktree path — so each worktree has a consistentidentity with zero configuration.
• Patterns are doublestarglobs relative to the repository root (absolute paths are resolved intoit). Claiming a directory claims its subtree, and a path that does notexist yet is treated the same way. Only existing regular files areclaimed literally. Glob-to-glob conflict detection is conservative: twoglobs 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 JSONLjournal (dibs log).

Installation

go install github.com/polymatx/dibs/cmd/dibs@latest

Prebuilt binaries for Linux, macOS, and Windows (amd64/arm64) are on thereleases page. Building fromsource requires Go 1.25+; runtime requires git.

A Dockerfile is included for containerized use — mount your repository at/workspace:

docker build -t dibs .
docker run --rm -i -v "$PWD":/workspace dibs mcp

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)

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 instructionsdegrades under context pressure. dibs therefore supports enforcement at twolevels, both opt-in:

• Claude Code — dibs hook install claude registers a PreToolUsehook. When an agent attempts to edit a file covered by another agent'sclaim, the tool call is blocked (exit code 2) and the model receives amessage naming the holder, their reason, and the expiry. Agentsconsistently adjust course when given this context.
• Any agent — dibs hook install pre-commit registers a git hook thatrejects 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, anddibs hook uninstall claude removes exactly what was added. Both hooksfail open — if dibs cannot run, editing and committing proceed normally.

Lessons

Lessons capture what an agent learned so the next session does notrediscover 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 viagit pull; there is no per-machine database to synchronize.
• Reviewable — knowledge changes go through the same pull-requestreview as code, and can be corrected or reverted like code.
• Searchable without infrastructure — BM25 ranking with light stemmingover title, tags, and body, computed in memory per query. At the scale ofa repository's accumulated lessons, lexical search is instant andrequires no embedding model or vector store.

MCP server

dibs mcp runs a stdio MCP server, so agents coordinate through typedtools rather than shell commands. The server instructions and tooldescriptions encode the protocol (claim before editing, release when done,leave notes, record lessons):

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 composes with these tools rather than replacing them. It pairsnaturally with beads for tasktracking (dibs claim src/auth --reason "bd-142: refactor auth") and withany session manager, since coordination is independent of how sessions arelaunched.

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, arepository is left exactly as it was, minus one directory.
• Leases, not locks. Every claim expires. A crashed or abandoned agentcannot block a repository.
• Fail-open enforcement. A malfunctioning hook must never preventlegitimate work; enforcement errs on the side of allowing edits.
• Cooperative trust model. dibs coordinates well-behaved agents andenforces claims inside Claude Code and at commit time. It is not asecurity boundary against a process that deliberately bypasses it.
• Machine-local coordination. Live claims are per machine, whichmatches the dominant workflow of parallel agents on one workstation.Lessons travel across machines through git. Cross-machine livecoordination is on the roadmap.
• Conservative conflict detection. Overlapping glob prefixes aretreated as conflicts even when the globs could be disjoint. Falsepositives 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 toolcall regardless of what the model remembers; the pre-commit hook catcheseverything 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 isrecorded in the journal.

Is dibs useful with a single agent?Yes, in a reduced role: lessons provide persistent knowledge acrosssessions, and the journal provides an audit trail of what was claimed andwhen.

Why not git lfs locks or lock files committed to the repository?LFS locks require a server and do not expire; committed lock files createcommit noise and are invisible to uncommitted worktrees. Neither supportsglob patterns or communicates context to the blocked agent.

Roadmap

• dibs tui — live terminal dashboard of agents and claims
• dibs claim --wait — block until a lease becomes free
• npm wrapper package for npx dibs and MCP registry listing
• Cross-machine coordination backend (opt-in)
• Cursor and OpenCode enforcement recipes

Contributing

Contributions are welcome. The project intentionally stays small: stdlibplus three dependencies, no daemons, no databases. SeeCONTRIBUTING.md for guidelines anddocs/protocol.md for the full coordination protocol.

License

MIT © 2026 polymatx