dibs

Purpose

Running multiple AI coding agents (Claude Code, Codex, Cline, Cursor, etc.) in parallel on the same code repository is already a common workflow, usually with one git worktree per agent. These sessions do not share state: agents cannot see what their peers are doing, and two agents touching the same file will cause silent overwrites and unmergeable diffs.

dibs provides the missing coordination primitive so that parallel coding agents no longer collide.

Main capabilities

• File claims and expiry: A claim is a JSON file containing the agent name, a set of patterns, a reason, and an expiry time. Conflict checks run under an advisory lock, and expiry times are evaluated lazily on read, with no daemon required.
• Pattern matching: Patterns are doublestar globs relative to the repository root (absolute paths are resolved into the repository root). Claiming a directory claims its entire subtree, and paths that do not yet exist are handled the same way. Only existing regular files are claimed literally. Glob-to-glob conflict detection is conservative: two globs with nested static prefixes are treated as conflicting.
• Identity resolution: Identity is resolved in the order of --agent, DIBS_AGENT, and a stable name derived from the worktree path, so every worktree has a consistent zero-config identity.
• Log: Every claim, rejection, release, expiry, and note is appended to a JSONL log (dibs log).
• Enforcement hooks (optional enablement):
  • Claude Code: dibs hook install claude registers a PreToolUse hook. When an agent tries to edit a file covered by another agent's claim, the tool call is blocked (exit code 2), and the model receives a message indicating the holder, reason, and expiry time.
  • Any agent: dibs hook install pre-commit registers a git hook that rejects commits touching files claimed by other agents.
  • Hook installation is additive and idempotent: existing entries in .claude/settings.json and existing git hooks are preserved, and dibs hook uninstall claude removes only what was added. Both hooks fail open: if dibs cannot run; editing and committing proceed normally.
• Lessons: Capture what the agent has learned so that the next session does not have to rediscover it. Lessons are Markdown files with YAML frontmatter under .dibs/lessons/, shared via git—the whole team and CI get them via git pull; they can be reviewed, corrected, or reverted through pull requests like code; they use BM25 ranking with lightweight stemming on titles, tags, and body text, computed in memory per query, with no embedding model or vector store required.
• MCP server: dibs mcp runs a stdio MCP server, and agents coordinate through typed tools rather than shell commands. The server instructions and tool descriptions encode the protocol (declare before editing, release when done, leave notes, record lessons). It supports any MCP client with stdio transport.

Usage

Get precompiled binaries for Linux, macOS, and Windows (amd64/arm64) from the releases page. Building from source requires Go 1.26+; running requires git.

Multi-architecture container images are published on GHCR—mount the repository at /workspace. The same image can also be built locally from the included Dockerfile (docker build -t dibs .).

Exit codes: 0 means normal/idle, 1 means error, 2 means rejected or held by another agent. All commands that read state accept --json for scripting.

It can be used with task tracking tools (such as beads), for example dibs claim src/auth --reason "bd-142: refactor auth"; it can also be used with any session manager, because coordination is independent of how the session is started.

When to use it

• Teams running multiple coding agents in parallel on the same workstation.
• Scenarios where you want agents to declare files before editing and avoid silent overwrites.
• Scenarios where you want the lessons accumulated by agents to be reviewed and shared through git along with the code.
• Scenarios where you want to coordinate agents with typed MCP tools rather than shell commands.

Limitations

• No infrastructure: no daemon, server, database, or telemetry. All state is plain JSON on disk and Markdown. After removing dibs, the repository returns to its original state, just missing one directory.
• Leases, not locks: Every claim expires. A crashed or abandoned agent cannot block the repository (default TTL 30 minutes, expirations are logged).
• Fail-open enforcement: Hook failures must never block legitimate work; enforcement tends toward allowing edits.
• Cooperative trust model: dibs coordinates well-behaved agents and enforces claims within Claude Code and at commit time. It is not a security boundary against processes that deliberately bypass it.
• Machine-local coordination: Live claims are stored machine-locally, matching the mainstream workflow of parallel agents on one workstation. Lessons learned propagate across machines via git. Cross-machine live coordination is on the roadmap.
• Conservative conflict detection: Overlapping glob prefixes are treated as conflicts even if they might be disjoint. False positives are cheap; silent collisions are not.
• Single-agent use: dibs is also useful for a single agent in a reduced role: lessons learned provide persistent knowledge across sessions, and the log provides an audit trail of when claims were made.

Comparison with other approaches

Adjacent tools solve different problems. dibs combines with these tools rather than replacing them. It does not use git lfs locks or lock files committed to the repository, because 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, and neither can convey context to a blocked agent.

Project information

MIT © 2026 polymatx. The project is intentionally kept small: standard library plus three dependencies, no daemon, no database. See CONTRIBUTING.md for contribution guidelines, and docs/protocol.md for the full coordination protocol.