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

```text
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.

```text
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`.

```text
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

```text
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:

```sh
COLIBRI_MCP_WRITE=1
```

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

```sh
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

```text
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:

```sh
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