Architecture

One binary, and the store is the bus

  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
  └─────────────────────────────────────────────┘
           ▲ tails past the projection mark every 500 ms
           │
  ┌────────┴────────────────────────────────────┐
  │ the host: devplane serve · open · app       │
  │ api      REST + SSE, bearer token, loopback │
  │ core     domain, reducers, attention, policy│
  │ acp      the client for every driven agent  │
  │ observe  OTLP, the roster, OpenCode's feed  │
  │ change   worktrees, gates, offers           │
  │ git      the git CLI                        │
  │ github   GitHub's API, its own sign-in       │
  │ web      the workbench, embedded            │
  └─────────────────────────────────────────────┘
           ▲ HTTP + SSE
    browser tab · the window · devplane CLI

• The hook writes. Every hook is a command hook running devplane hook: it decides in its own process, appends the event, the decision or a held permission to SQLite, and exits. If the store will not open, the decision goes to ~/.devplane/pending-decisions.jsonl and the next host files it.
• The host folds. devplane serve, devplane open or devplane app is the one long-lived process and the only one holding a socket. It tails what the hooks wrote, drives agents, receives telemetry, polls the roster and GitHub, and serves the workbench. Nothing auto-starts it.
• Read commands need no host. They ask a running host if one answers; otherwise they open the store, replay what the hooks wrote since the last projection in memory, write nothing, and name what they cannot see (live driven sessions, GitHub, the gate probe).

One host per home

The host writes ~/.devplane/host.json: port, version, start time, binary and pid. A host is alive when /healthz on that port answers, not because a pid exists. A second serve, open or app on the same home is refused with the running host’s uptime; a record whose port answers nothing is stale and cleared. devplane quit posts /api/quit with the token and waits for the port to go quiet; it sends no signal.

A second instance is a second home: DEVPLANE_HOME=/tmp/vp devplane serve --port 47832.

Events and reducers

• EventEnvelope { id, at, run_id, project_id?, source, event }, append-only. The source names the channel (a hook, OpenTelemetry, the roster, the status line, a vendor feed, a driven agent) or host for the host’s own acts.
• Reducers are pure functions (Run, Event) -> Run, tested by replay.
• The inbox is derived from state, never stored.
• /api/stream carries two tagged frames: event for a state change and message for a fragment of what a driven agent said. ?run= narrows it.

The purity rule

src/core/ may not reach the outside world: no async fn, no .await, no runtime, no database, no HTTP, no clock and no file system. The clock and files are read at the edge and passed in. tests/purity.rs fails the build on a violation.

This is what keeps state rebuildable by replay, the inbox correct after a restart, and the permission policy unable to fail open by waiting.

The store

SQLite with WAL and FTS5, in one file (schema version 11). A schema change moves the old file aside as devplane.v<n>.<time>.bak instead of migrating it, and never deletes one that holds anything. sqlite3 ~/.devplane/devplane.db opens it. ~/.devplane is mode 0700; the store, the token and the other files in it are 0600.

The retention sweep runs once when a host starts. Events (telemetry included) and driven agents’ messages older than 30 days are pruned, the search index with them, and finished runs older than 7 days. Decisions and asks are kept.

The API

HTTP + JSON on 127.0.0.1, with Server-Sent Events for live updates. Everything under /api needs the bearer token from ~/.devplane/token, in the Authorization header only. The telemetry routes under /devplane also accept the telemetry-only token from ~/.devplane/telemetry-token, which opens nothing else. /healthz and the workbench’s static files are open and carry no data.

There is no hook receiver: hooks write to the store.

Recovery

On host start: file what the spool holds → load projects, changes and runs → reconcile against the roster and live process ids → mark lost where a recorded process is gone → re-arm stall timers → open the API. The tail then catches up on what the hooks wrote while no host ran.

An unreadable roster never marks a run lost. A driven run that was mid-flight becomes interrupted, branch and worktree untouched, with resume offered where the agent supports it (Driving agents).

The window

devplane app runs the host inside the app’s own process and opens a WebView on http://127.0.0.1:<port>/?token=…, the address devplane open gives a browser. The page takes the token from the address once, removes it, and sends it as a header from then on. Same page, same API; no data crosses the window’s bridge. The window adds native notifications, a tray count, one global shortcut, devplane:// links, and opening a worktree in an editor or terminal. It is the cargo feature app, off by default, so the CLI build carries no WebKit.

Shutdown

devplane quit (or the window’s Quit) says what quitting ends, then the host stops answering, stops its pollers, stops every agent it drives (each agent’s whole process group) and waits, bounded, for their endings to be written. Stopped. prints once the port is quiet.

A killed host (kill -9, a crash, a power cut) cannot do this. The next host raises each agent it had started that is still running as a critical inbox item with the command to end it; it does not kill them for you.

Technology

DEVPLANE_UI=/path/to/dist devplane serve serves a built interface from disk instead of the embedded copy.

Performance

Each is 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.