{
"markdown": "![\"\"](\"docs/icon.svg\")
\n\n# Dibs\n\n[](https://github.com/agenxy/dibs/actions/workflows/ci.yml)\n[](https://github.com/agenxy/dibs/releases/latest)\n[](https://pkg.go.dev/github.com/agenxy/dibs)\n[](LICENSE)\n\n**Keeps your agents in the loop about each other.**\n\nOne place your agents look to see what the rest of the fleet is doing, and the\nmeans to do something about it: typed messages with deadlines and receipts, file\ntransfer, advisory claims on shared resources, and topic spaces they can join.\nDibs reports; it never acts.\n\nYou have three agents open. One is refactoring the session store. Another, in a\ndifferent window, has just decided the session store needs refactoring. Neither\ncan see the other, so you pay for the work twice and then pay again to reconcile\nit. Version control will not save you: the conflict is not in the files, it is in\nthe *intent*, and by the time it reaches a file the waste already happened.\n\nThat is the failure Dibs was built for, and it is the smallest one. Agents that\ncan see each other can also hand work over, ask a question and wait for the\nanswer, send a file, agree who holds a directory, and read what happened while\nthey were not running.\n\nOne board covers every agent that connects to it, across as many projects as you\nhave open, and across machines: `dibd` binds to loopback by default, and to a\ntailnet or LAN address if you want agents on other computers on the same board.\nAn agent is not tied to a repository: nothing binds it to a project, claims are\nabsolute paths, and mail is addressed to agents. Each agent is labelled with the\nproject it is working in, so a fleet spread over three repositories reads as\nthree groups rather than a column of identical rows. If you would rather keep two\nfleets apart, run a second `dibd` on its own data directory and they share\nnothing.\n\n\n\n### What a collision looks like\n\nTwo agents, in different windows, set out to do the same thing. The second one\ndeclares its work and Dibs answers:\n\n```jsonc\n// codex-1 → declare\n{ \"text\": \"Fixing session reconnect handling\",\n \"dirs\": [\"internal/session\"], \"refs\": [\"issue:1140\"] }\n```\n\n```jsonc\n{\n \"ok\": true, // nothing was blocked\n \"slot_id\": \"s1\",\n \"overlaps\": [\n { \"agent\": \"claude-1\", \"signal\": \"same-objective\", \"kind\": \"slot\",\n \"text\": \"Reworking how the session store handles reconnects\",\n \"refs\": [\"issue:1140\"] }\n ],\n \"warning\": \"another agent is already pursuing the same objective: you are\n probably about to duplicate its work. Read its slot, then message it\n (question/handoff) to split or stand down. This is the measured failure;\n do not just proceed.\"\n}\n```\n\n`ok` is `true`. Dibs did not stop anything and cannot: it recorded the\ndeclaration, named the peer already pursuing that objective, and left the\ndecision to the two agents. [Tutorial](docs/TUTORIAL.md).\n\n### What else is on the board\n\nDeclaring work is one tool of 44. The rest is what agents do once they can\nsee each other:\n\n- **Mail.** Private mailboxes, four types (`notify`, `question`, `request`,\n `handoff`), with delivery receipts, deadlines and attachments. A question\n blocks nobody: it waits, and can be declined.\n- **Files.** Content-addressed blobs, encrypted at rest, up to 64 MiB, attached\n to a message or fetched by id. Agents on different machines can pass work\n products without touching your filesystem.\n- **Claims.** Advisory `shared` or `exclusive` holds on absolute paths, with a\n human override. Advisory means exactly that: nothing is enforced.\n- **Spaces.** Topic channels agents open, join and merge, with announcements\n that require acknowledgement, and admit/evict for who belongs.\n- **History.** Every one of those is an entry in an encrypted, hash-chained\n ledger, and the state is a pure fold over it. An agent that was not running\n can read what it missed, and `dibs verify` proves the record was not edited.\n\nNo agent can act on another through Dibs. The worst thing you can receive is a\nmessage you may decline. It is a visibility layer, not an orchestrator.\n\n### When an agent needs you\n\nYou are a row on the board like anybody else, so an agent can address you the\nway it addresses a peer. A question reaches you as a notification on your own\nmachine, and you answer it there: no terminal, no board to open, nothing to\ntype into a tool.\n\n| An open question | An answer the agent enumerated |\n|---|---|\n|  |  |\n\nAn agent that states its options gets a press instead of a sentence: up to three\nbecome the notification's own buttons, so answering costs one gesture. Requests\nwork the same way and carry an effect. `request` + `grant: \"coordinator\"`\npromotes the asker when you approve it; `request` + `adopt: \"\"` hands a\nreturning agent its old mailbox back. **Approving is the act, not a note saying\nsomebody agreed one should happen.** There is never a command left for you to\nrun afterwards.\n\nThat matters because the alternative is you as the transport. An agent that has\nto wait for a human to notice, open something and relay an answer is one you are\ncarrying.\n\n**Two agents editing the same file is normal and healthy.** Dibs is not a lock\nover your source. The waste it exists to catch is *redundant effort*: two agents\nchasing one goal. [REQUIREMENTS.md](REQUIREMENTS.md) has the measured incident\nthat defines the design.\n\n---\n\n**Contents**: [Install](#install) · [Tutorial](docs/TUTORIAL.md) ·\n[For agents](#for-agents) · [What you get](#what-you-get) ·\n[Catching duplicate work](#catching-duplicate-work) ·\n[When a subagent stops working](#when-a-subagent-stops-working) ·\n[Configuration](#configuration) · [Security](#security) ·\n[Platform](#platform) · [Design](#design) · [Engineering](#engineering)\n\n---\n\n## Install\n\nListed in the official [MCP Registry](https://registry.modelcontextprotocol.io)\nas `io.github.Agenxy/dibs`, which is where a harness or an agent looks up a\nserver it has not been told about:\n\n```sh\ncurl 'https://registry.modelcontextprotocol.io/v0/servers?search=dibs'\n```\n\nTwo static binaries: `dibd` (daemon, MCP server and web board) and `dibs`\n(the CLI). Both `CGO_ENABLED=0`, byte-for-byte reproducible. No database, no\nNode, no runtime dependencies.\n\n### Homebrew (macOS)\n\n```sh\nbrew tap agenxy/tap\nbrew trust agenxy/tap\nbrew install dibs\n```\n\nHomebrew 6 refuses to load casks from a tap you have not trusted, so the first\nline is not optional and the install fails with a trust error without it. It is\na one-time thing per tap.\n\n`agenxy/tap` is one tap for every Agenxy project, so the third component is the\nonly part that changes. `agenxy/lanes/lanes` still works: GitHub redirects the\nold repository name, and the tap maps the old cask to this one, so an install\nfrom before the rename upgrades in place on the next `brew update`.\n\nInstalls both binaries. The cask clears the macOS quarantine flag on install:\nthe binaries are cosign-signed for provenance but not Apple-notarised, and\nwithout that step macOS refuses to run them after a successful install, which\nlooks like a broken product rather than an unsigned one.\n\n### Go\n\n```sh\ngo install github.com/agenxy/dibs/cmd/dibs@latest\ngo install github.com/agenxy/dibs/cmd/dibd@latest\n```\n\nGo's module proxy is its package registry: there is nothing to publish and no\naccount to create. Any tagged, public repository is installable by path, and\n[pkg.go.dev](https://pkg.go.dev/github.com/agenxy/dibs) indexes it\nautomatically. The catch is that this needs a Go toolchain, so it suits\ncontributors more than users.\n\n### From source\n\nThe toolchain is pinned with [mise](https://mise.jdx.dev), so a checkout builds\nthe same way everywhere. mise will not read a config file it has not been told to\ntrust, which means a fresh clone needs one command first:\n\n```sh\nmise trust && mise install # pinned Go/Task/lint/release toolchain\ntask install # build + install to ~/.local/bin\n```\n\nSkip the trust step and `task build` fails with `No version is set for shim:\ntask`, which reads like a missing install rather than an untrusted config. If you\nwould rather not use mise at all, `go build ./cmd/...` needs nothing but Go\n1.26.6. On an earlier patch release, `GOTOOLCHAIN=local go build ./cmd/...`\nbuilds fine and skips the toolchain download, which on a restricted-egress\nnetwork is a hard failure rather than a slow one.\n\n#### Without mise or task\n\nOn a network that allows the Go module proxy but not the object store it\nredirects to, neither tool installs, and the failure reads like a broken\ntoolchain rather than a blocked host. Dibs itself still builds: its own\ndependencies resolve from the proxy, and every build step is a `go build` or a\n`go run ./tools/...` in this tree.\n\n```sh\ngo build -o bin/dibd ./cmd/dibd\ngo build -o bin/dibs ./cmd/dibs\nswiftc -O -o bin/dibs-presence internal/humanauth/presence_darwin.swift # macOS\ngo run ./tools/appbundle -o bin/Dibs.app -version 0.0.0 # macOS\n```\n\nFour artifacts get installed, not two: `dibd`, `dibs`, and on macOS\n`dibs-presence` and `Dibs.app`. The daemon resolves the last two relative to its\nown executable, so they belong beside it. Copying only the binaries leaves the\ndaemon reporting a fault it cannot fix.\n\nThen install them, which is its own step: the commands above only produce\n`bin/`, so running `dibd` before this gets command-not-found on a fresh machine\nand the PREVIOUS build on a machine that has one.\n\n```sh\nmkdir -p ~/.local/bin\nrm -rf ~/.local/bin/dibs ~/.local/bin/dibd ~/.local/bin/dibs-presence ~/.local/bin/Dibs.app\ncp bin/dibs bin/dibd ~/.local/bin/\n```\n\nand on macOS, the two artifacts that only exist there:\n\n```sh\ncp bin/dibs-presence ~/.local/bin/\ncp -R bin/Dibs.app ~/.local/bin/\n/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f ~/.local/bin/Dibs.app\n```\n\nThat last line registers the bundle with Launch Services. Without it macOS does\nnot know it exists and refuses it notification authorisation, which presents as\na notifier that posts nothing and reports \"cannot notify\".\n\nTwo more install rules are not obvious from the commands:\n\n- **Remove before copying.** macOS caches a binary's signature verdict against\n its inode. `cp` over a running executable reuses the inode with new content,\n and every later run is SIGKILLed with no message, from a file that is\n byte-identical to a working one. `rm` first gives a fresh inode.\n- **Set the identifiers when signing.** The Go toolchain leaves them as `a.out`:\n\n ```sh\n codesign --force -i org.agenxy.dibs -s - ~/.local/bin/dibd\n codesign --force -i org.agenxy.dibs.cli -s - ~/.local/bin/dibs\n ```\n\n `-s -` is ad-hoc, which is fine to build with and costs a re-granted macOS\n privacy prompt on every install, because the system keys the grant to the\n signature. `go run ./tools/signcheck` says how to make a stable identity once\n and stop that.\n\nThen:\n\n```sh\ndibd & # daemon on 127.0.0.1:4777, data in ~/.dibs\ndibs mcp-config # print the MCP host config (add to e.g. .mcp.json)\ndibs admin set-password # once: the board is yours, not the agents'\ndibs web # print the live board URL\ndibs board # the same board, in the terminal\ndibs doctor # what is quietly broken, and how to fix it\n```\n\n### Shell completions\n\nThe binary generates its own completion scripts, from the same verb table the\nCLI dispatches on, so the completions cannot drift from the verbs (and no shell\nscript has to live in the tree). Write one to wherever your shell loads\ncompletions from:\n\n```sh\ndibs completion bash > /usr/local/etc/bash_completion.d/agents # bash\ndibs completion zsh > ~/.zsh/completions/_dibs # zsh (a dir on your $fpath)\ndibs completion fish > ~/.config/fish/completions/agents.fish # fish\n```\n\n### Keeping it running\n\n`dibd &` ties the daemon to the shell that started it: close the terminal or\nreboot and the fleet loses its board. For anything beyond a first look, run it\nunder your init system.\n\n**macOS (launchd)**: writes a user agent that starts at login and restarts on\ncrash:\n\n```sh\ndibs configure --service # writes ~/Library/LaunchAgents/org.agenxy.dibs.plist\nlaunchctl load -w ~/Library/LaunchAgents/org.agenxy.dibs.plist\n```\n\n**Linux (systemd user unit)**:\n\n```sh\ndibs configure --service # writes ~/.config/systemd/user/dibs.service\nsystemctl --user enable --now agents\n```\n\nTo stop the daemon for this data directory, and only that one:\n\n```sh\ndibs stop\n```\n\nNot `pkill dibd`. Dibs is built to let several isolated daemons coexist on a\nmachine, and a kill by name takes down whichever fleets happen to share the\nname.\n\n### A second machine\n\nThe board is a fleet board: agents on other machines join the same daemon and\nappear in the same rows. There is no second server to run, and nothing to\nreplicate.\n\nOn the joining machine, ask for the recipe. It derives the data directory from\nthe board's address and prints every step with the real paths filled in:\n\n```sh\ndibs mcp-config --board 127.0.0.1:4777\n```\n\nThat board gets a data directory of its own, holding its secret. The secret is\nper-board and is read from the data directory, so a machine that also runs its\nown board needs that second directory; its `~/.dibs` stays its own. The\ndirectory is named after the address, so a machine on three boards keeps three\nit can tell apart.\n\nIf the hub is a plaintext loopback daemon, which is the default, forward a port\nto it rather than exposing it to the network:\n\n```sh\nssh -N -L :127.0.0.1:4777 you@hub\n```\n\nThe two ends are independent: `4777` is what the hub listens on, and\n`` is whatever is free on this machine, which will not be 4777 if it\nalready runs a board of its own. `DIBS_ADDR` is then `127.0.0.1:`,\nthis machine's end of the forward. The hub never leaves\nloopback, and ssh has authenticated the machine before Dibs sees a byte. This\nis a supported transport, not a workaround: plenty of hosts will never have a\nroutable address, and requiring one would exclude them for no reason.\n\nA hub that is directly reachable serves HTTPS with a certificate it generated,\nand the bridge trusts only what the joining machine has recorded, so that\nmachine runs `DIBS_DIR= dibs trust ` once and\ncompares the fingerprint against `dibs fingerprint` on the hub. `DIBS_DIR` is not\noptional there: `trust` records the certificate in the directory it is given, and\nthe bridge reads it from the one in its own config. `mcp-config --board` prints whichever of these\ntwo steps the address calls for.\n\n**Once, not once a year.** What gets recorded is the board's own signing\nidentity, not the certificate it happens to be serving today. The daemon issues\nitself a short-lived certificate under that identity and replaces it whenever it\nnears expiry or stops naming an address clients dial, and a machine that has\nalready trusted the board keeps working through every one of those. The identity\nchanges only if you delete `tls-ca.pem` from the board's directory, which is the\none case where the ceremony is owed again.\n\nUse the bridge (`mcp-stdio`), not the url form. On a second machine that\nmatters more rather than less: a url client holds no nonce, so every reconnect\nforks an identity that cannot read its predecessor's mail, and the remote\nsessions are the long-lived unattended ones.\n\nPick the hub deliberately. Whichever machine runs the daemon decides whether\nthe fleet has a board at all, and a laptop is the tempting choice and the wrong\none: it sleeps, it changes networks, and it is the machine most likely to be\nrebooted mid-task. An always-on host reached by a forward is the answer.\n\nCheck it from the joining machine with `dibs doctor`, with the same `DIBS_ADDR`\nand `DIBS_DIR` set.\n\n### Upgrading a running fleet\n\nAfter installing a new build, one command moves the daemon onto it:\n\n```sh\ndibs upgrade\n```\n\nIt is deliberately not `dibs stop && dibd &`, because three things go wrong\nthere and all three are silent. The service unit pins an absolute path, so a\ndaemon installed somewhere new leaves the service starting a build from months\nago forever. A daemon started by hand comes back on the default loopback\naddress, which takes every remote agent off a board that was serving a fleet\nacross machines. And a new binary that cannot fold the ledger the old one wrote\nis only discovered *after* the daemon that could serve the board has been\nstopped.\n\nSo `dibs upgrade` runs the new binary against the ledger first (`dibd -check`,\nwhich replays without serving and is safe to run against a board another daemon\nis currently holding), and stops nothing unless that passes. Then it repoints a\nservice unit that pins the wrong daemon, restarts through the service manager\nwhere there is one and directly where there is not, restores the address the\ndaemon was bound to, and waits for the board to answer before reporting the\nserial and the agent count it came back with. Anything that fails between the\nstop and the start restarts the daemon on the build it was already running.\n\nNothing about this asks agents to re-register: `state == fold(ledger)`, so a\nrestarted daemon rebuilds the board rather than losing it, and the stdio bridge\nwaits the window out (REQUIREMENTS.md R12). `dibs upgrade -n` says what it would\ndo and changes nothing.\n\n### Configuration\n\nDibs runs correctly with no configuration file at all, and most fleets never\nwrite one. Everything the daemon accepts is in\n**[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**, with what happens if you\nleave each setting alone.\n\nAn unknown key stops the daemon rather than being ignored, deliberately: a\nsetting that was never going to take effect must not look applied.\n\n```sh\nman dibs # the CLI\nman 8 dibd # the daemon: flags, files, what a restart costs\ndibs doctor # what is actually in effect right now\n```\n\n### Verifying what you downloaded\n\nRelease artifacts are signed with [cosign](https://docs.sigstore.dev) in the\nSigstore bundle format: signature, certificate and transparency-log entry in\none file, and every archive ships an SPDX SBOM.\n\n```sh\nTAG=v0.0.1 # the release you downloaded\ncosign verify-blob checksums.txt \\\n --bundle checksums.txt.bundle \\\n --certificate-identity \"https://github.com/Agenxy/dibs/.github/workflows/release.yml@refs/tags/$TAG\" \\\n --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'\n```\n\nThe identity names the workflow AND the tag, so it has to match the release you\ndownloaded. `Verified OK` means the checksums file was produced by this\nrepository's release workflow at that tag, and `sha256sum -c checksums.txt` then covers the archives.\n\n`admin set-password` is a prerequisite for `dibs web`, not optional hardening.\nThe browser board shows decrypted mail and can act as you, so it is gated on\nsomething the agents do not have: every agent holds the coordination secret, none\nholds this. `dibs board` in the terminal needs no password: it shows only what\nthe board shows.\n\nAgents then coordinate through MCP tools: `register` → `check_in` →\n`declare` / `claim` / `send` / `await_events`. The server's instructions\nteach the protocol, so agents need no other documentation.\n\n**New here?** [docs/TUTORIAL.md](docs/TUTORIAL.md) walks the whole thing in\nfifteen minutes: daemon, two agents, and a duplicate-work collision caught in\nthe act.\n\n## For agents\n\nIf you are an AI agent connecting to Dibs, you need two things and neither is\nthis README.\n\n1. **The server teaches you the protocol on connect.** Its `instructions` carry\n the whole call sequence, and every error carries a `hint` naming the\n corrective call. You do not need separate documentation to make tool calls.\n\n2. **Read the resource `dibs://skills` once.** It is the layer above the\n protocol: the counterintuitive parts, the mistakes that look like success,\n and the defaults that are not what you would guess. It is served over MCP, so\n you can read it without this repository, and it is also\n [SKILLS.md](SKILLS.md) here.\n\nThe ones that have cost agents the most time:\n\n- **An agent is an AGENT, not a task.** Its name is your address (`reviewer`, not\n `refactor-auth`), because mail sent to a task name reads as nonsense.\n- **`declare` without a `slot_id` ADDS a declaration**, it does not replace one.\n Call it four times and the board shows you doing four things.\n- **A claim expiring is not permission.** It means coordination was lost, not\n that the other agent finished.\n- **A low overlap score is not proof you are alone.** Recall at tier 0 is ~0.3.\n A high score means \"look\"; a low score means nothing.\n- **Naming a `parent` grants you nothing**: lineage must be proven with a nonce\n the parent issues via `vouch_child`.\n- **Don't poll.** Run `dibs await` as a background shell task: it blocks and\n exits when events arrive, so your harness wakes you. The shell watches; you\n sleep, spending nothing.\n\nIf you are working *on* Dibs rather than with it, [AGENTS.md](AGENTS.md) is the map,\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) is the territory, and\n[llms.txt](llms.txt) indexes everything.\n\n## What you get\n\n- **A live board humans want open**: server-rendered, SSE-streamed (updates land\n in ~200 ms, no page reloads), dark/light, responsive, with a protocol guide at\n `/help`. No framework, no build step, no bundle: htmx and one hand-written script.\n- **A terminal that reads like the board**: `dibs board` opens with a one-line\n tally of the fleet, then agents, work and claims, colour carrying the same\n meaning it does in the browser. Piped, redirected, on a dumb terminal or under\n `NO_COLOR` it collapses to exactly the plain text it would have been, so\n `dibs board | grep builder` works and a redirected `dibs doctor` is a file\n you can paste into an issue.\n- **MCP-native**: 44 tools, self-teaching through server instructions and\n corrective error hints, plus resources and an MCP Apps panel. Dibs targets the\n **2026-07-28** stateless contract and also serves the legacy **2025-11-25**\n path, which, as of August 2026, is what every shipping host actually\n negotiates (see [below](#protocol-versions)). Both work; you need do nothing.\n- **Append-only, hash-chained ledger**: the persistence *is* the audit history.\n `dibs verify` checks integrity; `tail -f ~/.dibs/ledger.jsonl | jq` watches\n live.\n- **Honest liveness**: crash, hang and unresponsiveness are three different\n facts, reported as such. Claim expiry is *loss of coordination*, never \"safe to\n proceed\".\n- **Ephemeral and persistent agents**: session agents age out; standing roles\n (reviewers, nightly maintainers) sleep as `dormant` with durable mailboxes and\n wake by resuming.\n- **Zero-config security**: loopback by default; point it at a reachable address\n and it generates its own TLS certificate. No flags, no VPN, no external CA.\n- **Tested with real agents**: Codex CLI sessions coordinating end to end\n (register → awareness gate → claims with conflict surfacing → request →\n deny-with-reasoning → long-poll wake → sender reads the answer), with no\n interop friction on the MCP 2026-07-28 surface.\n\n## Catching duplicate work\n\nPath claims catch the collision that is cheap to detect: two agents naming the\nsame directory. Since v1.2 Dibs also catches the one that actually destroys\nwork: two agents doing the *same job* in different files.\n\nAn agent declares what it is doing in its own words. Dibs scores that against\nthe work already in flight, using the repository's own file layout and **git\nco-change history**, and **surfaces the agent already doing it** so they find each\nother before the duplicate effort happens:\n\n```\nalice: \"I am reworking how the session store handles reconnects\"\n → OPENED reworking-how-session-store-handles\nbob: \"looking at session persistence when the socket drops\"\n → CONSIDER reworking-how-session-store-handles score 0.27\n \"read the agent, and join_space if it is the same job\"\n```\n\nNo model, no download, no network. That is tier 0, reading your file names and\nyour commit history.\n\n**A score proposes; it does not commit you.** The default is `auto_join=declared`:\nbob is *shown* alice's agent and decides. Dibs joins an agent automatically only\non a shared identifying ref (`pr:1231`, `issue:88`, a coordination key), because\nthose name a thing that exists, while a score names a resemblance. Recall at\ntier 0 is around 0.3 and precision is not good enough to move somebody's work\nwithout asking; this example used to show bob JOINED, which the shipping default\nhas never done. `-match-auto-join always` restores unconditional joining if you\nwant it.\n\n### Tuning it\n\nMatching runs from the first agent registration, one index per repository, and\nthe daemon measures its own notify threshold on the history it has just mined.\nThere is nothing to switch on.\n\nWhat stays off is **joining**. `join_threshold` is 0 until you set it, so Dibs\nsuggests and never moves anybody:\n\n```sh\ndibs calibrate --repo . # measures YOUR repo, prints two numbers\ndibd -match-join & # notify is measured for you; set it only to disagree\n```\n\n`-match-repo` survives as a pre-warm: it indexes a tree before anybody registers\nfrom it, which is worth setting for a daemon started at login and worth nothing\notherwise.\n\n**Stop any daemon already running first.** Dibs refuses to start a second one\non the same machine, and names the one that is running. That is deliberate: two\ndaemons mean two boards, agents pointed at different ones cannot see each other,\nevery call still succeeds, and both boards look correct: the exact failure Dibs\nexists to prevent, made invisible. If you genuinely want two, say so with\n`-allow-parallel` and give each its own `-dir`. Two reasons are good ones:\nisolating agents you do not trust (see [SECURITY.md](SECURITY.md)), and keeping\na client's fleet on a board of its own. Understand what you give up: agents on\nseparate boards cannot see each other at all, so a shared dependency edited from\nboth is exactly the collision Dibs would otherwise have caught. One board with\nthe project shown per agent is the default for that reason.\n\nBetter still, put the numbers in `dibs.toml` and skip the flags entirely, which\nis what they are for.\n\n**Calibrate first.** Skipping it leaves `join_threshold` at zero, which means\nDibs suggests spaces and never joins one: deliberately, because auto-joining on\na threshold nobody measured is how every agent ends up in a single space. Measured\nacross five real repositories the calibrated threshold spans a factor of fifteen\n(0.022–0.327); there is no default that is not badly wrong somewhere.\n\nRead what calibrate tells you. If it reports that little related work clears the\nbar, it is saying matching cannot discriminate on this repository: leave\n`join_threshold` at 0 and take the suggestions instead. It says so explicitly\nrather than printing a number and hoping.\n\n### How well it actually works\n\n| repository | commits | recall@5 | under a punitive hold-out |\n|---|---|---|---|\n| hermes-agent | 310 | 0.214 → **0.362** | 0.319 |\n| opencode | 261 | 0.141 → **0.246** | 0.178 |\n| pi-mono | 281 | 0.176 → **0.336** | 0.230 |\n| codex | 203 | 0.124 → **0.196** | not measured |\n\n*(before → after the history index, tier 0, no model involved. Reproduce with\n`dibs calibrate --repo -n 60 -skip 5`; the punitive column is\n`go test ./internal/overlap -run PunitiveHoldout -v`.)*\n\n**Recall@5 near 0.3 is not \"solved\".** It means that for roughly a third of\ndeclarations the right file is in the top five: enough to put two agents in the\nsame space often enough to be worth having, and nowhere near enough to trust\nblindly. SPEC-CHANNELS §10.1 governs: **a low score is never proof that two\nagents will not collide.**\n\nThose numbers are **held out**, and how they were measured is the part to read.\n`dibs calibrate` evaluates by using a commit message as the query and that\ncommit's changed files as the answer, which is the exact pairing the history\nindex is built from. Measured naively, this change took recall@5 from 0.288 to\n0.815 and MRR to a perfect 1.000: the query was retrieving the commit it came\nfrom. Calibrate now holds evaluation commits out of the index, which is also what\nproduction does: index the past, predict the present. The real gain is an order\nof magnitude smaller than the leak that hid it.\n\nThe obvious next objection is near-duplicates: holding out the exact commit still\nleaves reverts, follow-ups and squashed series describing the same work. On these\nrepositories 51–66% of queries do have another commit sharing two or more\nsignificant terms. So the last column removes those too: every commit sharing\ntwo terms with any query, roughly **half the corpus**: and the gain survives at\n+26% to +49% over no history at all. Smaller, and real: near-duplicates\ncontribute to the improvement rather than being it.\n`TestHistoryGainSurvivesAPunitiveHoldout` asserts this rather than describing it.\n\n### Where overlap actually appears in the response\n\nTwo mechanisms, two keys. `declare`'s response is the primary integration\nsurface, so it is worth naming them explicitly:\n\n| Mechanism | Key | Also carries |\n|---|---|---|\n| **Exact signals**: a shared `refs:` entry, a shared directory | `overlaps` | `warning` |\n| **Scorer matching**: related work sharing no literal signal | `spaces` | `spaces_hint` |\n\nThey are independent: a declaration can produce either, both, or neither.\n`overlaps` needs no index and no threshold, so it works on the first\ndeclaration and across machines. `spaces` needs the repository indexed and a\n`notify_threshold` above zero, which the daemon measures for itself, and reports\n`matching: \"indexing\"` while the index is still building.\n\nAn operator integrating against Dibs logged `overlaps` and `suggestions`, saw\nempty results three times, and concluded matching was broken. It was working\nand writing to `spaces`, a key nothing had told them to read.\n\n### Semantic matching\n\nThe floor needs no model. To relate work that shares neither words nor history,\npoint Dibs at an embedding service: one endpoint, so MLX, llama.cpp, Ollama or\na hosted API all satisfy it:\n\n```sh\npip install mlx mlx-embeddings\ncontrib/embed-sidecar/dibs_embed.py --repo . --port 8737\ndibd -match-repo . -match-join 0.33 -match-embed-url http://127.0.0.1:8737\n```\n\nAn absent or slow sidecar degrades to the built-in scorer and records `degraded`\non any membership it caused: matching gets worse, nothing stops.\n\n**Know the scale limit before you rely on it.** Indexing is one chunk per ~40\nlines: this repository is 855 chunks and takes ~110s against a local Ollama. A\n7,400-file repository produced **58,710 chunks** and the service gave out partway\nthrough. Dibs fell back to tier 0 and said so, which is honest and is *not*\nequivalent, because tier 0 cannot relate work sharing neither words nor file\nhistory. If your repository is large, `-match-repo` can pre-warm a subtree instead of\nthe whole tree.\n\n### Matching indexes itself\n\nNothing needs configuring. Every agent registers with a working directory, and\nthe repository containing it is exactly the history worth mining, so each tree\nis indexed the first time an agent turns up in it, up to sixteen of them.\n\nOne index per repository, and an agent is scored by the tree it is working in.\nA co-change model asked about a different project's sentence does not decline;\nit answers confidently and wrongly, which is worse than no matching at all. An\nagent in a tree that is not indexed simply gets no semantic suggestions, and\nstill gets the shared-refs and shared-dirs signals, which are computed in the\ncore and need no index.\n\n`-match-repo` survives only as a pre-warm, for a daemon started at login that\nshould have an index ready before the first agent arrives.\n\nAgents working in a different tree are detected as such, and the matcher then\ndeclines to claim evidence rather than inventing it, because the only files two\nunrelated projects share are the ones every project has. `dibs doctor` names the\nindexed repository and warns when you are working outside it. Indexing several is\n[issue #7](https://github.com/agenxy/dibs/issues/7).\n\n### Choosing a model\n\nRetrieval models are asymmetric: a task description and a chunk of code are not\nthe same kind of text, and every serious one is trained with a marker saying\nwhich side it is being given. Dibs applies the right one automatically, keyed off\nthe model name. Getting the marker wrong costs more than choosing a smaller model:\n\n| scorer (on this repo) | recall@5 | MRR | related work clearing the bar |\n|---------------------------|----------|-------|-------------------------------|\n| snowflake-arctic-embed2 | 0.551 | 0.807 | **53%** |\n| built-in (no model) | 0.284 | 0.542 | 50% |\n| qwen3-embedding:0.6b | 0.508 | 0.760 | 49% |\n| qwen3-embedding:4b | 0.562 | 0.826 | 42% |\n| nomic-embed-text | 0.526 | 0.752 | 36% |\n\nThe same 4B model *without* its markers scores 22%: half. A four-times-larger\nmodel does not recover a distinction the input never encoded. Getting a marker\n*wrong* is worse: arctic-embed scored 42% while being given a document prefix its\ncard does not specify, and 53% once that was removed.\n\nWhich is why Dibs keys per model rather than per family. Families are not\ninternally consistent, and the differences are invisible from the name:\n\n- **BGE** needs four different things. `bge-large-en-v1.5` wants a trained\n English instruction, `bge-large-zh-v1.5` a different Chinese one, `bge-m3`\n documents that it needs *none*, and `bge-code-v1` / `bge-en-icl` /\n `bge-multilingual-gemma2` want `…\\n…`.\n- **arctic-embed** changed its prefix between v1 and v2. One version apart, same\n vendor, and the two strings share nothing.\n- **e5** marks both sides: except `e5-mistral-7b-instruct`, which is\n instruction-style and states plainly that documents need none.\n\nDibs only claims a convention a model card states. A model it does not recognise\nwarns and is addressed symmetrically: recoverable, unlike a confident wrong\nmarker. Measure your own repository rather than trusting this table; that is what\n`dibs calibrate` is for.\n\n## When a subagent stops working\n\nAn agent that spawns another (`codex exec`, a nested `claude`, an opencode run)\ngets one signal back, at the end: an exit code. Everything before it is silence,\nand silence has four causes that look identical from outside. The child is\nmid-turn. It is blocked on a permission prompt nobody will answer. It hung on a\nsocket. Or the lid was shut and nothing was running at all.\n\nMeasured on one machine, two `codex exec` processes side by side:\n\n```\n alive 22m CPU 19.6s 1.5%: working, producing output\n alive 7h39m CPU 0.11s 0.0004%: did nothing since it started\n```\n\nThe parent of the second had been blocked on it for seven and a half hours.\n\nAsk any time:\n\n```\ndibs probe --pid 48620\npid 48620: stuck: alive 7h40m and has used 100ms of CPU in all of it\n(0.0004% busy): it has done nothing since it started\n```\n\nOr be told. `dibd` sweeps every 20 seconds and sends the agent that spawned a\nsubagent a notice when it stalls, delivered on that agent's next `check_in`\nwithout it having to ask. Attribution happens at spawn time, where the harness\nallows it: in Claude Code a `PreToolUse` hook stamps the command with its\nparent's agent, and the OS carries that into every descendant, through\ndetaching, daemonisation and reparenting, which is where process ancestry\ngives up. Codex has no hook Dibs can use without spawning a subprocess, which\nit will not do, so there a child should call `vouch_child` and register with\nthe nonce instead.\n\n**It reports and never acts.** `codex exec resume` exists and Dibs will not call\nit: the parent knows what the child was for and whether re-running it is safe. A\nsupervisor that silently repairs things teaches its operator nothing and hides a\nfailure that may be systematic. Dibs hands back the command; running it is your\ncall.\n\n**Sleep is not silence.** Elapsed time is measured on a monotonic clock, so a\nclosed lid does not read as a stalled fleet: on the development machine, 8.45 of\nthe last 80.3 hours since boot were sleep. You are told \"silent for 3 awake\nminutes; the machine also slept 38\" rather than \"silent for 41\".\n\nDesign and measurements: [SPEC-SUPERVISION.md](SPEC-SUPERVISION.md).\n\n## Configuration\n\nSettings live in `/dibs.toml` rather than on the command line, which is the\npoint: a threshold you measured should not have to be retyped every restart.\n\n```toml\n[match]\nrepo = \"/path/to/repo\"\njoin_threshold = 0.327 # from `dibs calibrate`\nnotify_threshold = 0.163\nembed_url = \"http://127.0.0.1:8737\"\nembed_model = \"qwen3-embedding:0.6b\"\n# retrieval markers are inferred from the model name; set these only for a\n# family Dibs does not know:\n# embed_query_prefix = \"query: \"\n# embed_doc_prefix = \"passage: \"\n# a bearer token is NOT a config key: export DIBS_MATCH_EMBED_KEY instead\n\n[limits]\nagent_ttl = \"5m\" # how long an agent that gave a PID may go silent\nidle_ttl = \"45m\" # ...and one that did not: probably you, see below\nblob_store_bytes = 1073741824 # 1 GiB: hard cap on the attachment store\n\n[supervise]\nmin_age = \"10m\" # how old before a whole-life idleness verdict is allowed\nmin_duty = 0.0005 # CPU share below which a long-lived process counts as idle\n\n[roles]\n# Standing roles. The daemon grants these at startup and re-applies them as\n# agents register, so a role survives a board reset instead of having to be\n# re-granted by hand.\ncoordinator = [\"orchestrator\"] # broadcast, force-release, merge, evict\nadmin = [\"fleet-lead\"] # all of that, plus reading every agent's mail\n\n[roles.identity]\n# REQUIRED, and this is the half that makes the block above safe. A name\n# authenticates nobody: any agent may register as \"fleet-lead\". Each entry is\n# the FINGERPRINT of the agent allowed to hold that name, which `register`\n# returns and the daemon prints at startup for you to paste. Never the nonce\n# itself, which is that agent's whole recovery credential.\norchestrator = \"…64 hex characters, from the startup log…\"\nfleet-lead = \"…64 hex characters…\"\n```\n\n**Declaring a role in config is a human decision.**\nNo agent can promote itself: `grant_role` is not an MCP tool, it is admitted only\non the daemon's admin path, and a system op presented with an agent token is\nrefused outright. The file is authority because you own the file: an agent\ncannot reach it through Dibs, and cannot ask Dibs to.\n\nGranting by hand still works (`dibs admin coordinator `), but it dies with\nthe ledger it lived in. A fleet that resets its board and silently has nobody\nable to merge two colliding agents is the failure this avoids.\n\nAnything you leave out keeps its default, and flags override the file for a\none-off.\n\n**Which TTL applies to you is not obvious.** `agent_ttl` governs agents that\nregistered a **PID**, where death can be checked directly and a short lease is\nsafe. `idle_ttl` governs agents that did not, where silence is the only evidence,\nand silence is what a human-paced agent does between turns, so it defaults to 45\nminutes. The MCP config that `dibs mcp-config` prints is a plain HTTP client,\nwhich registers **without** a PID. If you set `agent_ttl` and nothing changed,\nthis is why: set `idle_ttl`.\n\n`agent_ttl` is worth a thought before you leave it alone. Any authenticated call\nrenews an agent's lease, so a chatty agent never goes near it, but an agent\nrunning a long build or a slow test suite makes no Dibs calls for its duration,\nand a crashed owner *yields its exclusive agents*. Set it above your longest\nsilent step, or a busy agent loses an agent it is still working in. Lower it if you\nwould rather find out about crashes sooner.\n\n`blob_store_bytes` is a *hard* bound, not a target: when the store is over it,\neviction drops content that messages still reference rather than exceed the cap.\nA recipient then gets `E_BLOB_EVICTED`: which says plainly that its access was\nnever the problem and the content is gone, but the artifact is gone all the\nsame. Raise it if your fleet exchanges large build outputs.\n\n### What Dibs writes to disk\n\n- `~/.dibs/`: the data directory: ledger, keys, blobs. Move it with `-dir`.\n- `~/.dibs-run/`: one small file per running daemon, so a second one can tell\n it is not alone and `dibs doctor` can report a fleet split across two boards.\n Nothing durable lives here; entries are removed when their daemon exits, and a\n leftover from a crash is detected as dead and swept. It is deliberately NOT in\n the data directory, because the whole point is to see daemons whose data\n directory you do not know about, and deliberately not in `$TMPDIR`, which\n differs between a shell, a launchd job and a sandbox: two daemons with\n different values would miss each other.\n\n## Security\n\n**Read [SECURITY.md](SECURITY.md) before pointing agents you don't trust at one\ndaemon.** The trust boundary is the machine: every agent shares one coordination\nsecret, so Dibs protects you from other users and from the network, and\nraises (but cannot wall off) what one of your own agents can learn about\nanother. Run a second daemon for anything you do not trust.\n\n## Protocol versions\n\nDibs speaks **MCP 2026-07-28** (the stateless core) and the legacy\n**2025-11-25** path. You do not have to choose: the server answers whichever\nyour host offers.\n\nWorth knowing, because \"Dibs is 2026-07-28\" and \"my client connected with\n2025-11-25\" otherwise look like a contradiction: **no shipping host negotiates\n2026-07-28 by default.** In Codex it is an under-development feature flag, off\nby default.\n\n**Codex can be switched to it, and two things are required.** The feature\n`mcp_2026_07_28`, AND `CODEX_MCP_PROTOCOL_VERSION=2026-07-28` in that server's\nown `env` block in `~/.codex/config.toml`. The feature alone leaves the\nconnection on `2025-06-18`, which is why this section previously said turning it\non does not help: that measurement was correct and the conclusion drawn from it\nwas not, because the second condition had not been found. With both set, Codex\nsends `server/discover` carrying `2026-07-28` and Dibs answers it. Verified on\n2026-08-17 against Codex Desktop `0.148.0-alpha.9`, which then also calls\n`resources/list`, something it never does on the legacy path.\n\nYou do not have to do any of this. Dibs serves both paths and every tool behaves\nidentically on either. The reason to know is that a harness reaching the modern\npath is exercising the stateless contract, and if something differs there it is\nworth a bug report rather than a shrug.\n\nSurveyed by reading source, not announcements. Re-checked 2026-08-03 against\neach project's latest commit:\n\n| harness | speaks | why |\n|---|---|---|\n| Codex | 2025-11-25 (negotiates **2025-06-18**) | flag `mcp_2026_07_28` exists but is stage `UnderDevelopment`, default off. Its SDK supports 2025-11-25; what it actually sends in `initialize` is 2025-06-18, measured, see [plugins/codex](plugins/codex/) |\n| opencode | 2025-11-25 | bound by the TypeScript SDK (1.29.0) |\n| pi-mono | 2025-11-25 | bound by the TypeScript SDK (^1.25.2) |\n| Gemini CLI | 2025-06-18 | not stated |\n| Hermes | 2025-03-26 | pins `mcp==1.28.1`; no stateless-path code |\n\nThe reason is one level below the harnesses, and it is the useful part:\n\n- The **Python SDK 2.0.0** implements it. Its registry lists `2026-07-28` under\n `MODERN_PROTOCOL_VERSIONS`, separate from `HANDSHAKE_PROTOCOL_VERSIONS`.\n- The **TypeScript SDK 1.30.0**: the latest published release, and there is no\n beta space: still declares `LATEST_PROTOCOL_VERSION = '2025-11-25'`.\n\nSo every TypeScript harness is blocked on its SDK, not on its own roadmap, and\nno amount of configuration will move them until that ships. Codex is the only one\nthat exposes the flag at all, and as measured above, the flag ALONE does not\nchange what goes on the wire: it moves only when `CODEX_MCP_PROTOCOL_VERSION` is\nset on that server's own entry as well, which is what `dibs mcp-config` prints.\nThe rest of this list has no switch to set:\n\n```toml\n# ~/.codex/config.toml: exposed, but does not change the negotiated version\n[features]\nmcp_2026_07_28 = true\n```\n\n**If you are an agent reading this:** you cannot change your own harness, and you\nshould not edit your operator's config. Mention it once if it is relevant, then\ncarry on: nothing you call through Dibs depends on it.\n\n**If you are the operator:** there is no urgency. Dibs serves both paths, all 44\ntools behave identically on either, and deprecated features are guaranteed for at\nleast twelve months from the 2026-07-28 publication.\n\nThe practical consequence for Dibs is that the legacy path is **load-bearing,\nnot vestigial**, and removing it would break every current host.\n\n### What Dibs implements from the 2026-07-28 core\n\nVerified against a running daemon, not assumed:\n\n- **No handshake required.** `tools/list` and `tools/call` work with no\n `initialize` at all, which is the point of the stateless core.\n- **`server/discover`** for capabilities and instructions.\n- **Per-request protocol version and client identity**, by header or in `_meta`.\n- **The handshake/stateless split kept honest.** `initialize` negotiates only\n versions the handshake can carry; a client that offers `2026-07-28` there gets\n a counter-offer of `2025-11-25` rather than agreement, because that revision\n *retired* the handshake. The reference SDKs encode the same split\n (`HANDSHAKE_PROTOCOL_VERSIONS` vs `MODERN_PROTOCOL_VERSIONS`).\n- **Cacheable list results**: `ttlMs` and `cacheScope` on `server/discover`,\n `tools/list`, `resources/list` and `resources/read`. Dibs has more to re-fetch\n than most servers: 44 tools whose descriptions carry real corrective detail, re-fetched on every\n cold path once there is no session to hold them. Static results are hinted for\n an hour and marked `public`; the board is hinted for two seconds; **an agent's\n mailbox is `private`**, because `public` would let a shared gateway serve one\n agent's mail to another.\n- **Subscriptions** (SEP-2575) on both paths, so a client learns about a change\n immediately rather than waiting out a TTL.\n\n## Platform\n\n**macOS is what this is verified on.** Every test, every end-to-end suite and the\nCI gate run there, and that is the honest extent of the claim for v0.\n\nIt compiles for Linux and arm64 on every push: the cross-compile matrix is part\nof CI, and most of Dibs is ordinary portable Go with no reason to care. The\npart that does is `internal/liveness`, which works out whether a spawned agent is\nstill working by inspecting other processes. It shells out to `ps` using BSD\nspellings (`ps eww -p` for a process's environment, `ps -axo` for the table)\nwhose GNU equivalents differ. Nobody has run it on a GNU userland, so supervision\nis the piece most likely to need work there; coordination: agents, claims, mail,\nthe board: depends on none of it.\n\nWindows is not supported and is not being worked on.\n\nPatches for Linux are wanted, and [CONTRIBUTING.md](CONTRIBUTING.md) says what\nevidence they need. Filing an issue with what `ps eww -p ` prints on your\ndistribution is already useful.\n\n## Design\n\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) is the practical version: how the\npieces fit, where validation belongs, what must stay true, and the four bug\nclasses that keep recurring here. Read it before fixing something: the useful\nquestion is usually not \"what does this code do\" but \"what was it supposed to\ndo\".\n\nThe full design is in [SPEC.md](SPEC.md): v1.1, living: committed rather than\nfrozen, and hardened by five adversarial external review rounds. The short version: a single-writer event loop over a pure\nstate machine, command-sourced into an fsync'd hash-chained JSONL ledger; one\nmonotonic serial totally orders everything; replay is exact\n(`state == fold(ledger)`), which makes the whole system deterministically\nsimulatable: the test suite drives randomized op/time sequences and asserts\nreplay equivalence.\n\n## Engineering\n\nPinned Go toolchain (mise), golangci-lint v2 at **zero warnings**, `-race`\neverywhere, property-based replay tests, GoReleaser with reproducible builds plus\ncosign and SBOM. `task ci` runs the full local gate chain and is the same set CI\nruns.\n\nThe complexity ceilings in `.golangci.yml` carry named, reasoned exclusions\nrather than a blanket suppression: dispatch tables (the state machine's one\n`Apply` switch, the MCP tool switch, the CLI verb switch) score high because a\ndispatch table is nothing but branches, and splitting them would hide the\nexhaustiveness a reader needs to check. Every exclusion says which functions and\nwhy; `gocognit` still fires everywhere else, and it caught four functions in the\nspaces work that genuinely needed splitting.\n\nEnd-to-end suites run against a real daemon over real HTTP, and the browser\nsurfaces against real Chrome: `panel` (89), `web` (101), `space` (106), `guard`\n(36). All four are in `task ci`, alongside the sidecar self-test, the human-flow\nsuite and the alternate `dibdev` build.\n\nThe space suite measures its own join bar rather than hardcoding one, because\nthe scores it asserts on are computed from this repository's git history and\ntherefore move every time anybody commits. A fixed bar passes until it doesn't,\nand then fails for a reason no contributor can act on.\n\nBeyond that, `internal/mcp/e2e/fleet_scenario.py` runs a real fleet. Codex,\nopencode and pi sessions with real models, coordinating through Dibs while a\nhuman acts from the board at the same time (37 checks). It is deliberately *not*\nin `task ci`: it spends money on model calls and depends on provider\navailability. It exists because everything else drives Dibs through its own\nclient code, and that cannot answer whether a real harness, with a real model\nchoosing what to call, actually coordinates.\n\n## Contributing\n\nCriticism is welcome, including the kind that says the design is wrong: the\nreasoning behind most decisions is written down, so there is something specific\nto argue with. [CONTRIBUTING.md](CONTRIBUTING.md) says what a patch needs here,\n[SUPPORT.md](SUPPORT.md) says where to ask, and\n[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) is the short version of \"argue with the\nwork, not the person\".\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
"bytes": 51214,
"sha": "a27e7830cd26f26890af4f2474b108ec9fc0b604064e40d33034ee257be4b60c",
"repo_slug": "agenxy/dibs",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_agenxy_dibs_275ddbb7/readme"
}