colibri/docs/CLAWDIE-STUDIO-PROPOSAL.md

Clawdie Studio — Integrated Editor + Control Plane Proposal

Date: 27.maj.2026 Status: PROPOSAL — for discussion, not committed to roadmap yet Author: Sam (operator), structured by Claude (domedog)

The Idea

A single "Clawdie Studio" experience where the operator can edit docs/code while simultaneously running and observing Colibri — agents, tasks, scheduler, sessions — all from one visual surface.

The user should not need to switch between a terminal (colibri CLI / TUI) and an editor (Zed) to operate the control plane. The studio ties them together.

Why Rust Makes This Feasible

Colibri is already Rust. Zed is already Rust. The shared language removes the FFI/integration friction that would exist with a TypeScript control plane. Specifically:

• Unix socket protocol is already JSON-over-newline — any Rust client can consume it trivially.
• colibri-client crate is a typed Rust client — a Zed extension or MCP bridge can depend on it directly.
• colibri-harness (TUI) already proves "visual dashboard over socket" works end-to-end.
• colibri CLI already covers task/agent/status operations.

The gap between "what we have" and "Clawdie Studio" is smaller than it looks because the socket API is the integration point.

Architecture: Decoupled Components, Unified Experience

clawdie-studio (the user experience)
  │
  ├── colibri-daemon     rc.d service, always-on, headless-safe
  ├── colibri-mcp        MCP bridge for Zed assistant integration
  ├── colibri            CLI operator tool
  ├── colibri-harness    TUI fallback / SSH dashboard
  └── Zed                editor + task panel via extension

The user sees one product. The system remains robust: if Zed crashes or isn't installed, colibri-daemon still runs agents and processes tasks.

Integration Levels

Level 1 — Near-term: "One App Experience" (not one binary)

Use Zed as the visual shell. Colibri stays the rc.d service.

Zed
  ├── edit docs/code
  ├── Colibri task panel (sidebar extension)
  ├── terminal: colibri status / list-tasks / intake-task
  └── talks to /var/run/colibri/colibri.sock

colibri-daemon
  └── boot service, owns agents/scheduler/SQLite

This gives the all-in-one feel without making the editor responsible for supervision. The daemon runs even when the editor is closed.

Implementation: start with Zed tasks/terminal commands and MCP. A native Zed sidebar can come later, but the exact extension API/socket constraints must be verified on the target Zed build before assuming an extension can link colibri-client or open the Unix socket directly.

Level 2 — Mid-term: MCP Integration (highest leverage)

Build colibri-mcp — an MCP (Model Context Protocol) server that wraps colibri-client.

Zed Assistant → MCP protocol → colibri-mcp → colibri-client → Unix socket → colibri-daemon

Zed already supports MCP natively. An MCP server is just a stdin/stdout JSON-RPC process — trivial to implement in Rust.

Capabilities this unlocks:

• Check agent state from the assistant
• Create intake tasks from current file/docs context
• Query queued tasks and blocked panes
• Summarize active sessions
• Trigger smoke tests or scheduler runs
• Ask "what's the system doing right now?" and get a real answer

Why highest leverage:

• No forking, no vendoring, no embedding
• Reuses existing colibri-client crate directly
• Works with any MCP-capable editor (Zed, Cursor, Windsurf, etc.)
• The assistant can act on Colibri state, not just display it

Level 3 — Long-term: True Single Binary

Technically possible but not recommended as the ISO target.

Options:

• Fork/vendor Zed and embed Colibri service code
• Build a custom Rust GUI around Colibri instead of Zed
• Build a launcher binary that starts/checks Colibri and opens Zed

Why not now: A true Zed+Colibri single binary would carry significant maintenance burden and blur the critical boundary — Colibri must run headless at boot even when no editor is open.

Product Shape

clawdie-studio (the package)
  │
  ├── /usr/local/bin/colibri-daemon     (the service)
  ├── /usr/local/bin/colibri            (the CLI)
  ├── /usr/local/bin/colibri-mcp        (the MCP bridge)
  ├── /usr/local/bin/colibri-harness    (the TUI)
  ├── /usr/local/bin/colibri-studio     (the launcher)
  └── Zed extension: colibri-sidebar    (the visual panel)

colibri-studio launcher does:

1. Check if colibri-daemon service is running
2. If not, offer to start it (or start it automatically)
3. Open Zed with the correct workspace and extension settings
4. Optionally display a system tray indicator

ISO integration:

• clawdie-iso bundles all binaries
• Zed is either pre-installed or the extension works without it (CLI/TUI fallback)
• Firstboot wizard asks: "Enable Clawdie Studio?" and configures the service

colibri-mcp Scope

Phase 1 MCP tools (minimal viable set):

Tool	Description	Default
colibri_status	Daemon status (agents, sessions, host, paths, cost mode)	read-only
colibri_snapshot	Glasspane snapshot (all pane states)	read-only
colibri_list_tasks	Tasks by status (queued/claimed/done/failed)	read-only
colibri_agent_state	Current agent state for a pane	read-only
colibri_create_task	Create a task from current context	write-gated
colibri_intake_task	Submit intake task with capabilities	write-gated
colibri_set_cost_mode	Acknowledge requested mode; runtime-only/status-intent until live config exists	write-gated

Default ISO posture should be read-only. Mutating tools require:

COLIBRI_MCP_WRITE=1

Agent spawn/kill tools are stronger than normal writes and should require a separate guard plus allowlist:

COLIBRI_MCP_SPAWN=1
COLIBRI_MCP_SPAWN_ALLOWLIST=/usr/local/bin/pi,/usr/local/bin/colibri-smoke-agent

Phase 2 MCP tools (after basics proven):

Tool	Description
colibri_spawn_agent	Spawn an agent with provider/model config
colibri_kill_agent	Kill a running agent
colibri_session_summary	Summarize an active session
colibri_schedule_job	Add a cron/interval/one-shot job
colibri_search_skills	Search built-in knowledge (future colibri-skills)

Relationship to Existing Colibri Crates

colibri-daemon     ← already exists, socket API serves all clients
colibri-client     ← already exists, typed Rust client
colibri-contracts  ← already exists, shared wire types
colibri-glasspane  ← already exists, agent supervision state
colibri-harness    ← already exists, TUI dashboard
colibri-mcp        ← NEW: thin MCP bridge using colibri-client
colibri-studio     ← NEW: launcher binary (thin wrapper)

No existing crates need architectural changes. Two new thin binaries wrap existing infrastructure. The MCP binary should default its socket path from COLIBRI_DAEMON_SOCKET, then /var/run/colibri/colibri.sock.

Zed task fallback

Before MCP/native UI exists, Zed can still be Colibri-aware through project tasks or terminal commands:

colibri status
colibri snapshot
colibri list-tasks --status queued
colibri intake-task --title "review current project" --capability freebsd

This is sufficient for the next ISO if Zed is present but the integration bridge is not yet packaged.

Implementation guardrails

• Colibri remains service-owned and headless-safe; Zed never becomes required for boot or supervision.
• MCP is the first real editor bridge because it avoids forking Zed and can serve other MCP-capable clients.
• Native Zed extension/panel is a later UX layer, not the protocol source of truth.
• Write tools are opt-in; spawn tools are separately guarded and allowlisted.
• set-cost-mode remains runtime-only acknowledgement until a real mutable config model is implemented.
• No arbitrary shell command tool in MCP.

Decision Points

1. MCP server vs Zed extension vs both? Recommendation: start with MCP (editor-agnostic), add Zed-specific UI panel later.

2. colibri-studio launcher or just documentation? Recommendation: build a minimal launcher. It's ~200 lines of Rust and dramatically improves the first-run experience.

3. Include in ISO? Recommendation: include colibri-mcp and colibri-studio in the ISO artifact. Zed stays optional (pre-installed or user-added).

4. Timeline? Recommendation: colibri-mcp Phase 1 tools can be built in 1-2 focused sessions. colibri-studio launcher is another session. Total: ~1 week of focused agent time.

Non-goals

• Not embedding Zed into Colibri
• Not replacing the TUI (it stays the SSH/headless fallback)
• Not making the editor required for Colibri operation
• Not changing the socket API (MCP wraps it, doesn't replace it)
• Not building a custom GUI framework (use what exists)

Prior Art

• Herdr already does "visual dashboard over socket" for Linux/macOS
• colibri-harness already does this for TUI
• Zed + MCP is a proven integration path (Zed's assistant is MCP-native)
• VS Code + Language Server Protocol proved the "thin bridge over socket" pattern works at scale