clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 45
colibri/docs/HEADROOM-SIDECAR.md
Sam & Claude 9891d06144 feat(rc): rename test agent and load provider env (Sam & Codex) 
Rename the local deterministic launch helper from colibri-smoke-agent to colibri-test-agent, update CLI/TUI/tests/docs, and teach the FreeBSD rc.d service to source /usr/local/etc/colibri/provider.env plus set a service PATH for local spawns.\n\nChecks: cargo fmt --check; ./scripts/check-format.sh; git diff --check; cargo check -p colibri-daemon -p colibri-client -p colibri-glasspane-tui; cargo check -p colibri-client --bins; cargo test -p colibri-client --test live_socket_check -- --nocapture.
2026-06-15 07:35:44 +02:00

2.1 KiB
Raw Blame History

Headroom sidecar for Colibri

Colibri can optionally ask a local headroom-ai sidecar to compress tool results before they are rendered through the session read path.

This is off by default. The daemon does not start or supervise Headroom; it only connects to an already-running Unix socket when explicitly enabled.

Configuration

COLIBRI_HEADROOM_ENABLED=1
COLIBRI_HEADROOM_SOCKET=/var/run/colibri/headroom.sock  # optional default

Start the sidecar with a Python environment that can import headroom:

python3 scripts/headroom-sidecar.py --socket /var/run/colibri/headroom.sock

Then start colibri-daemon with the environment above. Check connection state with colibri status; the status JSON includes:

{
  "headroom": {
    "enabled": true,
    "socket": "/var/run/colibri/headroom.sock",
    "connected": true
  }
}

Protocol

The daemon keeps one Unix-socket connection open and sends newline-delimited JSON requests. The sidecar must support multiple requests on that same accepted connection.

Request:

{"id":"tool-name","raw":"tool output text","role":"tool"}

Response:

{"id":"tool-name","compressed":"shorter text","tokens_before":100,"tokens_after":25}

If tokens_after >= tokens_before, Colibri keeps the original tool result. If the sidecar errors, disconnects, or times out, Colibri degrades to the original uncompressed content.

Current daemon timeout: 5 seconds per sidecar request.

Scope and caveats

  • Compression is opt-in and best-effort.
  • The sidecar currently affects session prompt/message rendering paths that pass a HeadroomSidecar; it is not a global daemon-wide replacement for existing cost-mode compaction.
  • Keep COLIBRI_HEADROOM_ENABLED=0 for ISO/live-USB defaults unless Headroom is staged and validated on the target image.
  • FreeBSD: upstream headroom-ai may require local packaging work because some ONNX/ORT-backed extras do not have FreeBSD prebuilt binaries. Use a known-good Python environment and validate scripts/headroom-sidecar.py directly before enabling the daemon flag.