# polymatx/dibs [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/polymatx/dibs  
**GitHub Stars:** 2  
**npm Downloads (last month):** 15  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/polymatx-dibs

## Description
Coordination layer for parallel coding agents: TTL file claims stored in the git common dir (visible across every worktree instantly), enforcement hooks that block colliding edits in Claude Code and at commit time, agent presence, handoff notes, and git-committed lessons searchable with BM25. Single static binary — no server, no database.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "dibs": {
    "command": "npx",
    "args": ["-y","dibs"],
    "env": {
      "DIBS_AGENT": ""
    }
  }
}
```

**Requires environment variables:** `DIBS_AGENT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What polymatx/dibs does

polymatx/dibs coordinates multiple coding agents that operate on one Git repository, including repositories divided into worktrees. Its core unit is a file claim: an agent leases a path, directory, or glob for a limited period and gives a reason for the lease. Other agents can inspect claims, avoid conflicting work, or send a note to the current holder.

The project also tracks agent presence, unread notes, lease events, and a journal of coordination activity. Lessons are stored as Markdown files under `.dibs/lessons/`, committed with the repository, and searchable with BM25 so later sessions can find prior findings.

## How it works

polymatx/dibs keeps live coordination data in the Git common directory returned by `git rev-parse --git-common-dir`. Because all worktrees share that directory, claims and presence updates are visible across worktrees without commits. This state is machine-local and does not appear in normal Git status output. Knowledge files use the repository’s `.dibs/` directory instead, making lessons available through Git history, review, and CI.

Claims are JSON records containing an agent identity, patterns, a reason, and an expiry. Conflict checks use an advisory lock, while expired leases are discarded logically when state is read. The default lease duration is 30 minutes and the maximum is 24 hours. Agent identity comes from `--agent`, then `DIBS_AGENT`, and finally a stable name derived from the worktree path.

Patterns are doublestar globs relative to the repository root. Directory claims cover their subtrees, and paths that do not exist yet can still be claimed. Conflict detection for two globs is conservative when their static prefixes overlap in a nested way.

## Setup and configuration

Install the binary with `go install github.com/polymatx/dibs/cmd/dibs@latest`, use a release binary for Linux, macOS, or Windows, or run the published container image. Building from source requires Go 1.26 or newer; running dibs requires Git.

From the repository root, run `dibs init` to create the `.dibs/` directory. The optional `--agents-md` flag adds the coordination protocol to `AGENTS.md`. Run `dibs mcp` to start the MCP server over stdio. The container example mounts the repository at `/workspace` and invokes the same MCP command.

## Tools and capabilities

polymatx/dibs supports these command-level operations:

- Claim, release, renew, and check file leases.
- Show agents, claims, expiry information, and unread note counts.
- Broadcast notes and read them with per-agent tracking.
- Add, list, show, and BM25-search lessons.
- Inspect journal events and identify the current agent.
- Install or remove Claude Code and pre-commit enforcement hooks.

State-reading commands support `--json` for scripting. Exit code `2` indicates a denied operation or a path held by another agent.

## Limitations and notes

The system has no database, daemon, background process, or separate coordination service. Claims are leases, so a crashed agent’s claims expire rather than requiring manual cleanup. Enforcement is opt-in: the Claude Code hook blocks conflicting edit attempts, while the pre-commit hook rejects commits that touch another agent’s claimed files. Both hooks fail open if dibs cannot run, allowing the edit or commit to continue.

The Claude Code hook is specifically for Claude Code. The pre-commit hook applies at Git commit time and can cover agents that use the repository’s commit workflow. Existing Claude settings and Git hooks are preserved during additive, idempotent installation.

_Full upstream README: https://allmcps.com/mcp/polymatx-dibs/readme_