colibri/README.md

# Colibri

The Clawdie control plane core — a small, cross-platform (FreeBSD + Linux) Rust
daemon that unifies coordination (task board, agent registry, skills catalog)
with cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering).

**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state.

FreeBSD build lane handoff: `docs/FREEBSD-BUILD-LANE-HANDOFF.md`.
ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`.
Clawdie Studio/Zed proposal: `docs/CLAWDIE-STUDIO-PROPOSAL.md`.
External MCP host prototype: `docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`.
Optional Headroom compression sidecar: `docs/HEADROOM-SIDECAR.md`.

## Workspace

| Crate                   | Role                                                                    |
| ----------------------- | ----------------------------------------------------------------------- |
| `colibri` (root)        | Workspace root + probe binaries (colibri-probe, runtime-inventory)      |
| `colibri-mcp`           | MCP bridge for editor integration (Zed, Claude Code) via stdio JSON-RPC |
| `colibri-contracts`     | JSON schema contracts (golden tests)                                    |
| `colibri-deepseek`      | DeepSeek cache-hit probe, prefix metering                               |
| `colibri-runtime`       | Host status ingestion, runtime inventory                                |
| `colibri-glasspane`     | Agent 5-state machine (zot/pi JSONL events → state)                     |
| `colibri-daemon`        | Always-on Unix socket server, session lifecycle                         |
| `colibri-client`        | Typed Unix-socket client + operator CLI                                 |
| `colibri-glasspane-tui` | ratatui live dashboard (FreeBSD-native)                                 |
| `colibri-store`         | Embedded SQLite coordination (task board, agents, skills)               |
| `colibri-skills`        | Skills catalog crate                                                    |
| `clawdie`               | Host installer/deployer: ZFS layout + `clawdie` service (FreeBSD/Linux) |

## Build

```sh
cargo build --release
```

## Test

```sh
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```

## Architecture

```
colibri-daemon (always-on Unix socket server)
  ├── glasspane      — agent state machine (zot/pi JSONL → idle/working/blocked/done)
  ├── store          — SQLite coordination (tasks, agents, skills)
  ├── socket         — newline-JSON socket API
  ├── session        — append-only JSONL sessions, 3-region prompt assembly
  └── spawner        — agent subprocess management (retry/backoff, FreeBSD jail confinement)

colibri-client       — CLI tools (colibri, colibri-test-agent)
colibri-glasspane-tui— ratatui dashboard
```

## Probe binaries

```sh
# DeepSeek cache probe (needs DEEPSEEK_API_KEY)
cargo run --release --bin colibri-probe

# Runtime inventory manifest
cargo run --release --bin colibri-runtime-inventory
```

## FreeBSD

Target `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid
`openssl-sys` linking. Default DB path: `/var/db/colibri/colibri.sqlite`.