colibri/README.md

Colibri

The Clawdie control plane — a cross-platform (FreeBSD + Linux) Rust daemon that coordinates agent task execution, tracks cost, and observes agent state. Deploys as the Clawdie service on bare FreeBSD hardware (ZFS, PostgreSQL, bhyve VMs, Bastille jails) or as a standalone daemon on Linux.

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 (fixture 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, task dispatch, session lifecycle
colibri-client	Typed Unix-socket client + operator CLI
colibri-glasspane-tui	ratatui live dashboard (FreeBSD-native)
colibri-ledger	Embedded SQLite coordination (task board, agents, cost tracking)
colibri-skills	Skills catalog crate
clawdie	Host installer/deployer: ZFS layout + clawdie service (FreeBSD/Linux)

Quick start

cargo build --release
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Default DB path: /var/db/colibri/colibri.sqlite.

Architecture

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

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

Probe binaries

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

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

Learn more

The wiki records design decisions and architecture docs. Key pages:

Page	What it covers
agent-harness	Agent lifecycle, zot/pi integration, RPC dispatch
glasspane	5-state machine, attention system, TUI
hive-routing	Fleet routing, capability matrix, node registration
cost-dashboard	Per-task cost tracking, proof_text, live dashboard
model-selection-and-eval	T2.x eval harness + model selection design
mother-hive	Mother node coordination (PostgreSQL + MCP over SSH)
pull-requests	Branch naming, commit format, review workflow
quality-gates	CI pipeline, fmt/clippy/test/wiki-lint gates

FreeBSD build: x86_64-unknown-freebsd (Rust Tier-2). TLS uses rustls for static linking (no openssl-sys dependency).