Colibri Wiki
A knowledge base for Colibri’s decisions and architecture — based on Andrej Karpathy’s LLM Wiki pattern.
Every major subsystem has a page recording why it was built the way it
was — the rationale the code can’t express. Implementation docs in docs/
cover the how; these pages cover the why.
Why this exists
Section titled “Why this exists”Stale decisions accumulate faster than anyone hand-audits them: a rename that
was only half-applied, a doc that still describes the old design, a default
left over from a superseded choice. Several recent passes were spent finding
exactly that (pi → zot, usb_nodes → hive_nodes, fake → sample). This wiki
makes the bookkeeping near-zero-cost: one place that records what was decided,
links to where it lives in code, and can be linted for drift.
Conventions (the schema)
Section titled “Conventions (the schema)”These rules keep the wiki a maintainable artifact, not a second source of truth:
- Code is the source of truth. Pages describe decisions and where they live; they link to code/docs rather than re-explaining implementation. When a decision ships, slim its page to “how it works + link.”
- Link, don’t duplicate. Reference code as
path/to/file.rs:lineand other wiki pages with relative links ([label](/wiki/page/)) — Forge-clickable, the equivalent of Obsidian[[wikilinks]]adapted to a repo. - One decision per page where practical; cross-link liberally.
- Flag, don’t silently overwrite. When new code contradicts a page, note the contradiction (and resolve it) rather than quietly editing history.
- Lint, don’t trust. A page is a claim to be checked against code, not a guarantee.
Lint workflow
Section titled “Lint workflow”The wiki-lint script checks every page against the
current code: dangling references, resurrected old names (from the naming
ledger), and orphan pages. It runs as part of ci-checks.sh --strict and is
gated by the pre-push hook — a drift failure blocks a push, same as a clippy
warning.
| Page | What it covers |
|---|---|
| agent-harness | The zot (agent) + Colibri (control plane) split; autospawn + RPC driver |
| agent-events-reference | Per-harness zot event reference, Glasspane mappings, and verified transcript fields |
| cost-model | Byte-stable prefixes, cache-hit metering, auto-escalation, T14 compaction |
| glasspane | Agent state machine, JSONL streaming, AgentRuntime taxonomy, snapshot API |
| headroom-sidecar | Optional tool-result compression sidecar and its Unix-socket protocol |
| jail-confinement | Persistent vs ephemeral jails, priv-mode policy, reuse of spawner confinement for MCP servers |
| mother-hive | Mother MCP architecture — forced-command SSH, single-home-in-colibri, peer auth, key-on-seed |
| naming-decisions | Ledger of harness-neutral / architecture renames — shipped and in-flight |
| layered-soul | How Colibri consumes the layered-soul reviewed-context repo today vs planned |
| task-board | Capability match scoring, cron scheduling, intake drain, SQLite backing |
| quality-gates | ci-checks.sh as the pre-merge gate; why drift reached main before |
| contracts | Stable JSON schemas (run-manifest, runtime-inventory, provider-smoke), golden tests |
| store-schema | SQLite coordination schema and migration discipline |
| external-mcp | MCP bridge for editors + external stdio MCP host; read/write/external-call gates |
| operator-cli | The colibri CLI as a thin typed Unix-socket client over the daemon API |
| tui | Terminal dashboard client (colibri-tui) vs the colibri-glasspane state machine |
| runtime-inventory | Host runtime inventory + watchdog status reader; additive, read-only integrations |
| skills-catalog | Read-only runtime consumer for reviewed Clawdie-AI skill artifacts |
| vault-provision | Vaultwarden-driven env-file provisioning into jails after agent spawn |
| deployment | Host installer (clawdie): ZFS layout, rc.d/systemd service, dry-run safety |