switchboard-cli

Portable governance substrate for AI workflows.

Switchboard keeps project intent, dispatch context, returns, audits, receipts, and evaluation evidence in a repo-local .switchboard/ tree. The CLI is the primary interface; any web surface is only another view over the same governance state.

Alpha release: 0.1.0-alpha.4. Expect rough edges and breaking changes. Use it for governed experiments, demos, and research workflows before depending on it as production infrastructure.

Install

npm install -g switchboard-cli
sb --version

Requires Node.js 18 or newer.

What it does

Switchboard is not a chat wrapper or vendor gateway. It is a file-based governance layer around AI-assisted work:

• compile canonical project state into an execution contract
• generate SBX packets for Claude, ChatGPT, Cursor, or Codex-style surfaces
• ingest structured returns and reconcile them against the contract
• issue receipts that describe what was actually verified
• run independent evaluation against the latest receipt
• calibrate the trust machinery with blind, replay, and adversarial seeds
• run AutoAgent improvement loops with local, hybrid, cloud, parallel, and adaptive-governance modes

The core design goal is deterministic, inspectable workflow state rather than clever orchestration.

Quick start

# Scaffold repo-local governance state
sb init

# Compile the current project contract and objective
sb compile

# Generate a packet for a target surface
sb packet claude
sb packet chatgpt
sb packet cursor
sb packet codex

# Dispatch to Claude Code, then ingest the structured return
sb run claude
sb ingest

# Generate independent review context and issue a receipt
sb audit codex
sb receipt

# Evaluate the receipt independently
sb evaluate

The normal path is:

init -> compile -> packet -> run -> ingest -> audit -> receipt -> evaluate

Every step reads from or writes to .switchboard/ in the current project root.

Commands

| Command | Purpose | | --- | --- | | sb init | Scaffold .switchboard/ with project, working, routing, export, and return state | | sb compile | Compile the current canonical state into a governed loop contract | | sb compile --objective "<text>" | Override the loop objective for the next compile | | sb compile --surface <surface> | Force a target surface: claude-code, chatgpt, cursor, or codex | | sb packet <surface> | Generate an SBX dispatch bundle for claude, chatgpt, cursor, or codex | | sb packet <surface> --force | Generate a packet despite blocking integrity findings | | sb run claude | Dispatch the latest governed packet to Claude Code through the local transport | | sb run claude --dry-run | Prepare dispatch metadata without executing | | sb ingest | Ingest the expected structured return and persist reconciliation, gate, and audit inputs | | sb ingest --file <path> | Ingest a specific return YAML file | | sb audit codex | Generate and optionally execute Codex audit context for independent review | | sb receipt | Build a receipt from the latest persisted ingest artifacts | | sb receipt --export json | Export the receipt as standalone JSON | | sb receipt --export yaml | Export the receipt as standalone YAML | | sb evaluate | Run the independent evaluation lane against the latest audited receipt | | sb calibrate | Run the two-layer calibration harness | | sb autoagent | Run the governed autonomous improvement loop |

Receipts and evaluation

Receipts are intended to be honest evidence artifacts, not certificates. A receipt records the dispatch, ingest result, reconciliation findings, audit status, gate posture, and what the system can defensibly say about the run.

sb evaluate is deliberately separate from receipt generation. It reads the latest receipt and writes an independent assessment so that execution, receipt issuance, and evaluation do not collapse into one self-affirming step.

Calibration

sb calibrate tests the trust machinery itself.

# Default mix
sb calibrate

# Custom seed counts
sb calibrate --blind 10 --adversarial 5

# Adversarial-only run
sb calibrate --adversarial-only 8

# Replay-only run
sb calibrate --replay-only

# Review pending escalations and trends
sb calibrate --review
sb calibrate --trends

The harness compares an internal pipeline verdict with an external scorer that has no imports from the core implementation. Disagreements become calibration evidence rather than hidden failures.

AutoAgent

AutoAgent is an alpha improvement loop for governed projects. It expects:

• .switchboard/autoagent/program.md: what the loop should improve
• .switchboard/autoagent/score.ts: a score function that returns a numeric result

Common modes:

# Local loop; defaults to adaptive governance
sb autoagent --tier code --max-iterations 5

# Harness or full autonomy tiers
sb autoagent --tier harness
sb autoagent --tier full

# Explicit governance mode
sb autoagent --governance full
sb autoagent --governance light
sb autoagent --governance none
sb autoagent --governance adaptive

# Cloud coordinator or hybrid coordinator/local-worker modes
sb autoagent --cloud --tier code
sb autoagent --hybrid --tier code

# Cloud parallel mode: three workers test hypotheses concurrently
sb autoagent --cloud --parallel --tier code

# Inspect or control a cloud session
sb autoagent --status
sb autoagent --stream
sb autoagent --steer "focus on the highest-scoring hypothesis"
sb autoagent --stop

# Review or restore results
sb autoagent --results
sb autoagent --rollback

Adaptive governance starts with low overhead, then escalates when score jumps, boundaries are crossed, research pivots occur, or enough kept iterations accumulate. Dangerous-project keywords such as financial, live, credential, deploy, and production force full governance.

Cloud, hybrid, and parallel modes are included for showcase and research use. They may require local credentials, available vendor CLIs, and operator supervision.

Alpha boundaries

Switchboard currently optimizes for a clear CLI-first research/showcase path:

• canonical state lives in .switchboard/
• package internals are TypeScript source run through tsx
• receipts and evaluation are evidence records, not guarantees
• cloud and managed-agent paths are experimental
• public npm publication requires the internal packages to be published before the CLI

It intentionally does not try to be an enterprise control plane, observability product, generic eval platform, or vendor-sprawl abstraction.

License

MIT