# OpenRig architecture

> **This map is not the territory.** It is a zoomed-out guide for finding your way around the
> code. It is incomplete by design and it may be stale. Where it disagrees with the code, the code
> is right; please fix the page. Every path, symbol, count and command below was checked against
> commit `1347d825` (`v0.6.3-33-g1347d825c`). Each count shows the command that produced it, so you
> can re-run it.

## What OpenRig is

OpenRig runs a team of coding agents on your machine as one system. A local daemon keeps the team's
state in SQLite and runs each agent as an ordinary Claude Code or Codex session (or a plain
terminal, a Pi runner, or a scripted test stub) inside tmux. People and agents drive it through the
`rig` CLI, a terminal UI (TUI) and an MCP server, all of which talk to the daemon over local HTTP.
The agents themselves are unmodified. What OpenRig adds is the coordination around them: launching
and restoring agents, delivering messages, keeping durable work in a queue, and giving each agent
the right skills and context.

## Packages

| Directory | Package | What it is | How it ships |
|---|---|---|---|
| `packages/daemon` | `@openrig/daemon` (private) | The daemon: HTTP routes, domain services, SQLite migrations, runtime adapters, built-in specs, skills, plugins, static context-pack sources | Copied into `@openrig/cli` |
| `packages/cli` | `@openrig/cli` | The `rig` command, the MCP server, daemon start and stop | The only published package |
| `packages/tui` | `@openrig/tui` (private) | The terminal UI | Copied into `@openrig/cli`; opened by `rig tui`, by bare `rig` in a terminal, or by the `openrig-tui` bin |
| `packages/ui` | `@openrig/ui` (private) | The React web UI, in **maintenance mode**: it still ships and runs, but gets no new feature work. The CLI and TUI are the supported surfaces | Built files copied into `@openrig/cli` and served by the daemon |
| `packages/test-system` | none (not an npm workspace) | The stub-agent scenario library, the CI scenario harness, live-model eval cases | Not shipped |

**What bundles what.** `packages/cli/package.json` publishes `LICENSE`, `dist`, `daemon`, `ui`,
`tui` and `scripts`. `scripts/build-package.sh` (the CLI's `prepublishOnly`) builds the daemon, UI,
TUI and CLI, then assembles them inside `packages/cli/`: the daemon's `dist`, `assets`, `specs` and
`policies`, the generated context packs and a copy of `docs/reference/` go under `daemon/`; the UI
build goes to `ui/dist`; the TUI build goes to `tui/dist`. So `docs/reference/` ships to every
user; `docs/as-built/` and this file do not.

**Sharing code between packages.** The CLI and TUI import daemon code only through the subpaths in
the `exports` field of `packages/daemon/package.json` (18 at this commit), for example
`@openrig/daemon/attention`, which points at `packages/daemon/src/attention-surface.ts`. The CLI
uses 16 of them and the TUI uses 2. In development they resolve through the npm workspace. At
package time `scripts/rewrite-daemon-imports.mjs` rewrites them to the shipped `daemon/dist` copy
and fails the build on a specifier with no `exports` entry. To share new daemon code, add a
`*-surface.ts` file and an `exports` entry.

## The request path

```
  rig (CLI)            TUI            MCP server (rig mcp serve, stdio)
       \                |                /
        +---- HTTP to the daemon (port 7433 by default) --------------+
                                |
  packages/daemon/src/server.ts      createApp(): context middleware, /healthz, app.route("/api/...")
                                |
  packages/daemon/src/routes/        one Hono router per area; reads services with c.get(...)
                                |
  packages/daemon/src/domain/        services, repositories, orchestrators, event bus
              /                 |                  \
     SQLite (db/)       tmux (adapters/tmux.ts)    runtime adapters (adapters/*-adapter.ts)
                                                     claude-code, codex, pi, terminal, stub
```

**Inside the daemon** (`packages/daemon/src/`):

- **Startup.** `index.ts` is the process entry: it resolves where to listen, starts the server and
  runs the periodic queue sweeps. It calls `createDaemon()` in `startup.ts`, which opens the
  database (`db/connection.ts`: WAL mode, foreign keys on), runs `migrate(db, ALL_MIGRATIONS)`,
  constructs every service and adapter, and passes them to `createAppWithWebSocket(deps)` in
  `server.ts`.
- **`server.ts`.** In `createApp(deps)`, the first `app.use("*", ...)` middleware puts each
  service on the request context (`c.set("<name>" as never, deps.<name>)`), serves `/healthz`, and
  mounts each router with `app.route("/api/<area>", ...)`. Unknown `/api/*` paths get a JSON 404;
  other GET requests serve the web UI's built files.
- **`routes/`.** Thin handlers. For example, `routes/ps.ts` reads `psProjectionService` from the
  context and returns its entries as JSON. `routes/terminal-ws.ts` registers the terminal
  WebSocket, and `routes/require-sender-identity.ts` is a shared helper rather than a router.
- **`domain/`.** The behaviour: repositories over SQLite (`rig-repository.ts`,
  `queue-repository.ts`, `session-registry.ts`), orchestration (`startup-orchestrator.ts`,
  `node-launcher.ts`, `rigspec-instantiator.ts`), message delivery (`session-transport.ts`,
  `seat-delivery-guard.ts`) and events (`event-bus.ts`). Larger areas have their own
  subdirectories, such as `gateway/`, `provider/`, `policies/`, `scope/`, `context-packs/` and
  `mission-control/`.
- **`adapters/`.** The outside world. `tmux.ts` wraps tmux. The five `RuntimeAdapter`
  implementations launch each runtime and project skills and files into it. `cmux.ts` and
  `compose-services-adapter.ts` cover other integrations.
- **`db/`.** `connection.ts`, `migrate.ts`, `all-migrations.ts` and `migrations/`.
- **`middleware/auth-bearer-token.ts`.** The bearer-token check for operator write routes, plus
  the loopback and Tailscale bind detection used at startup.
- **Live updates** go out as server-sent events: `routes/events.ts` uses Hono's `streamSSE`, and
  the TUI subscribes to `/api/activity/events`.
- **State** lives in `$OPENRIG_HOME` (default `~/.openrig`). The database is `openrig.sqlite`
  there (`daemon-db-path.ts`).

**The clients:**

- **CLI.** `createProgram()` in `packages/cli/src/index.ts` registers every top-level command;
  the commands live in `packages/cli/src/commands/`. Most are thin clients: they call a daemon route
  through `DaemonClient` (`packages/cli/src/client.ts`) and render the result. A few lifecycle
  helpers open the database file directly. Bare `rig` in a terminal opens the TUI
  (`packages/cli/src/front-door.ts`).
- **MCP.** `createMcpServer(client)` in `packages/cli/src/mcp-server.ts` registers the tools over
  the same `DaemonClient`. `rig mcp serve` (`packages/cli/src/commands/mcp.ts`) runs it on stdio.
- **TUI.** `packages/tui/src/daemon-client.ts` is its only HTTP module. It reads existing daemon
  projections, for example `/api/ps`, `/api/rigs/summary` and `/api/queue/list`, and the
  `/api/activity/events` stream when the daemon offers it. The daemon URL comes from `--url`,
  `OPENRIG_URL`, or `http://127.0.0.1:7433`. Agents can drive a running TUI through its control
  socket (`packages/tui/src/socket-server.ts`).
- **Web UI.** Served by the daemon from the bundled `ui/dist`.

**In a development checkout,** `rig daemon start` prefers `packages/daemon/dist` over the bundled
copy (`resolveDaemonPath` in `packages/cli/src/daemon-lifecycle.ts`), and the TUI launcher prefers
`packages/tui/dist` (`packages/cli/src/front-door.ts`). Rebuild the package you changed. A daemon
that is already running keeps running the code it started with.

## Key counts

At commit `1347d825`. Run these from the repository root to refresh them.

| What | Count | Command |
|---|---|---|
| Database migrations | 89 (latest: `089_classification_identity_provenance.ts`) | `git ls-files packages/daemon/src/db/migrations \| wc -l` |
| Files in `routes/` | 67 | `git ls-files packages/daemon/src/routes \| wc -l` |
| ... of which create a Hono router | 65 | `git grep -l 'new Hono' -- packages/daemon/src/routes \| wc -l` |
| `app.route(...)` mounts in `server.ts` | 69 | `grep -c 'app.route(' packages/daemon/src/server.ts` |
| Top-level `rig` commands | 85 | `grep -c 'program.addCommand(' packages/cli/src/index.ts` |
| Runtime adapters | 5 (`claude-code`, `codex`, `pi`, `terminal`, `stub`) | `git grep -l 'implements RuntimeAdapter' packages/daemon/src \| wc -l` |
| MCP tools | 18 | `grep -c 'server.tool(' packages/cli/src/mcp-server.ts` |
| Daemon `exports` subpaths | 18 | `node -p 'Object.keys(require("./packages/daemon/package.json").exports).length'` |
| Library scenarios | 11 | `grep -l '^scenario:' packages/test-system/scenarios/*.yaml \| wc -l` |

## Where to add things

Each recipe names the files to touch. Read a neighbouring example before you start; the code is
the authority.

### A CLI command

1. Create `packages/cli/src/commands/<name>.ts` exporting a function that returns a commander
   `Command` and takes optional injected dependencies. `packages/cli/src/commands/unarchive.ts`
   is a short example.
2. In the action, get the daemon with `getDaemonStatus(...)` and `daemonStatusGuard(status)`
   (`packages/cli/src/daemon-lifecycle.ts`), then call it with
   `new DaemonClient(getDaemonUrl(status))` (`packages/cli/src/client.ts`). Offer `--json` for
   agents, and set `process.exitCode` on failure.
3. Register it in `createProgram()` in `packages/cli/src/index.ts` with
   `program.addCommand(...)`. If it takes injected dependencies, add them to `ProgramDeps` in the
   same file.
4. Add `packages/cli/test/<name>.test.ts`. `packages/cli/test/archive.test.ts` shows how tests
   inject mocked lifecycle dependencies.
5. If the command needs new daemon behaviour, add a route as well.

### A daemon route

1. Create `packages/daemon/src/routes/<area>.ts` with a Hono router. Both styles exist: a
   constant (`export const psRoutes = new Hono()` in `routes/ps.ts`) and a factory
   (`whoamiRoutes()` in `routes/whoami.ts`).
2. Read services from the request context with `c.get("<name>" as never)`. Keep the behaviour in
   `packages/daemon/src/domain/`.
3. Mount it in `createApp()` in `packages/daemon/src/server.ts` with
   `app.route("/api/<area>", ...)`, above the `/api/*` 404 catch-all.
4. A new service needs three more edits: a field on `AppDeps` and a `c.set(...)` line in
   `server.ts`, and its construction in `createDaemon()` in `packages/daemon/src/startup.ts`.
5. Test it the way `packages/daemon/test/whoami-routes.test.ts` does: build a small Hono app,
   `c.set` the service, mount the router and call `app.request(...)`. `createFullTestDb()` in
   `packages/daemon/test/helpers/test-app.ts` gives you an in-memory database migrated with the
   test fixture list (`migrationsForFullTestDb`).

### A database migration

1. Create `packages/daemon/src/db/migrations/<NNN>_<name>.ts` exporting a `Migration`
   (`{ name: "<NNN>_<name>.sql", sql: "..." }`; the type is in `packages/daemon/src/db/migrate.ts`).
   `089_classification_identity_provenance.ts` is a one-line example.
2. Take the next number after the highest on `main` (089 at this commit). Parallel pull requests
   often pick the same number, so check again and renumber if `main` moved before you merge.
3. Import it in `packages/daemon/src/db/all-migrations.ts` and append it to `ALL_MIGRATIONS`.
   Startup runs exactly that list (`startup-migrations-mirror.test.ts` pins this).
4. Add it to `migrationsForFullTestDb` in `packages/daemon/test/helpers/test-app.ts`, or list it in
   `migrationsForFullTestDbExclusions` with a reason. `migration-fixture-parity.test.ts` fails
   otherwise.
5. `migrate()` sorts migrations by name and records each applied name in `schema_migrations`, so
   an install that already applied a migration never runs it again. Editing a migration that has
   shipped changes nothing for those installs; add a new one instead. A long-lived install applies
   every new migration on its next start, against real data.

### A runtime adapter

1. Implement `RuntimeAdapter` from `packages/daemon/src/domain/runtime-adapter.ts`: `runtime`,
   `listInstalled`, `project`, `deliverStartup`, `launchHarness` and `checkReady`. The smallest
   implementation is `packages/daemon/src/adapters/terminal-adapter.ts`; the scripted test double
   is `stub-runtime-adapter.ts`.
2. Register it in `packages/daemon/src/startup.ts`. The adapter maps are keyed by runtime name:
   `adapters:` (for the pod instantiator) and `runtimeAdapters:`. The context monitor has its own
   map for the runtimes it samples.
3. Accept the runtime name in rig spec validation: `SUPPORTED_RUNTIMES` in
   `packages/daemon/src/domain/rigspec-preflight.ts`. Other runtime lists, such as `RuntimeHint` in
   `domain/discovery-types.ts` and `LEGACY_KNOWN_RUNTIMES` in `domain/rigspec-schema.ts`, may need
   it too; search for an existing runtime name such as `"pi"` to find them.
4. Launch, projection and readiness are arteries. Read
   [docs/as-built/arteries.md](docs/as-built/arteries.md) first.

### A shipped skill

Skills ship from three copies in this repository (the "edges"), listed in
`scripts/skill-edge-layout.generated.json`:

| Edge | Path | Layout |
|---|---|---|
| `spec` | `packages/daemon/specs/agents/shared/skills/` | by category (`core`, `pm`, `pods`, `process`) |
| `plugin` | `packages/daemon/assets/plugins/openrig-core/skills/` | flat |
| `canonical` | `skills/_canonical/` | public mirror of the `spec` copy |

Each skill in the layout file lists which edges carry it. At this commit, 33 skills are in `spec`
and `canonical`, 17 only in `plugin`, and 2 in all three.

- `npm run mirror-skills:check` (part of `npm test`) hashes every file in each edge and compares the
  hashes with `scripts/skill-edge-digests.generated.json`. It also fails on a `SKILL.md` the layout
  does not list.
- The full apply, `npm run mirror-skills`, regenerates all three edges from the maintainers' skill
  source, which lives outside this repository. It needs `OPENRIG_SKILL_CANON_ROOT` and three
  authority-file environment variables, so an outside contributor cannot run it.
- **To fix a skill:** edit the file in every edge that carries it (same bytes), run
  `node scripts/regen-edge-digests.mjs` to refresh the hashes from disk, then run
  `npm run mirror-skills:check`. Say in the pull request that you edited mirrored skill files: the
  next full apply regenerates these copies from the maintainers' source, so the change has to land
  there too.
- **To add a skill:** open an issue first. Its layout entry is generated from files that are not
  in this repository.
- Every shipped skill also becomes a context pack at package time (next recipe).

### A context pack

- **Static packs** are hand-written: a directory under `packages/daemon/context-packs-src/<name>/`
  with a `manifest.yaml` and its files. Keep `version: "0"` in the manifest; the generator stamps
  the package version. A pack file may be a symlink to a file under `docs/reference/`, so a
  reference document has one source (for example `help/help.md` points to
  `docs/reference/help.md`). Any other symlink fails the build. There are 5 static packs at this
  commit.
- **Generated packs** go to `packages/daemon/context-packs/`, which is gitignored and never edited
  by hand. `scripts/generate-context-packs.mjs` builds it at package time from every shipped skill
  and every static pack.
- `npm run generate-context-packs:check` (part of `npm test`) validates every pack through the
  daemon's own manifest parser, so build the daemon first. It also runs the leak scan over the
  static sources, including the `docs/reference/` files they link to.
- The daemon serves the shipped packs through `rig context get`; `startup.ts` registers the bundled
  directory as its built-in root.

### A scenario

Scenarios run the real CLI, daemon, tmux and SQLite with scripted stub agents (`runtime: stub`)
and no model cost.

1. Add `packages/test-system/scenarios/<defect-class>.yaml`, named for the class of bug it
   catches. Topology fixtures sit beside it (`*-stub.yaml`).
2. The format is checked by `validateScenario` in
   `packages/daemon/test/helpers/scenario-schema.ts`. Step verbs: `up`, `down`, `send`, `restart`,
   `restore`, `emit`, `mutate`, `policy`, `seed_regression`, `daemon`, plus `expect`. `expect` may
   only read shipped surfaces: `ps`, `queue`, `stream`, `scope`, `pane`, `transcript`,
   `tui_socket`, `policy_provenance`.
3. Today the runner binds `up`, `down`, `send`, `restart` and `daemon`. `restore`, `emit`,
   `mutate` and `policy` fail with `UnboundActionError`, and `seed_regression` needs a fault
   controller (`packages/daemon/test/helpers/scenario-real-deps.ts`).
4. Write a header comment naming the defect class and the seed: what a seeded regression plants,
   and which `expect` must catch it. A scenario counts only as a pair: it passes on healthy code
   and fails on the seeded run (`packages/test-system/README.md`).
5. **Run it on your machine** after `npm run build`, from a shell that is not inside tmux:
   `node --import tsx packages/daemon/scripts/run-scenarios.mjs <file.yaml>`. It uses a private
   daemon and a private tmux server, and refuses to start if `TMUX` is set. It supplies no fault
   controller, so a `seed_regression` step fails there; the seeded pair runs in the container
   path.
6. **CI.** The `installed-scenario` job runs `scripts/run-pr-scenarios.sh` in disposable,
   network-less containers built from the packed package. It runs two cases, both built around
   queue durability (`library` is `queue-baton-survives-restart.yaml`). Adding a case today means
   changing three files: the `--case` list in `scripts/run-pr-scenarios.sh`, `CASES` in
   `packages/test-system/ci/result.mjs`, and the fault controller in
   `packages/test-system/ci/run.mjs`. [docs/as-built/test-layers.md](docs/as-built/test-layers.md)
   covers both run modes, running a case on your own Docker host, and what a stub can and cannot
   prove.

## Guards you will meet

`npm test` runs `test:repo` (builds the daemon, runs `node --test scripts/*.test.mjs`, the docs
guard, `mirror-skills --check` and `generate-context-packs --check`) and then the daemon, CLI and
TUI suites. `npm run test:ui` runs the web UI suite separately. `npm run lint` typechecks all four
packages.

- **Docs guard** (`scripts/check-docs-guard.mjs`). Under `docs/`, git may track only
  `docs/as-built/`, `docs/reference/`, `docs/releases/` and exactly `docs/DESIGN.md`;
  `.gitignore` ignores the rest of `docs/`. Remember that `docs/reference/` ships inside the npm
  package, and the daemon copies its Markdown files to `$OPENRIG_HOME/reference/` when it
  starts. Files in `docs/as-built/` carry a `last-verified-against-source` commit in their
  frontmatter.
- **Internal-leak guard** (`scripts/internal-leak-scanner.mjs`, with rules in
  `scripts/internal-tokens.generated.json`). It refuses maintainer-internal names and paths in
  content that ships. It runs in `generate-context-packs.mjs` (static pack sources, on every
  `npm test`), in the full skill mirror apply (each public skill), in `scripts/build-package.sh`
  (the daemon `specs/` tree before it is copied into the package), and in the release-time
  substance gate (`scripts/check-substance-gate.mjs`, `npm run gate:substance`) over the packed
  CLI. No workflow runs it over a pull request's whole diff.
- **Portability report** (`.github/workflows/portability-report.yml`, running
  `scripts/portability-report.mjs`). On each pull request it lists added lines containing
  machine-specific values: credentials, home and temporary paths, network addresses, email
  addresses. It never fails the job; you read it and decide.
- **Generated files.** Do not hand-edit `scripts/*.generated.json` or anything under
  `packages/daemon/context-packs/`. The skill-edge digests are the one generated file a contributor
  refreshes, with `node scripts/regen-edge-digests.mjs` (see "A shipped skill").
- **Hosted CI** (`.github/workflows/tests.yml`): `build-and-package`, `typecheck`, `repo-checks`,
  `package-tests` (macOS; daemon, CLI, TUI and UI suites with no credentials and no external
  network) and `installed-scenario`.

## Pointers

- [CONTRIBUTING.md](CONTRIBUTING.md): setup, what a pull request needs, what to expect from review.
- [docs/reference/developing.md](docs/reference/developing.md): which checks block and which are
  advisory. It predates the hosted Tests workflow; `.github/workflows/tests.yml` is current.
- [docs/reference/worktree-builds.md](docs/reference/worktree-builds.md): building in a git
  worktree, with its own `npm install` rather than a symlinked `node_modules`.
- [docs/reference/](docs/reference/): user and operator reference; it ships with the package.
- [docs/as-built/](docs/as-built/README.md): module-by-module descriptions of the system. **These
  are being re-verified.** Most modules were last verified against `7eaf524c` (2026-05-16, around
  v0.3.1); the two pages this change adds, `arteries.md` and `test-layers.md`, are verified against
  `1347d825`. The older modules' counts are historical: `architecture/daemon-core.md`
  describes 40 migrations, and there are 89 today. Use them for orientation, then check the code.
- [docs/as-built/test-layers.md](docs/as-built/test-layers.md): what each test layer covers and
  what it cannot catch.
- [docs/as-built/arteries.md](docs/as-built/arteries.md): the areas where a small change has a
  large effect, what depends on them, and what broke there before.
- [packages/test-system/ci/README.md](packages/test-system/ci/README.md): the CI scenario job.
- [docs/releases/](docs/releases/) and [CHANGELOG.md](CHANGELOG.md): release history, written by
  the maintainers at release time.