dibs

<img src="docs/icon.svg" width="72" height="72" alt="">

# Dibs

[![CI](https://github.com/agenxy/dibs/actions/workflows/ci.yml/badge.svg)](https://github.com/agenxy/dibs/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/agenxy/dibs?sort=semver)](https://github.com/agenxy/dibs/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/agenxy/dibs.svg)](https://pkg.go.dev/github.com/agenxy/dibs)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**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, and it never decides what an agent should do next. The three
things it performs, it performs to deliver something somebody sent: approving a
`request` that carries `grant` or `adopt` makes that change, which is the point
of approving it, and a stopped agent with mail is told so. It is told in one of
two ways: by
`[wake.exec]` running a command from your own config, which is the one Dibs can
confirm happened, or over the session socket its own harness publishes, which
needs no configuration and is best effort. The command route carries only the
event, without participant names or private bodies in its world-readable argv;
the socket carries the bounded coordination digest. Neither carries an
imperative. Loaded app threads are not reopened; unloaded app threads open only
while the person is known away (ten minutes without input by default), never on
an unknown presence measurement. That second route is the receiver's
decision: a Claude Code session in bypassPermissions mode holds peer messages
for its human, and sends no receipt, so Dibs cannot tell held from delivered and
does not claim to. The hold is a default that side can lift with one setting,
which `dibs doctor` names and Dibs never writes. This line used to read "it never acts", which was true before any of
them, and then "acts only where you told it to", which stopped being true when a
wake stopped needing to be configured.

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.

![The Dibs board: five agents, what each is working on, and what is outstanding](docs/board.webp)

### 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:

```jsonc
// codex-1 → declare
{ "text": "Fixing session reconnect handling",
  "dirs": ["internal/session"], "refs": ["issue:1140"] }
```

```jsonc
{
  "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](docs/TUTORIAL.md).

### What else is on the board

Declaring work is one tool of 52. 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 asking the human a free-text question, as a native macOS dialog](docs/ask-human-text.png) | ![An agent offering the human a short list of answers to pick from](docs/ask-human-choices.png) |

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](REQUIREMENTS.md) has the measured incident
that defines the design.

---

**Contents**: [Install](#install) · [Tutorial](docs/TUTORIAL.md) ·
[For agents](#for-agents) · [What you get](#what-you-get) ·
[Catching duplicate work](#catching-duplicate-work) ·
[When a subagent stops working](#when-a-subagent-stops-working) ·
[Configuration](#configuration) · [Security](#security) ·
[Platform](#platform) · [Design](#design) · [Engineering](#engineering)

---

## Install

Listed in the official [MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.Agenxy/dibs`, which is where a harness or an agent looks up a
server it has not been told about:

```sh
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.

The macOS binaries are code-signed with a stable Agenxy identity, so macOS
sees one program across versions rather than a new one at every release: a
firewall allowance or a folder permission you grant once keeps applying. The
certificate is self-signed, which means Gatekeeper still asks the first time
and `spctl` still refuses; a Developer ID and notarization are what would
remove that, and Dibs does not have one yet. Signing is deterministic, so the
reproducibility above holds for anyone holding the same certificate, and
everyone else can reproduce the unsigned binaries and compare everything but
the signature.

### Homebrew (macOS)

```sh
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 TRIES to clear 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.

It is not treated as fatal, because `xattr` exits non-zero in ordinary cases
and failing the install over that would be worse than the warning it prevents.
So if macOS still says the developer cannot be verified, it did not work, and
`xattr -dr com.apple.quarantine "$(brew --prefix)/bin/dibd"