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:line and 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

Skripta wiki-lint preverja vsako stran proti trenutni kodi: neobstoječe reference, oživljena stara imena (iz evidence preimenovanj), in osamljene strani. Teče kot del ci-checks.sh --strict in je zaščitena s pre-push hookom — napaka pri odstopanju blokira push, enako kot clippy opozorilo.

Pages

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/syst) 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
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