Colibri Wiki
Colibri Wiki
Section titled “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, 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)
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](./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 |
| task-dispatch-flow | End-to-end task path: queued → claimed → spawn → register → dispatch → cost; why a task stalls |
| factory-model | How Colibri maps to the “factory model” architecture — harness, spectrum, conductor/orchestrator, economics |
| doctor | colibri doctor self-diagnosis (check battery) + colibri upgrade self-rebuild; cross-platform build split |
| 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 |
| deepseek-pricing | DeepSeek V4 per-token pricing — regular + peak-valley rates, UTC + Ljubljana timezone windows |
| glm-pricing | GLM-5 series per-token pricing (z.ai GLM Coding Plan) — GLM-5.2 flagship + GLM-5-Turbo; no peak-valley mechanism |
| tokenomics | The three cost levers — timing (valley), caching (prefix), budget (cost modes); the map that links the detail pages |
| 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 |
| ssh-bridge | SSH forced-command bridge call flow — USB→mother JSON-RPC transport, security model, troubleshooting |
| abbreviations | Expansions for acronyms and technical terms — add new ones as they appear |
| 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 | Eval harness + eval-driven model selection — Phases 1–3 shipped, Phase 4 (cloud eval) planned |
| 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 |
| pull-requests | PR workflow — branching, review, gates, merge conventions |
| quality-gates | ci-checks.sh as the pre-merge gate; why drift reached main before |
| verify-before-execute | Verify in the target context, surface failures — the xkbcomp borrowed-tool lesson, the chroot pattern, TUI/GUI application |
| contracts | Stable JSON schemas (run-manifest, runtime-inventory, provider-test), fixture 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) |
| tmux-safety | Why Colibri must prevent agents from killing the host tmux server — two-layer defense, skill, jail confinement |
| 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 |
| ts-legacy | Retired clawdie-ai TypeScript codebase — what it did, what survived into colibri/hermes-bsd, what was dropped |
| rust-glossary | Quick reference for Rust terms in the codebase: serde, Result/Option, Arc/Box, derive macros |
| ts-legacy | Retired clawdie-ai TypeScript codebase — what it did, what survived into colibri/hermes-bsd, what was dropped |
| bare-metal-freebsd | FreeBSD on physical hardware (HP ML350p) — iLO, IPMI, USB boot quirks, sensor monitoring gaps |
| updating-a-node | Base vs packages: freebsd-update on release hosts, pkg upgrade on pkgbase hosts, boot environments, why never to mix |
| forge-ops | The forge VPS (code.smilepowered.org): topology, two-artifact backup contract, one-major-hop upgrades, repo-archive trap, jail-restore project |
| llama-cpp | Local LLM inference with llama.cpp — install, model selection, DeepSeek distills, memory reality, hive integration |
| llama-cpp-benchmarks | Measured 8B vs 14B on valhala (Xeon E5-2620) — tok/s, prompt speed, coexistence, router tier recommendations |