Coevolve

A terminal control plane for agentic software delivery — an 8-mode Bubble Tea dashboard that drives the mini-ork orchestration loop with opencode as the LLM worker, and renders the live flow, costs, memory, and learning in one place. Every panel shows real data only (provenance-gated — never mock numbers).

Coevolve is the extensible CLI over four cooperating subsystems:

You type a task in the Home command line; plain text goes to the configured main LLM (opencode) and streams back like Claude/opencode, while /run <task> (or any task that names mini-ork) spawns a full orchestration you watch node by node — with per-node cost, lane, and status pulled straight from mini-ork's state.db.

Coevolve is a front-end over a stack — it doesn't do the work itself, it drives and visualizes the subsystems below. On its own the binary builds and launches, but every panel will read "offline" until you wire in its sources.

To build

• Go 1.25+

Required at runtime (without these, Coevolve has nothing to drive)

• opencode CLI, authenticated — the LLM worker for both chat and the implementer lane. Coevolve inherits your ~/.local/share/opencode/auth.json and env keys (OpenAI/Cloudflare/etc.).
• mini-ork checkout — the orchestrator. /run shells out to it, and its state.db is the source for the Runs, Router, Topology, Cost, Logs, and Learning panels. Point Coevolve at it with MINI_ORK_ROOT.

Optional — enables specific modes

• ContextNest — a separate HTTP service (Rust/axum) that backs the ContextNest mode (capsules · basins · graph). Coevolve talks to it over REST at CN_BASE_URL (default http://127.0.0.1:28080); when it's down, mode 4 renders "ContextNest offline" and the rest of the app is unaffected.
• TraceOtter — the learning/GRPO layer. Its signal (rewards by lane, objective domains) rides in mini-ork's state.db, so the Learning mode lights up as soon as mini-ork has recorded traces — no extra service to run.

In short: you need opencode + a mini-ork checkout to get real work and data; ContextNest is an add-on for the memory mode; TraceOtter data comes for free with mini-ork.

git clone https://github.com/sourceshift/coevolve.git
cd coevolve
go build -o bin/coevolve ./cmd/coevolve

Then run the binary directly, or go install ./cmd/coevolve to put coevolve on your PATH.

# point at your mini-ork checkout, then launch the dashboard
export MINI_ORK_ROOT=/path/to/mini-ork
./bin/coevolve

In the TUI:

1. Land on Home (mode 0). Type a request and press Enter.
2. Plain prose → streams from the main LLM. /run <task> → mini-ork orchestration.
3. /run opens an interactive pre-flight: pick the recipe, a hard budget cap, and dry-run vs. live, then confirm. The loop renders inline.
4. Switch modes with digits 0–7 (or ←/→) to inspect runs, cost, memory, topology, and logs.

coevolve [tui]          launch the 8-mode dashboard (default)
coevolve capabilities   list registered integrations by role (headless smoke)
coevolve version        print the version

capabilities needs no TTY — it's a quick check that the extensibility spine is wired.

Modes self-register at startup, so adding a mode is a single new file under internal/tui/modes/.

While the Home prompt is focused, keystrokes type normally; a bare digit only switches tabs when the input is empty.

Coevolve is configured entirely through the environment (sane fallbacks apply):

DB resolution order: MINI_ORK_DB → MINI_ORK_HOME/state.db → MINI_ORK_ROOT/.mini-ork/state.db. When the DB is unreachable, modes render an honest "offline" state rather than fabricated data.

you ─▶ Home command line
         │
         ├─ plain text ──▶ opencode serve (HTTP+SSE) ──▶ streamed prose/tools
         │
         └─ /run <task> ─▶ mini-ork loop ──▶ nodes ──▶ state.db ──▶ live panels
                              (classify→plan→execute→verify→reflect→…)

For chat, Coevolve spawns an isolated opencode serve on a free port, creates a session pinned to your worker model, and reads the SSE event stream — surfacing text, tool calls, tokens, and cost as they happen. For /run, it shells out to mini-ork and tails the run's own state.db so every node row you see is the real one mini-ork just wrote.

cmd/coevolve/       entrypoint + subcommand dispatch
internal/core/      integration registry, events, provenance (the spine)
internal/tui/       Bubble Tea root model, palette, keys, palette overlay
internal/tui/modes/ the 8 self-registering dashboard modes
internal/run/       run controller · opencode serve worker · mini-ork spawn
internal/seams/     read-only data seams over mini-ork's DB / ContextNest / logs
internal/plan/      recipe catalog + suggestion for the /run pre-flight
internal/session/   per-session JSONL run log
kickoffs/           the build roadmap (10 epics)
reference/          the original Python prototype (contracts)

• Real data only. Panels are provenance-gated; if the source is missing, the panel says so — it never invents a number.
• Extensible spine. Integrations register by Kind (orchestrator, memory, learning, worker, router); modes register themselves. Adding either is one file.
• Single-user, credential-inheriting. No isolated XDG — it uses your real authenticated opencode config, so a run works exactly as opencode would.

Apache License 2.0. Architecture informed by omnigent (Apache-2.0).