Sam & Claude
9891d06144
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.
244 lines
9.8 KiB
Markdown
244 lines
9.8 KiB
Markdown
# 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-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/kill 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_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 (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 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
|
|
|
|
- **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
|