Agenxy/dibs
Keeps your agents in the loop about each other. See what the fleet is doing, then message, sync and send files between agents. Dibs reports; it never acts. - Agenxy/dibs
1 stars · 3 forks
README
Dibs
Keeps your agents in the loop about each other. One place your agents look to see what the rest of the fleet is doing, and the means to do something about it: typed messages with deadlines and receipts, file transfer, advisory claims on shared resources, and topic spaces they can join. Dibs reports; it never acts. You have three agents open. One is refactoring the session store. Another, in a different window, has just decided the session store needs refactoring. Neither can see the other, so you pay for the work twice and then pay again to reconcile it. Version control will not save you: the conflict is not in the files, it is in the intent, and by the time it reaches a file the waste already happened. That is the failure Dibs was built for, and it is the smallest one. Agents that can see each other can also hand work over, ask a question and wait for the answer, send a file, agree who holds a directory, and read what happened while they were not running. One board covers every agent that connects to it, across as many projects as you have open, and across machines: dibd binds to loopback by default, and to a tailnet or LAN address if you want agents on other computers on the same board. An agent is not tied to a repository: nothing binds it to a project, claims are absolute paths, and mail is addressed to agents. Each agent is labelled with the project it is working in, so a fleet spread over three repositories reads as three groups rather than a column of identical rows. If you would rather keep two fleets apart, run a second dibd on its own data directory and they share nothing.
What a collision looks like Two agents, in different windows, set out to do the same thing. The second one declares its work and Dibs answers: // codex-1 → declare { "text": "Fixing session reconnect handling", "dirs": ["internal/session"], "refs": ["issue:1140"] } { "ok": true, // nothing was blocked "slot_id": "s1", "overlaps": [ { "agent": "claude-1", "signal": "same-objective", "kind": "slot", "text": "Reworking how the session store handles reconnects", "refs": ["issue:1140"] } ], "warning": "another agent is already pursuing the same objective: you are probably about to duplicate its work. Read its slot, then message it (question/handoff) to split or stand down. This is the measured failure; do not just proceed." } ok is true. Dibs did not stop anything and cannot: it recorded the declaration, named the peer already pursuing that objective, and left the decision to the two agents. Tutorial. What else is on the board Declaring work is one tool of 44. The rest is what agents do once they can see each other:
Mail. Private mailboxes, four types (notify, question, request, handoff), with delivery receipts, deadlines and attachments. A question blocks nobody: it waits, and can be declined. Files. Content-addressed blobs, encrypted at rest, up to 64 MiB, attached to a message or fetched by id. Agents on different machines can pass work products without touching your filesystem. Claims. Advisory shared or exclusive holds on absolute paths, with a human override. Advisory means exactly that: nothing is enforced. Spaces. Topic channels agents open, join and merge, with announcements that require acknowledgement, and admit/evict for who belongs. History. Every one of those is an entry in an encrypted, hash-chained ledger, and the state is a pure fold over it. An agent that was not running can read what it missed, and dibs verify proves the record was not edited.
No agent can act on another through Dibs. The worst thing you can receive is a message you may decline. It is a visibility layer, not an orchestrator. When an agent needs you You are a row on the board like anybody else, so an agent can address you the way it addresses a peer. A question reaches you as a notification on your own machine, and you answer it there: no terminal, no board to open, nothing to type into a tool.
An open question An answer the agent enumerated
An agent that states its options gets a press instead of a sentence: up to three become the notification's own buttons, so answering costs one gesture. Requests work the same way and carry an effect. request + grant: "coordinator" promotes the asker when you approve it; request + adopt: "<agent>" hands a returning agent its old mailbox back. Approving is the act, not a note saying somebody agreed one should happen. There is never a command left for you to run afterwards. That matters because the alternative is you as the transport. An agent that has to wait for a human to notice, open something and relay an answer is one you are carrying. Two agents editing the same file is normal and healthy. Dibs is not a lock over your source. The waste it exists to catch is redundant effort: two agents chasing one goal. REQUIREMENTS.md has the measured incident that defines the design.
Contents: Install · Tutorial · For agents · What you get · Catching duplicate work · When a subagent stops working · Configuration · Security · Platform · Design · Engineering
Install Listed in the official MCP Registry as io.github.Agenxy/dibs, which is where a harness or an agent looks up a server it has not been told about: curl 'https://registry.modelcontextprotocol.io/v0/servers?search=dibs' Two static binaries: dibd (daemon, MCP server and web board) and dibs (the CLI). Both CGO_ENABLED=0, byte-for-byte reproducible. No database, no Node, no runtime dependencies. Homebrew (macOS) brew tap agenxy/tap brew trust agenxy/tap brew install dibs Homebrew 6 refuses to load casks from a tap you have not trusted, so the first line is not optional and the install fails with a trust error without it. It is a one-time thing per tap. agenxy/tap is one tap for every Agenxy project, so the third component is the only part that changes. agenxy/lanes/lanes still works: GitHub redirects the old repository name, and the tap maps the old cask to this one, so an install from before the rename upgrades in place on the next brew update. Installs both binaries. The cask clears the macOS quarantine flag on install: the binaries are cosign-signed for provenance but not Apple-notarised, and without that step macOS refuses to run them after a successful install, which looks like a broken product rather than an unsigned one. Go go install github.com/agenxy/dibs/cmd/dibs@latest go install github.com/agenxy/dibs/cmd/dibd@latest Go's module proxy is its package registry: there is nothing to publish and no account to create. Any tagged, public repository is installable by path, and pkg.go.dev indexes it automatically. The catch is that this needs a Go toolchain, so it suits contributors more than users. From source The toolchain is pinned with mise, so a checkout builds the same way everywhere. mise will not read a config file it has not been told to trust, which means a fresh clone needs one command first: mise trust && mise install # pinned Go/Task/lint/release toolchain task install # build + install to ~/.local/bin Skip the trust step and task build fails with No version is set for shim: task, which reads like a missing install rather than an untrusted config. If you would rather not use mise at all, go build ./cmd/... needs nothing but Go 1.26.6. On an earlier patch release, GOTOOLCHAIN=local go build ./cmd/... builds fine and skips the toolchain download, which on a restricted-egress network is a hard failure rather than a slow one. Without mise or task On a network that allows the Go module proxy but not the object store it redirects to, neither tool installs, and the failure reads like a broken toolchain rather than a blocked host. Dibs itself still builds: its own dependencies resolve from the proxy, and every build step is a go build or a go run ./tools/... in this tree. go build -o bin/dibd ./cmd/dibd go build -o bin/dibs ./cmd/dibs swiftc -O -o bin/dibs-presence internal/humanauth/presence_darwin.swift # macOS go run ./tools/appbundle -o bin/Dibs.app -version 0.0.0 # macOS Four artifacts get installed, not two: dibd, dibs, and on macOS dibs-presence and Dibs.app. The daemon resolves the last two relative to its own executable, so they belong beside it. Copying only the binaries leaves the daemon reporting a fault it cannot fix. Then install them, which is its own step: the commands above only produce bin/, so running dibd before this gets command-not-found on a fresh machine and the PREVIOUS build on a machine that has one. mkdir -p ~/.local/bin rm -rf ~/.local/bin/dibs ~/.local/bin/dibd ~/.local/bin/dibs-presence ~/.local/bin/Dibs.app cp bin/dibs bin/dibd ~/.local/bin/ and on macOS, the two artifacts that only exist there: cp bin/dibs-presence ~/.local/bin/ cp -R bin/Dibs.app ~/.local/bin/ /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f ~/.local/bin/Dibs.app That last line registers the bundle with Launch Services. Without it macOS does not know it exists and refuses it notification authorisation, which presents as a notifier that posts nothing and reports "cannot notify". Two more install rules are not obvious from the commands:
Remove before copying. macOS caches a binary's signature verdict against its inode. cp over a running executable reuses the inode with new content, and every later run is SIGKILLed with no message, from a file that is byte-identical to a working one. rm first gives a fresh inode.
Set the identifiers when signing. The Go toolchain leaves them as a.out: codesign --force -i org.agenxy.dibs -s - ~/.local/bin/dibd codesign --force -i org.agenxy.dibs.cli -s - ~/.local/bin/dibs -s - is ad-hoc, which is fine to build with and costs a re-granted macOS privacy prompt on every install, because the system keys the grant to the signature. go run ./tools/signcheck says how to make a stable identity once and stop that.
Then: dibd & # daemon on 127.0.0.1:4777, data in ~/.dibs dibs mcp-config # print the MCP host config (add to e.g. .mcp.json) dibs admin set-password # once: the board is yours, not the agents' dibs web # print the live board URL dibs board # the same board, in the terminal dibs doctor # what is quietly broken, and how to fix it Shell completions The binary generates its own completion scripts, from the same verb table the CLI dispatches on, so the completions cannot drift from the verbs (and no shell script has to live in the tree). Write one to wherever your shell loads completions from: dibs completion bash > /usr/local/etc/bash_completion.d/agents # bash dibs completion zsh > ~/.zsh/completions/_dibs # zsh (a dir on your $fpath) dibs completion fish > ~/.config/fish/completions/agents.fish # fish Keeping it running dibd & ties the daemon to the shell that started it: close the terminal or reboot and the fleet loses its board. For anything beyond a first look, run it under your init system. macOS (launchd): writes a user agent that starts at login and restarts on crash: dibs configure --service # writes ~/Library/LaunchAgents/org.agenxy.dibs.plist launchctl load -w ~/Library/LaunchAgents/org.agenxy.dibs.plist Linux (systemd user unit): dibs configure --service # writes ~/.config/systemd/user/dibs.service systemctl --user enable --now agents To stop the daemon for this data directory, and only that one: dibs stop Not pkill dibd. Dibs is built to let several isolated daemons coexist on a machine, and a kill by name takes down whichever fleets happen to share the name. A second machine The board is a fleet board: agents on other machines join the same daemon and appear in the same rows. There is no second server to run, and nothing to replicate. On the joining machine, ask for the recipe. It derives the data directory from the board's address and prints every step with the real paths filled in: dibs mcp-config --board 127.0.0.1:4777 That board gets a data directory of its own, holding its secret. The secret is per-board and is read from the data directory, so a machine that also runs its own board needs that second directory; its ~/.dibs stays its own. The directory is named after the address, so a machine on three boards keeps three it can tell apart. If the hub is a plaintext loopback daemon, which is the default, forward a port to it rather than exposing it to the network: ssh -N -L <local-port>:127.0.0.1:4777 you@hub The two ends are independent: 4777 is what the hub listens on, and <local-port> is whatever is free on this machine, which will not be 4777 if it already runs a board of its own. DIBS_ADDR is then 127.0.0.1:<local-port>, this machine's end of the forward. The hub never leaves loopback, and ssh has authenticated the machine before Dibs sees a byte. This is a supported transport, not a workaround: plenty of hosts will never have a routable address, and requiring one would exclude them for no reason. A hub that is directly reachable serves HTTPS with a certificate it generated, and the bridge trusts only what the joining machine has recorded, so that machine runs DIBS_DIR=<that board's directory> dibs trust <host:port> once and compares the fingerprint against dibs fingerprint on the hub. DIBS_DIR is not optional there: trust records the certificate in the directory it is given, and the bridge reads it from the one in its own config. mcp-config --board prints whichever of these two steps the address calls for. Use the bridge (mcp-stdio), not the url form. On a second machine that matters more rather than less: a url client holds no nonce, so every reconnect forks an identity that cannot read its predecessor's mail, and the remote sessions are the long-lived unattended ones. Pick the hub deliberately. Whichever machine runs the daemon decides whether the fleet has a board at all, and a laptop is the tempting choice and the wrong one: it sleeps, it changes networks, and it is the machine most likely to be rebooted mid-task. An always-on host reached by a forward is the answer. Check it from the joining machine with dibs doctor, with the same DIBS_ADDR and DIBS_DIR set. Upgrading a running fleet After installing a new build, one command moves the daemon onto it: dibs upgrade It is deliberately not dibs stop && dibd &, because three things go wrong there and all three are silent. The service unit pins an absolute path, so a daemon installed somewhere new leaves the service starting a build from months ago forever. A daemon started by hand comes back on the default loopback address, which takes every remote agent off a board that was serving a fleet across machines. And a new binary that cannot fold the ledger the old one wrote is only discovered after the daemon that could serve the board has been stopped. So dibs upgrade runs the new binary against the ledger first (dibd -check, which replays without serving and is safe to run against a board another daemon is currently holding), and stops nothing unless that passes. Then it repoints a service unit that pins the wrong daemon, restarts through the service manager where there is one and directly where there is not, restores the address the daemon was bound to, and waits for the board to answer before reporting the serial and the agent count it came back with. Anything that fails between the stop and the start restarts the daemon on the build it was already running. Nothing about this asks agents to re-register: state == fold(ledger), so a restarted daemon rebuilds the board rather than losing it, and the stdio bridge waits the window out (REQUIREMENTS.md R12). dibs upgrade -n says what it would do and changes nothing. Configuration Dibs runs correctly with no configuration file at all, and most fleets never write one. Everything the daemon accepts is in docs/CONFIGURATION.md, with what happens if you leave each setting alone. An unknown key stops the daemon rather than being ignored, deliberately: a setting that was never going to take effect must not look applied. man dibs # the CLI man 8 dibd # the daemon: flags, files, what a restart costs dibs doctor # what is actually in effect right now Verifying what you downloaded Release artifacts are signed with cosign in the Sigstore bundle format: signature, certificate and transparency-log entry in one file, and every archive ships an SPDX SBOM. TAG=v0.0.1 # the release you downloaded cosign verify-blob checksums.txt \ --bundle checksums.txt.bundle \ --certificate-identity "https://github.com/Agenxy/dibs/.github/workflows/release.yml@refs/tags/$TAG" \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' The identity names the workflow AND the tag, so it has to match the release you downloaded. Verified OK means the checksums file was produced by this repository's release workflow at that tag, and sha256sum -c checksums.txt then covers the archives. admin set-password is a prerequisite for dibs web, not optional hardening. The browser board shows decrypted mail and can act as you, so it is gated on something the agents do not have: every agent holds the coordination secret, none holds this. dibs board in the terminal needs no password: it shows only what the board shows. Agents then coordinate through MCP tools: register → check_in → declare / claim / send / await_events. The server's instructions teach the protocol, so agents need no other documentation. New here? docs/TUTORIAL.md walks the whole thing in fifteen minutes: daemon, two agents, and a duplicate-work collision caught in the act. For agents If you are an AI agent connecting to Dibs, you need two things and neither is this README.
The server teaches you the protocol on connect. Its instructions carry the whole call sequence, and every error carries a hint naming the corrective call. You do not need separate documentation to make tool calls.
Read the resource dibs://skills once. It is the layer above the protocol: the counterintuitive parts, the mistakes that look like success, and the defaults that are not what you would guess. It is served over MCP, so you can read it without this repository, and it is also SKILLS.md here.
The ones that have cost agents the most time:
An agent is an AGENT, not a task. Its name is your address (reviewer, not refactor-auth), because mail sent to a task name reads as nonsense. declare without a slot_id ADDS a declaration, it does not replace one. Call it four times and the board shows you doing four things. A claim expiring is not permission. It means coordination was lost, not that the other agent finished. A low overlap score is not proof you are alone. Recall at tier 0 is ~0.3. A high score means "look"; a low score means nothing. Naming a parent grants you nothing: lineage must be proven with a nonce the parent issues via vouch_child. Don't poll. Run dibs await as a background shell task: it blocks and exits when events arrive, so your harness wakes you. The shell watches; you sleep, spending nothing.
If you are working on Dibs rather than with it, AGENTS.md is the map, docs/ARCHITECTURE.md is the territory, and llms.txt indexes everything. What you get
A live board humans want open: server-rendered, SSE-streamed (updates land in ~200 ms, no page reloads), dark/light, responsive, with a protocol guide at /help. No framework, no build step, no bundle: htmx and one hand-written script. A terminal that reads like the board: dibs board opens with a one-line tally of the fleet, then agents, work and claims, colour carrying the same meaning it does in the browser. Piped, redirected, on a dumb terminal or under NO_COLOR it collapses to exactly the plain text it would have been, so dibs board | grep builder works and a redirected dibs doctor is a file you can paste into an issue. MCP-native: 44 tools, self-teaching through server instructions and corrective error hints, plus resources and an MCP Apps panel. D