colibri/docs/CLAWDIE-STUDIO.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 studio provides a unified surface so the user operates the control plane entirely within the editor, without terminal context-switching.

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-glasspane-tui (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-tui          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 startup checks 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-tui          (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/stop 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-test-agent

Phase 2 MCP tools (after basics proven):

Tool	Description
colibri_spawn_agent	Spawn an agent with provider/model config
colibri_stop_agent	Stop 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 (via 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-glasspane-tui ← already exists, TUI dashboard
colibri-mcp        ← already exists, MCP bridge + external MCP host (PR #36)
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 always remains service-owned and headless-safe; boot and supervision function independently of any editor.
• MCP is the first editor bridge: it serves any MCP-capable client and keeps Zed unforked.
• The standard editor bridge (MCP) is the foundation; a custom Zed panel is an optional nicer face we may add later, never the part everything depends on.
• Tools that change things are off by default and must be turned on on purpose; tools that launch agents are locked down further and only approved ones run.
• set-cost-mode only applies to the current session for now and isn't saved — permanent settings wait until we build a proper editable-config system.
• 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

• colibri-glasspane-tui already does "visual dashboard over socket" 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