Smithers

Appearance

Smithers ​

What this is and why it exists ​

Matrix is docker-for-actors / npm-for-actors — a typed pub/sub/RPC substrate where every Feed, Service, and Component is an actor on a federated bus. Smithers is one vertical built on top of that substrate. It is the convergence loop: a methodical orchestrator that turns a GitHub issue into a constraint projection, dispatches a coding agent under that projection, forces the agent to argue every constraint at sign-off, dispatches parallel reviewers behind a barrier, and ratchets satisfied constraints as invariants the system never regresses past.

Smithers ships as the @open-matrix/smithers Package. It is dual: a headless SmithersSupervisor (with ConstraintGraph, GitHubAdapter, ContainerManager, WorkspaceActor children) plus a Pattern A browser workbench (<smithers-app>). The supervisor coordinates work; the workbench renders the same projection the agent and reviewers operate on (the Projection Principle from DESIGN.md §1.2).

Motivation ​

Raw agent loops drift: they wander, declare victory early, and produce output that almost meets the spec. Smithers exists to put a constraint barrier around that loop — gather the requirements first, dispatch a coding agent under an explicit projection of those requirements, force it to argue every constraint at sign-off, run parallel reviewers behind a barrier, and ratchet what has been proven so the system never regresses past it. Smithers does not replace the coding agent or the inference runtime; it orchestrates them so that work converges on the target the issue actually described. Read these docs if you ship work that has to converge on a spec, or if you operate an agent fleet and need a review barrier that does not depend on human attention to hold the line.

Where this fits ​

  • Vertical, not substrate. Smithers is a Package on the substrate. It uses system.agents, system.inference, system.factotum, and @open-matrix/inference-catalog; it owns none of them.
  • Tier 1 today. Smithers runs on a developer's local Host. Productization to a hosted Tier 2 surface is gated on the worker-isolation audit (P2.5) and the productization checklist (P2.6).
  • Wedge it serves. Vertical-A polish (the Personal AI runtime). Smithers is what makes a developer's local Host useful for engineering work once the substrate is up.

Five-minute quickstart ​

Smithers is opt-in (it consumes inference credit and Docker), so a default hivecast install does not start it.

bash
# Build smithers (and the Host wrapper if you don't already have it)
pnpm --filter @open-matrix/smithers build
pnpm --filter hivecast build

# Install + start a Host
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs start --home /tmp/matrix-home

# Bring up Smithers explicitly
matrix up @open-matrix/smithers --serve --home /tmp/matrix-home

# Open the workbench
#   http://127.0.0.1:3100/apps/smithers/

# From the bus
matrix invoke smithers smithers.status '{}' --home /tmp/matrix-home
matrix invoke smithers smithers.start '{"issueNumber":42}' --home /tmp/matrix-home

Once smithers.start runs, SmithersSupervisor walks the convergence pipeline (gathering → working → sign-off → reviewing → barrier → continuing) and the workbench renders each phase as a projection, not as ad-hoc UI state.

Conceptual map ​

  • Overview — what Smithers is, where it sits as a Matrix Package, how it differs from the broader agent platform.
  • User Guide — workbench tour, issue/session lifecycle, sign-off and review barrier, settings, the evaluation harness.
  • Developer Guide — package layout, coding-agent + inference integration, actor topology, tests.
  • Reference — manifest, browser components, supervisor ops, configuration.

Cross-references ​

Status note: cross-package import boundary. CodingAgent directly dynamic-imports @open-matrix/inference-catalog (projects/matrix-3/packages/smithers/src/coding-agent/CodingAgent.ts:219) instead of routing through system.inference over the bus. This is a known intentional design — tracked as P1.6 — and is not yet resolved. Documenting it here so that present-state pages don't pretend Smithers' inference path is fully bus-routed.

Note on terminology. "Harness" in the Smithers source means the evaluation/proof harness (see tests/, scripts/test.ts, the Stanford-paper proof ladder), not Smithers itself. The TOC's "Harness" page describes the convergence loop / review barrier — the actual product surface.

Source conventions: PORTABILITY-RULES.md.