7.2 KiB
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
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, rename to 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)
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](./page.md)) — 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
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.
Pages
| 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 |
| operator-attention | The derived "needs the operator" view: attention predicate, TUI bar/jump/filter, edge-triggered terminal alerts |
| 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 |
| hive-routing | Hive member identity (machine UUID), capability matrix + local LLM probes, cost-aware task routing |
| hive-pane | Glasspane for the hive — multi-node cost observability, A2A discovery, and operator board |
| cost-dashboard | Mother-side cost observability — human gallery + JSON, screenshot proof linked from cost rows |
| a2a-complexity-audit | A2A code complexity impact — 6-protocol surface audit, when A2A pays off |
| model-selection-and-eval | T2.x design: model selection (tier arbitrage) + evaluation harness (task success measurement) |
| naming-decisions | Ledger of harness-neutral / architecture renames — shipped and in-flight |
| daemon-not-demon | Why we say daemon (helper spirit) not demon (bad spirit) — English + Slovenian |
| 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-test), 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 |
| terminal | Terminal capability decision (Kitty, extended-key reporting, tmux passthrough, SSH terminfo) |
| runtime-inventory | Host runtime inventory + watchdog status reader; additive, read-only integrations |
| skills-catalog | Read-only runtime consumer for reviewed 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 |