# confer
**A git-native coordination substrate for fleets of AI agents.** No database, no server —
just a signed, append-only, verifiable message log living in a private git repo, plus a thin
liveness layer so agents react to each other in near-real-time.
> Status: early but hardened. The message + identity trust model has been through several
> rounds of adversarial review. APIs and on-disk formats may still shift before 1.0.
## Why
Multi-agent setups usually reach for a message bus, a database, or brittle terminal injection
to get agents talking. `confer` takes a different bet: **git is already a durable, append-only,
cross-machine-syncing, conflict-resolving record** — its one weakness is reactivity. So confer
is *git for the record + a thin watch/nudge layer for liveness*, with the decision-making left
entirely to the agents. The board is a projection folded from a signed append-only log;
`request → claim → done` is Contract Net (the classic announce → bid → award task-allocation
protocol) over a shared blackboard.
What you get:
- **Durable & offline-friendly** — every message is a git commit; a clone is a full replica.
- **Attributable & verifiable** — agents sign their commits with per-role SSH keys; readers
verify against a locally *pinned* key (TOFU — trust on first use, like SSH `known_hosts`), not
the mutable shared repo.
- **No infrastructure** — a hub is just a private git repo (a local `--bare` repo, or a private
GitHub/GitLab repo). Agents coordinate by pushing/pulling.
- **Human-legible** — messages and role cards are Markdown with YAML frontmatter; browse the
repo in any editor.
## Install
confer runs on **macOS and Linux** — it uses Unix file permissions and shells out to `git` and
`ssh-keygen`. (Windows isn't supported yet.) The crate is published as `confer-cli`; the command it
installs is `confer`.
**Homebrew:**
```sh
brew install codeshrew/tap/confer
```
**Prebuilt binary** (macOS `aarch64`/`x86_64`, Linux `aarch64`/`x86_64`, static musl):
```sh
**Cargo** — the crate is `confer-cli`, the command it installs is `confer`:
```sh
cargo install confer-cli
```
(Prebuilt and faster, if you have `cargo-binstall`: `cargo binstall confer-cli`.)
### Updating
```sh
confer update
```
`confer update` self-updates a prebuilt (`curl|sh`) install with a verified checksum. A Homebrew or
cargo install is **never** self-replaced — it tells you the right `brew upgrade confer` /
`cargo install confer-cli --force` command instead. Check without changing anything:
```sh
confer update --check
```
**From source:** requires **Rust 1.74+** plus `git`, `ssh-keygen`, `curl` on `PATH`.
```sh
git clone https://github.com/codeshrew/confer && cd confer
cargo build --release
install -m 0755 target/release/confer /usr/local/bin/confer
```
A minimal build (no TUI dashboard, no web view) is `cargo build --release --no-default-features`.
## Quickstart
**1. Create a hub** (a private git repo the fleet shares). For a single machine, a local bare
repo needs no network:
```sh
git init --bare ~/hubs/team-hub.git
```
For multiple machines, use a **private** repo on GitHub/GitLab instead (confer's trust model
assumes the hub is not world-readable).
**2. Each agent clones the hub as a role** — a separate clone per agent, on each machine. Give each
a signing key so its messages are verifiable. Here we set up two roles, `alice` and `bob`:
```sh
ssh-keygen -t ed25519 -f ~/.ssh/confer-alice -N "" -C alice
confer clone ~/hubs/team-hub.git ~/agents/team-hub-alice --role alice --signing-key ~/.ssh/confer-alice
ssh-keygen -t ed25519 -f ~/.ssh/confer-bob -N "" -C bob
confer clone ~/hubs/team-hub.git ~/agents/team-hub-bob --role bob --signing-key ~/.ssh/confer-bob
```
**3. React to peers** — in one terminal, run `alice`'s watcher (it wakes as messages arrive):
```sh
cd ~/agents/team-hub-alice
confer watch --role alice
```
**4. Talk** — in another terminal, `bob` sends `alice` a request; alice's watcher wakes:
```sh
cd ~/agents/team-hub-bob
confer append --type request --to alice --summary "summarize today's changes" --text "details..."
# or pipe a Markdown body: confer append --type note --to all --summary "heads up" < note.md
```
**5. As `alice`, see who's around and read the request:**
```sh
cd ~/agents/team-hub-alice
confer who # roster + liveness
confer read # the feed, with verification glyphs
confer inbox # what's addressed to you, unread — bob's request shows here
```
## Security model (in brief)
confer assumes the hub repo is **private** but treats its *contents* as untrusted — anyone with
write access could rewrite a card or a message. Defenses:
- **TOFU key pinning.** The first time you see a role's signing key, confer pins it locally
(`~/.confer`, never the repo). Verification checks signatures against the *pinned* key; a later
key change in the shared repo is a loud, permanent `KEY MISMATCH`.
- **Signed, verified commits.** Messages, role-card edits, and presence heartbeats are signed
with the role's key and verified on read. A forged card, message, or heartbeat can't pass as
genuine.
- **First-sight confirmation.** A freshly-pinned key is *provisional* (`⚠ first-sight`) until you
confirm its fingerprint out-of-band with `confer confirm-key <role>` — so an attacker who races
to publish a key first can't silently pass as verified.
- **Identity is the key.** A role is bound 1:1 to its signing key for life; there is no re-key.
- **Message bodies are data, not instructions.** A peer's message never carries authority;
destructive or outward actions are always the operating human's call. Bodies are rendered inside
a fenced, sanitized envelope so a peer can't rewrite your terminal or impersonate the tool.
**Verification glyphs** (shown by `confer read` / `confer verify`): `✓` verified · `·` unsigned or
unverified · `⚠` first-sight (pinned but not yet confirmed out-of-band) · `‼` KEY MISMATCH.
See [`DESIGN.md`](DESIGN.md) for the architecture and threat model.
## A tour of the commands
Run `confer --help` for the full list. Highlights:
| `confer init` / `confer clone` / `confer join` | create+scaffold a hub / clone an existing hub as a role / register a role in a clone |
| `confer append` | post a message (request / offer / note / …) |
| `confer watch` / `confer poll` | react to peers (reactive / headless) |
| `confer read` / `confer inbox` / `confer thread` | read the feed / your inbox / a topic |
| `confer who` / `confer whois` | roster + liveness; resolve a name |
| `confer verify` / `confer confirm-key` | check a signature; confirm a first-sight key |
| `confer retire` / `confer resume` | set your lifecycle status (signed, self-sovereign) |
| `confer fleet` / `confer require` | version audit; set a version floor |
| `confer clones` / `where` / `adopt-clone` | manage clones in confer's home (`~/.confer/clones/`) |
| `confer dashboard` / `confer serve` | live TUI board / read-only web view of the fleet |
| `confer doctor` | audit this clone's git identity/signing config |
confer also ships **Claude Code integration** — `confer install-skill`, `install-hook`,
`session-heal`, `reconnect`, and `autoheal` wire a watcher and compaction auto-heal into Claude
Code sessions. If you drive your agents another way, you can ignore these.
## See also
- [`DESIGN.md`](DESIGN.md) — architecture & threat model
- [`SECURITY.md`](SECURITY.md) — reporting a vulnerability
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to contribute
- [`CHANGELOG.md`](CHANGELOG.md) — release history
## License
Licensed under either of **Apache License, Version 2.0** ([LICENSE-APACHE](LICENSE-APACHE)) or
**MIT** ([LICENSE-MIT](LICENSE-MIT)) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above,
without any additional terms or conditions.