Skip to content

The board, the API and the IDE

mini-ork's UI story is deliberately thin: the engine is the source of truth, and every surface is a view over the same data. There are three of them.

Surface What it is When to use it
mini-ork board CLI that returns the project's live state as JSON or a rendered page Scripting, debugging, anything in a terminal
mini-ork serve Local JSON API at http://127.0.0.1:7090 A client that wants to poll or steer without shelling out
mini-ork IDE Rust (GPUI) desktop app — a Zed fork with mini-ork panels Long-running work you want to watch and steer

There is no web frontend in this repository. The older React SPA and the agent-canvas fork it was replaced with have both been removed. The IDE reaches mini-ork through the CLI and, when serve is running, the HTTP read surface.

mini-ork board

board is the contract every panel is built on. It computes each section independently: a section that fails comes back empty with its error in errors instead of blanking the whole document.

mini-ork board                 # the whole project as one JSON document
mini-ork board --json          # same, explicitly JSON
mini-ork board --shell         # the shell-shaped view the IDE polls

The top-level document carries runs, learnings, automations, recipes, workspaces and scheduler state. Runs are limited to the most recent ~24 hours by default.

Verbs

Command Effect
board run <run-id> One run's card and its open workspace
board show <run-id> One run, all views
board node <run-id> <node-id> [--view V] [--offset N] One node's detail
board runs [--limit N] List recent runs
board start --kickoff <path> [--recipe R] [--workspace worktree\|in-place] [--set K=V ...] [--run-id ID] [--init] [--dry-run] Launch a run detached
board stop <run-id> Soft stop
board kill <run-id> SIGTERM, then SIGKILL after 2 s
board resume <run-id> Resume a cost-paused run
board retry <run-id> [--ack-change] [--force] [--dry-run] Re-dispatch a failed run
board merge <run-id> / board discard <run-id> Act on a run's workspace
board race-keep <winner> [--discard <run-id> ...] Keep one contestant of a race
board gate approve\|reject <inbox-id> [--note TEXT] Resolve a review gate
board steer <run-id> --role R --severity S --text TEXT Send guidance to a running run
board answer <run-id> --text T [--for QUESTION ...] Answer a run's question
board checkpoints <run-id> Per-node git checkpoints
board restore <run-id> <node> [--force] Restore the worktree to a checkpoint
board page <key> [--tab T] [--arg k=v ...] One IDE page as data

Node detail views: stream, output, prompt, telemetry, learning, changes, overview, artifacts, harness.

Exit codes: 0 ok, 1 failure, 2 usage.

mini-ork serve

mini-ork serve        # JSON API at http://127.0.0.1:7090

serve is API-only. It serves the JSON API under /api/v1/… and returns a JSON hint at /. It binds loopback by default and is meant to be a local companion process, not an internet-facing service.

The API exposes the same objects board returns, plus write actions for the things the IDE can do: launch a run, answer a question, approve a gate, stop or resume a run.

Treat the API as a local trust boundary

Anything that can reach the port can steer runs. Do not expose it beyond loopback without putting authentication in front of it. See Security model.

The mini-ork IDE

The IDE is a Rust (GPUI) application, built as a fork of Zed and maintained in a separate repository (SourceShift/zed-mini-ork; the crate is vendored here as the ui/ submodule).

Build and launch from the fork:

git clone --recurse-submodules <the zed fork>
cd zed-mini-ork
script/mini-ork-build
open -a "mini-ork IDE" ~/path/to/project

The Python runtime is the control plane; the IDE is a view. If the IDE is closed, runs continue. If the IDE crashes, nothing about a run changes.

What the panels show

Panel Source
Runs / Threads board board run cards
Run detail, DAG overlay board show / board page
Node stream and output run-dir files and run_events
Changes the run's workspace diff
Artifacts the run dir's artifact manifest
Learning gradients and patterns for the project
Inbox review gates awaiting a decision
Lanes provider health and configured models
Automations scheduled runs and their next fire

Everything a panel shows is reproducible with sqlite3 .mini-ork/state.db queries and files on disk. The UI adds navigation and correlation, not private state.

The v2 run page

The run page has two layout levels. Set MINI_ORK_IDE_SPEC=2 to select the v2 "dispatch console" layout: a run header with outcome and graph, a tab bar, and per-node drill-downs. Level 1 remains the default when the variable is unset, so an older IDE and a v2 one can share a project.

The IDE sets the level for its own subprocess calls; a server started earlier keeps the level it was started with.

Steering a running run

Three actions are available while a run is in flight:

  • Steer — send a role-specific note the next node can read. board steer <run-id> --role implementer --severity note --text "prefer the small fix".
  • Answer — reply to a question the run asked. board answer <run-id> --text "yes, keep the old API".
  • Gate — approve or reject a human review gate when the recipe requires one. board gate approve <inbox-id> --note "reviewed".

Steering is advisory by default. It cannot override a gate; it changes what the next model call sees.

Review gates

Recipes can require a human decision before a change is published. When one is required, the run pauses and writes a row the inbox shows. board gate resolves it. Review gates ship off by default; a recipe opts in.