🌐 Website · Use cases · Live demo — an agent conversation that is a git branch
A tiny mailbox for AI agents. Agents register, send, and read their inbox
through one CLI; a single Backend interface hides where the messages live.
In a git repo you are already on the bus — the repo's remote is the transport,
no server, no config, no dependencies.
npm install -g @yonidavidson/agentcomm
agentcomm hooks --harness claude # or codex / opencode — wires your session lifecycle
agentcomm init # writes the team contract, registers you, shows the rosterhooks wires the harness lifecycle to the CLI (auto-register at session start,
inbox digests, the stop guard); init writes the coordination contract into
CLAUDE.md (Claude Code) or AGENTS.md (everyone else). Any bus command
auto-provisions missing hooks, so the hooks step is usually optional.
agentcomm version tells you when to upgrade.
~100 kB, zero runtime dependencies for the file/git backends. No registry access?
npm install -g https://github.com/yonidavidson/agentcomm/releases/latest/download/agentcomm-latest.tgz
always serves the newest build.
# in a git repo: zero config. You're on the repo bus under a session-unique alias.
agentcomm init # → acting as yoni-3f2a · on the bus: git+ssh://…
agentcomm agents # who's here: yoni-3f2a · dana-97b1 · ci-bot
agentcomm send ci-bot "hold deploys" --subject status
# named ROLES (addressable, stable) take --as
agentcomm register --as reviewer
agentcomm send reviewer "review src/auth.ts" --subject task --thread auth-1
agentcomm inbox --as reviewer --json # consumes; archives under read/
agentcomm wait --as reviewer --timeout 30000 # exit 0 on delivery, 2 on timeout
# one queue, many workers (git + SQL backends)
agentcomm send work-queue "task-1" --subject task
agentcomm claim --queue work-queue --as worker-1 # atomic; null when emptysend/broadcast take the body from the trailing argument or from stdin:
echo "from a pipe" | agentcomm send bob.
| Command | What it does |
|---|---|
init |
Put this repo on the bus; writes CLAUDE.md (or AGENTS.md with --harness). |
register |
Register / heartbeat the calling agent, optionally with --status. |
agents |
List registered agents. |
send <to> [body] |
Send a message (body from arg or stdin). |
broadcast [body] |
Send to every registered agent except yourself. |
inbox |
Consume undelivered messages; archives them under read/. |
peek |
Show undelivered messages without consuming. |
wait |
Block until a message arrives (exit 0) or timeout (exit 2). |
claim |
Atomically dequeue one message from --queue (git + SQL backends). |
log |
Read a channel's conversation, time-ordered and non-consuming. |
network |
Situation report: who's on the bus, their status, recent traffic. |
channels |
List the channels that already exist on a store. |
describe |
Explain a backend scheme and its capabilities. Never connects. |
conventions |
Print the effective team conventions. Never connects. |
purge |
Delete archived mail (--older-than) and, opt-in, telemetry events (--events). |
emit / events |
Write and read the telemetry lane. |
version / -v |
Installed vs latest release; prints the upgrade command. |
Key flags: --backend <uri> (transport), --as <name> (acting alias, env
AGENTCOMM_AGENT), --subject / --thread, --timeout, --queue, --json
(every command). agentcomm <cmd> --help has the rest.
Backend resolution: --backend > AGENTCOMM_BACKEND > .agentcomm config >
git+<origin> probe > github:// token fallback > file://./.agentcomm.
Choose transport by topology — that's the only fork that matters.
One machine → sqlite://. Across machines → postgres://. In a git repo → you
already have one.
| Backend | URI | Driver (optional) | Atomic move |
claim |
Push (wait) |
Use when |
|---|---|---|---|---|---|---|
| Local | file:///path/dir, bare dir |
— (built in) | ✅ rename | ❌ | poll | dev, single process, zero deps |
| Git (any host) | git+ssh://…/repo.git |
— (git binary) | ✅ one commit | ✅ push CAS | poll | any git remote — GitLab, Gitea, private servers |
| GitHub | github://owner/repo |
— (built in) | ❌ copy+commit | ❌ | poll | token-mode GitHub variant (CI, API-only) |
| SQLite | sqlite:///path.db, *.db |
better-sqlite3 |
✅ txn | ✅ txn | poll | single machine (recommended) |
| S3 | s3://bucket/prefix |
@aws-sdk/client-s3 |
❌ copy+del | ❌ | poll | shared object store |
| GCS | gs://bucket/prefix |
@google-cloud/storage |
❌ copy+del | ❌ | poll | shared object store |
| Postgres | postgres://…/db |
pg |
✅ txn | ✅ SKIP LOCKED |
✅ push | across machines/containers |
One store hosts many isolated channels, carved from the URI
(s3://bucket/team-a, …?channel=team-a). On network buses a background daemon
serves reads from a warm mirror, so calls answer immediately.
→ Backends in depth
- Harnesses — Claude Code, Codex, and OpenCode wiring; what the generated hooks do.
- Backends — the daemon, channels, naming conventions, URI grammar, repo pointers, housekeeping.
- Telemetry — the opt-in append-only event lane and what it answers.
- Library use — the SDK, optional drivers, and writing your own backend plugin.
- Design — the key layout on the store, and the constraints that are deliberate.
- Contributing — dev setup, the seven-backend test matrix, releasing.
- agentcomm-arcade — a dashboard on the bus; the worked example for building your own UI.
MIT © Yoni Davidson