Architecture

Processes

  Claude Code / Codex / Copilot session
        │ command hooks
        ▼
  devplane hook ── decides in its own process, answers on stdout
        │ appends events, decisions, held asks
        ▼
  ~/.devplane/devplane.db  (SQLite) ◀── read commands, with no host
        ▲ tailed every 500 ms
        │
  devplane up ── the host: the one long-lived process and the only socket
        ▲ HTTP + SSE on 127.0.0.1
  browser tab · desktop window · devplane CLI

• The hook writes. devplane hook decides in-process, appends to SQLite, and exits. If the store will not open, the decision goes to ~/.devplane/pending-decisions.jsonl for the next host to file. There is no hook receiver route.
• The host folds. devplane up tails the hooks’ rows, drives agents over ACP, receives telemetry, polls the roster and GitHub, runs gates, and serves the workbench. Nothing starts it automatically.
• Read commands need no host. Without one they replay the store in memory, write nothing, and say what they cannot see.

One host per home

~/.devplane/host.json names the host’s port, version, start time, binary and pid; alive means /healthz answers, not that the pid exists. A second host on the same home is refused. devplane down posts /api/quit and waits for the port to close. A second instance needs its own DEVPLANE_HOME and port.

Source map

Events are EventEnvelope { id, at, run_id, project_id?, source, event }, append-only. Reducers are pure (Run, Event) -> Run, tested by replay. The inbox is derived from state, never stored.

The store

SQLite with WAL and FTS5, one file, schema version 18. A schema change starts a new store and moves the old one aside (after an upgrade).

Pruning runs once at host start.

The API

HTTP + JSON on 127.0.0.1, with Server-Sent Events on /api/stream (event and message frames; ?run= narrows it). Everything but /healthz and the static files needs a token (Security). Routes marked window need the desktop window’s proof as well.

Recovery and shutdown

On host start: file the spool, load projects, changes and runs, reconcile with the roster and live pids, mark lost where a process is gone, re-arm stall timers, open the API, and let the tail catch up. An unreadable roster never marks a run lost. A driven run caught mid-flight becomes interrupted, branch and worktree untouched, with resume where the agent supports it (Driving agents).

devplane down (or Quit) says what it ends, stops answering and polling, stops each driven agent’s process group, and waits, bounded, for their endings to be written. A killed host cannot: the next host raises each of its agents still running as a critical inbox item with the command to end it.

The window

devplane up --window runs the host in the app’s process and opens a WebView on the same URL a browser gets: same page, same API, no data over the window’s bridge. It adds notifications, a tray count, a global shortcut, devplane:// links, opening a worktree in an editor or terminal, and the proof the window routes need. Tauri 2, behind the Cargo feature app, off by default, so the command line links no WebKit.

DEVPLANE_UI=/path/to/dist devplane up --no-browser serves a built interface from disk.

Technology

Performance

Asserted by a test or fixed in code:

• Deciding a prohibition costs under 60 ms over starting the binary at all.
• The host folds hook-written rows within 500 ms.
• The roster is polled every 2 s while anything is busy, 10 s when idle; GitHub every five minutes.
• The embedded workbench stays under 250 KB gzipped.

Something wrong or out of date? Edit this page.