GitHub - kmccleary3301/breadboard: A Programmable Harness Calculus

Agent engine · harness emulator · TypeScript SDKs · multi-client coding stack.

5-minute quickstart · docs index

BreadBoard is a coding-agent engine and research workbench built around one hard constraint:

every client, replay, harness profile, and host integration should run against the same engine truth surface rather than a collection of unrelated wrappers

That constraint is what makes the repo unusual.

BreadBoard is simultaneously:

a Python engine with a CLI bridge and deterministic event log
Python and TypeScript SDKs over the same bridge
a terminal-first coding stack with multiple client surfaces
authorable harness definitions with lock-first execution
TypeScript packages for SDK, transport, and runtime-boundary experiments
a conformance-heavy environment for replay, parity, optimization, long-run agents, and future evaluation work
a growing research platform for ATP, formal sandboxes, optimization, DAG search, RL export layers, C-Trees, and DARWIN

This repository is for engineers and researchers who care about:

strong contract boundaries
reproducibility
host/runtime interoperability
evidence-backed parity claims
configurable harness behavior instead of hard-coded one-off agents

What you can do with BreadBoard

Surface	What it is	Status
Engine + CLI bridge	Canonical HTTP + SSE runtime surface used by every client	🟢
Python SDK	Programmatic access to the engine from Python	🟢
TypeScript SDK	CLI-bridge TypeScript client package	🟢
TypeScript packages	SDK, transport, and runtime-boundary packages	🟡
Primary TUI	`kmccleary3301/breadboard-tui`	🟢
OpenTUI slab	Fixed-height slab client in `opentui_slab/`	🟡
VSCode sidebar	Early client surface in `vscode_sidebar/`	🟡
Harness execution	Author, validate, lock, and run reproducible harnesses	🟢
Replay / conformance	Golden, parity, and contract validation paths	🟢
Long-run / RLM / optimization work	Experimental and advancing, but real	🟡
DAG / RL / DARWIN / ATP / C-Trees research layers	Integrated and documented, with active playbooks	🟡

The shortest accurate description

BreadBoard is what you get if you start with:

“I want something in the same broad class as Codex CLI, Claude Code, and OpenCode”

and then you keep going until you also have:

explicit kernel contracts
replay-proof evidence
profile-driven harness emulation
TypeScript SDK and runtime-boundary packages
multiple clients talking to one engine

It is not a thin wrapper around one provider SDK, and it is not just a terminal app.

Choose your path

If you want to…	Start here
clone the repo and get something running quickly	docs/quickstarts/FIRST_RUN_5_MIN.md
do a full local setup with environment validation	docs/getting-started/INSTALL_AND_DEV_QUICKSTART.md
figure out which canonical script family or entrypoint to use	docs/guides/OPERATOR_SCRIPT_SURFACE.md
understand the repo at a high level	docs/INDEX.md
understand the research systems and choose the right advanced subsystem	docs/quickstarts/RESEARCH_SYSTEMS_QUICKSTART.md
use the engine from Python or TypeScript	docs/contracts/cli_bridge/openapi.json and the examples below
evaluate parity / replay / evidence	docs/conformance/README.md
evaluate the TypeScript package surfaces	`sdk/ts/`, `sdk/ts-kernel-contracts/`, `sdk/ts-backbone/`
understand BreadBoard’s stable contracts and evidence posture	docs/contracts/policies/KERNEL_CONTRACT_PACK_V1.md

Research systems entrypoint

If you are here for the newly integrated research-facing subsystems, start with:

Those docs are the fastest path into:

ATP and Lean sandboxing
optimization
DAG runtime
RL training overlays
C-Trees
DARWIN

Public, durable documentation now lives under the tracked docs/ taxonomy. Maintainer-only notes live under docs/internals/, including the research-closeout and stop/go material in docs/internals/research/. Local planning, research, tranche, and archaeology material is intentionally offloaded to docs_tmp/ so new readers do not have to navigate our execution residue first.

The stable top-level zone model is documented in docs/reference/REPOSITORY_ZONE_MODEL.md.

Repository map

├── agent_configs/                 product harness definitions + public top-level E4 dossier configs
│   └── misc/                      scenario-specific, historical, and supporting configs
├── breadboard/
│   ├── product/                   public product operations and interfaces
│   ├── artifacts/                 shared artifact ownership primitives
│   └── rl/                        research-only training and evaluation modules
├── breadboard_engine/             canonical Python engine and runtime substrate
│   ├── api/                       CLI bridge server, session runner, protocol surfaces
│   ├── execution/                 runtime execution primitives
│   ├── longrun/                   durable/background execution logic
│   ├── mcp/                       MCP integration layer
│   ├── optimize/                  optimization/evaluation substrate
│   ├── orchestration/             orchestration logic and controllers
│   ├── reward/                    evaluation and reward surfaces
│   ├── rlm/                       recursive language model / long-form work
│   ├── state/                     session/event/transcript state
│   ├── todo/                      task/todo primitives
│   └── tool_calling/              tool routing and related logic
├── breadboard_sdk/                Python SDK surface
├── sdk/
│   ├── ts/                        CLI-bridge TS SDK
│   ├── ts-backbone/               TypeScript runtime API experiments
│   ├── ts-workspace/              public workspace / execution-profile layer
│   ├── ts-host-kits/              reusable host-integration abstractions
│   ├── ts-host-bridges/           concrete host bridge experiments
│   ├── ts-host-t3/                small host-boundary starter package
│   ├── ts-transport-ai-sdk/       AI SDK projection/session transport adapter
│   ├── ts-kernel-contracts/       TS contract/types/validators for kernel schemas
│   ├── ts-kernel-core/            TS kernel substrate and constrained runtime slices
│   ├── ts-execution-drivers/      shared driver interfaces and planning
│   ├── ts-execution-driver-local/ trusted-local execution driver
│   ├── ts-execution-driver-oci/   OCI / gVisor / Kata-oriented execution driver
│   ├── ts-execution-driver-remote/ delegated remote execution driver
│   └── ts-orchestration-temporal/ durable orchestration adapter work
├── config/
│   ├── longrun/                   long-run and durable-execution config surfaces
│   └── text_contracts/            text and contract artifacts
├── conformance/                   engine fixture bundles and conformance manifests
├── contracts/                     machine-readable kernel and contract schemas
├── docs/                          durable tracked docs surface
├── implementations/               profiles, prompts, tools, and synthesis assets
├── opentui_slab/                  fixed-height OpenTUI-style client
├── scripts/                       setup, validation, replay, export, and maintenance tools
├── tests/                         Python-side validation and conformance tests
├── tool_calling/                  tool-dialect work and examples
├── tools/                         supporting tooling (for example instrumented harness refs)
├── tui_skeleton/                  legacy TUI contract/golden harness (not distributed)
└── vscode_sidebar/                VSCode sidebar surface

Zone intent:

breadboard/product/ and breadboard/artifacts/ are product-facing packages
breadboard/rl/, breadboard/search/, and breadboard/optimize/ are research-only and excluded from the product wheel
breadboard_engine/ is the canonical internal engine; the former package alias has been removed
breadboard_ext/ is extension space
breadboard_sdk/ and sdk/ are SDK and host surfaces
scripts/ and docs/ are support surfaces with explicit taxonomy

If you want the documentation equivalent of that map, see docs/INDEX.md.

Install and bootstrap

Requirements

Requirement	Recommended	Notes
Python	3.11+	engine, Python SDK, scripts
Node.js	22+	TUI and TS packages
`uv`	recommended	bootstrap prefers `uv` when available
`npm`	current stable	used for client and TS package setup

Fast path

bash scripts/dev/bootstrap_first_time.sh

Engine-only:

bash scripts/dev/bootstrap_first_time.sh --profile engine

Make shortcuts:

make setup
make setup-fast
make setup-engine
make setup-fast-engine

Verification

python scripts/dev/quickstart_first_time.py --include-advanced
python scripts/dev/first_time_doctor.py --strict
make doctor
make setup-refresh-python
make cli-capabilities
make devx-smoke
make devx-full-pass
make devx-timing
make sdk-hello-live
make disk-report

What the bootstrap actually does

creates or reuses .venv
installs Python dependencies from requirements.txt
builds relevant Node/TS packages when sources are present
performs doctor/smoke checks unless you explicitly choose a faster path

For the detailed setup reference:

Common command paths

Goal	Command
bootstrap everything	`make setup`
engine-only bootstrap	`make setup-engine`
strict environment doctor	`make doctor`
inspect CLI capabilities	`make cli-capabilities`
SDK hello verification	`make sdk-hello-live`
fast dev-x smoke	`make devx-smoke`
full dev-x confidence pass	`make devx-full-pass`
inspect `~/.breadboard` disk usage	`make disk-report`
prune `~/.breadboard` safely	`make disk-prune`

For the full set, see Makefile.

Basic usage

CLI

Create, lock, and run a product harness:

breadboard harness create --out ./harness
breadboard harness lock ./harness/daily_driver.v1.yaml \
  --out ./harness/daily_driver.lock.json
breadboard harness run ./harness/daily_driver.v1.yaml \
  --lock ./harness/daily_driver.lock.json \
  --local \
  --task "Summarize the repository layout in five bullets."

harness create copies the public bb.harness_definition.v1 daily-driver profile, its bb.model_roles.v1 role map, and its system prompt. As shipped, it uses deterministic mock/reference behavior and consults no provider credential. Configured provider mode is explicit: replace the profile's providers model declaration and matching role targets with a supported integration, create a fresh lock, and retain the profile's prompt-mode shell approval policy.

Configured provider mode is bounded by the provider support and known-divergence table and its machine-readable manifest. Those rows are synthetic and provider-free: real login, credential validity, live provider network, cost, latency, quota, model quality, and release-wide behavior remain unproved until the named external gates.

breadboard --json system describe resolves that package-local bundle and reports its definition, lock, and resource identities under data.default_profile.

Run the engine directly from source:

python -m breadboard_engine.api.cli_bridge.server

RL episode harness

breadboard.rl.harness runs SWE and terminal training episodes for external trainers. The wrapper creates an episode, runs it through the versioned HTTP interface, and closes it when NeMo returns or cancels the rollout. BreadBoard selects the trusted profile, drives policy turns, executes tools in the admitted sandbox image, runs the verifier in a separate copied lease, records artifacts, and closes both leases.

Profiles come from BREADBOARD_HARNESS_PROFILES_FILE or BREADBOARD_HARNESS_PROFILES_JSON. A profile must admit immutable image digests and named verifier commands. SWE profiles set require_repository_binding: true and map each repository snapshot digest to its approved image with repository_images. The process driver requires trusted_process: true and reports network: host; use it only for local tests because it executes on the host without network isolation.

BREADBOARD_HARNESS_PROFILES_FILE=/secure/breadboard-harness-profiles.json \
BREADBOARD_HARNESS_TOKEN="$(cat /secure/breadboard-harness.token)" \
BREADBOARD_POLICY_ALLOWED_HOSTS=policy-model.internal \
python -m breadboard.rl.harness.api

The server binds to 127.0.0.1:8097 by default. A non-loopback bind requires BREADBOARD_HARNESS_TOKEN, and custom ASGI launchers must opt into unauthenticated loopback mode explicitly. Artifacts persist under BREADBOARD_HARNESS_ARTIFACT_ROOT (default ~/.breadboard/rl-harness/artifacts) and are available through the authenticated retrieval paths returned in each artifact reference. The token-only policy bridge rejects policy-visible image content; sandbox images and repository snapshots travel as immutable digests.

Python SDK

from breadboard_sdk import BreadBoardClient

client = BreadBoardClient(base_url="http://127.0.0.1:9099")
client.create_harness()
lock = client.lock_harness("daily_driver.v1.yaml")
started = client.start_session({
    "lock_id": lock["data"]["path"],
    "task": "List the top-level modules and explain each in one line.",
})
session_id = started["data"]["session"]["session_id"]

for event in client.events_session(session_id):
    print(event["kind"], event["payload"])

Product session streams persist only stable observation projections: assistant_message reports metadata.has_content, tool_call reports the public tool name, and tool_result reports that name plus whether execution failed. Assistant content, tool arguments and results, credentials, paths, and backend event IDs are not written to the product session log. Completed streams replay with the same sequence after a service restart.

The SSE envelope is bb.public_session_event.v1; it is not the canonical kernel bb.kernel_event.v2 record. Every payload_schema_version resolves to either the public product-session lifecycle payload schema or the registered kernel observation payload schema.

TypeScript SDK

import { createBreadboardClient } from "@breadboard/sdk"

const client = createBreadboardClient({ baseUrl: "http://127.0.0.1:9099" })
await client.createHarness()
const lock = await client.lockHarness("daily_driver.v1.yaml")
const started = await client.startSession({
  lock_id: lock.data.path,
  task: "Explain the purpose of the conformance directory."
})
const sessionId = started.data.session.session_id

for await (const event of client.eventsSession(sessionId)) {
  console.log(event.kind, event.payload)
}

TypeScript runtime packages

The TypeScript package family includes SDK, workspace, transport, and runtime-boundary surfaces. Treat these as package-level APIs, not as a public claim that external hosts should adopt BreadBoard as their primary runtime:

import { createWorkspace } from "@breadboard/workspace"
import { createBackbone } from "@breadboard/backbone"

const workspace = createWorkspace({
  workspaceId: "demo",
  rootDir: process.cwd(),
})

const backbone = createBackbone({ workspace })
const session = backbone.openSession({
  sessionId: "demo-session",
  requestedModel: "openai/gpt-5.4",
  requestedProvider: "openai",
  projectionProfileId: "ai_sdk_transport",
})

Transport and host-boundary packages

The host-boundary packages are useful for local experiments and integration tests:

import { createT3CodeStarter } from "@breadboard/host-t3"

const starter = createT3CodeStarter()

Relevant package docs:

Public E4 dossiers

One of the strongest features in this repo is that the top-level public E4 configs are inspectable harness dossiers rather than opaque overlays.

Harness	Public dossier	What it gives you
Codex	codex_0-107-0_e4_3-6-2026.yaml	current Codex public dossier with tracked target package refs
Claude Code	claude_code_2-1-63_e4_3-6-2026.yaml	replay-focused Claude dossier with explicit policy surfaces
OpenCode	opencode_1-2-17_e4_3-6-2026.yaml	shared OpenCode dossier with replay bundles in `misc/`
oh-my-opencode	oh_my_opencode_3-10-0_e4_3-6-2026.yaml	async/background-task-oriented dossier surface

Supporting docs:

Public dossier readability does not mean perfect parity everywhere. Use the evidence docs and replay bundles for exact claim boundaries.

Conformance, replay, and evidence

BreadBoard keeps a deterministic event log and leans heavily on replay/evidence.

Typical replay workflow

python scripts/release/export_cli_bridge_contracts.py
bash scripts/phase12_live_smoke.sh
RUN_DIR="$(ls -1dt logging/* | head -n 1)"
python scripts/log_reduce.py "${RUN_DIR}" --turn-limit 2 --tool-only

Useful entrypoints

Area	Start here
conformance overview	docs/conformance/README.md
test matrix	docs/conformance/CONFORMANCE_TEST_MATRIX_V1.md
kernel contract pack	docs/contracts/policies/KERNEL_CONTRACT_PACK_V1.md
replay-proof quickstart	docs/quickstarts/REPLAY_PROOF_BUNDLE_QUICKSTART.md
launch proof media	docs/media/proof/README.md

What the event log is for

replay
evidence extraction
host projection
conformance comparisons
debugging
future optimization work

The point is not just observability. The point is that the same canonical event truth can feed:

the TUI
the VSCode sidebar
TS host integrations
replay fixtures
parity claims

TypeScript package map

Package	Role
`sdk/ts/`	CLI-bridge TypeScript SDK
`sdk/ts-kernel-contracts/`	generated types/validators for kernel contracts
`sdk/ts-kernel-core/`	constrained TS kernel substrate
`sdk/ts-workspace/`	execution profiles, capability sets, artifact refs, output shaping
`sdk/ts-backbone/`	TypeScript runtime API experiments
`sdk/ts-host-kits/`	reusable host integration abstractions
`sdk/ts-host-bridges/`	concrete host bridge implementations
`sdk/ts-host-t3/`	small host-boundary starter package
`sdk/ts-transport-ai-sdk/`	AI SDK projection/session transport layer
`sdk/ts-execution-drivers/`	shared execution-driver contracts and helpers
`sdk/ts-execution-driver-local/`	trusted-local execution path
`sdk/ts-execution-driver-oci/`	OCI/gVisor/Kata execution path
`sdk/ts-execution-driver-remote/`	delegated remote execution path
`sdk/ts-orchestration-temporal/`	Temporal-oriented orchestration adapter work

If you are evaluating the TypeScript packages, this table is the starting point.

Client surfaces

Client	Path	Notes
Primary terminal client	`kmccleary3301/breadboard-tui`	canonical end-user TUI and `bb` binary
Legacy TUI contract harness	`tui_skeleton/`	retained for contract, replay, and golden validation; not distributed
OpenTUI slab	`opentui_slab/`	fixed-height slab experiments
VSCode sidebar	`vscode_sidebar/`	extension/client surface
Python host scripts	`breadboard_sdk/`	Python API consumption
TS packages	`sdk/ts/` and related packages	SDK, transport, and runtime-boundary experiments

Docs navigator

The repo docs are large. These are the most useful entrypoints.

Setup and onboarding

Doc	Purpose
docs/quickstarts/FIRST_RUN_5_MIN.md	fastest path from clone to a working local run
docs/getting-started/INSTALL_AND_DEV_QUICKSTART.md	full setup and environment reference
docs/INDEX.md	docs map by audience and task

Contracts and kernels

Doc	Purpose
docs/contracts/policies/KERNEL_CONTRACT_PACK_V1.md	stable public contract pack
docs/contracts/kernel/PROGRAM_INDEX_V1.md	kernel and runtime contract program map

Conformance and claims

Doc	Purpose
docs/conformance/README.md	conformance suite overview
docs/contracts/policies/KERNEL_CONTRACT_PACK_V1.md	public-facing contract and change discipline

Claim boundaries

BreadBoard has strong parity and conformance claims, but it does not use vague wording casually.

Two examples of what this README is not claiming:

BreadBoard is not presented here as a blanket drop-in replacement for every other harness.
BreadBoard is not presented here as having perfect parity everywhere just because a harness definition exists.

Use these before repeating a claim:

Repo status

Area	Current posture
Engine and CLI bridge	🟢 active
Product contract catalog	🟢 active
TypeScript SDK and runtime-boundary packages	🟡 active / evolving
TUI and client surfaces	🟢 active / evolving
VSCode sidebar	🟡 active buildout
Long-run / RLM / optimization	🟡 active research/buildout
Broad “full replacement” claims for every external harness	🔴 not implied by this README

A few repo-specific observations

The engine-client split is the central design bet, not a detail.
The product operation catalog is the source for the ordinary CLI, HTTP API, and SDK surfaces.
The TypeScript package work is active, but public claims should stay tied to shipped package behavior and conformance evidence.
The conformance and evidence story is part of the product, not just internal test infrastructure.

If those things are what you care about, BreadBoard is likely worth your time. If what you want is a minimal wrapper around one provider SDK, it probably is not.

Where to go next

Run the quickstart:
- docs/quickstarts/FIRST_RUN_5_MIN.md
Read the docs map:
- docs/INDEX.md
Inspect the product operation contract:
- contracts/public/operations.v2.json
If you are evaluating TypeScript packages, start here:
- sdk/ts/README.md
- sdk/ts-kernel-contracts/README.md
If you care about proof and parity:
- docs/conformance/README.md

Navigation Menu

Repository files navigation

What you can do with BreadBoard

The shortest accurate description

Choose your path

Research systems entrypoint

Repository map

Install and bootstrap

Requirements

Fast path

Verification

What the bootstrap actually does

Common command paths

Basic usage

CLI

RL episode harness

Python SDK

TypeScript SDK

TypeScript runtime packages

Transport and host-boundary packages

Public E4 dossiers

Conformance, replay, and evidence

Typical replay workflow

Useful entrypoints

What the event log is for

TypeScript package map

Client surfaces

Docs navigator

Setup and onboarding

Contracts and kernels

Conformance and claims

Claim boundaries

Repo status

A few repo-specific observations

Where to go next

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
agent_configs		agent_configs
breadboard		breadboard
breadboard_engine		breadboard_engine
breadboard_ext		breadboard_ext
breadboard_sdk		breadboard_sdk
config		config
conformance		conformance
container_templates		container_templates
contracts		contracts
docs		docs
docs_tmp		docs_tmp
examples		examples
implementations		implementations
internals/archive/scripts		internals/archive/scripts
misc/opencode_runs		misc/opencode_runs
opentui_slab		opentui_slab
renderer_assets		renderer_assets
scripts		scripts
sdk		sdk
tests		tests
tool_calling		tool_calling
tools/claude_code_logged		tools/claude_code_logged
tui_skeleton		tui_skeleton
vscode_sidebar		vscode_sidebar
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
README.md		README.md
adaptive_iter.py		adaptive_iter.py
main.py		main.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
requirements_web.txt		requirements_web.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

What you can do with BreadBoard

The shortest accurate description

Choose your path

Research systems entrypoint

Repository map

Install and bootstrap

Requirements

Fast path

Verification

What the bootstrap actually does

Common command paths

Basic usage

CLI

RL episode harness

Python SDK

TypeScript SDK

TypeScript runtime packages

Transport and host-boundary packages

Public E4 dossiers

Conformance, replay, and evidence

Typical replay workflow

Useful entrypoints

What the event log is for

TypeScript package map

Client surfaces

Docs navigator

Setup and onboarding

Contracts and kernels

Conformance and claims

Claim boundaries

Repo status

A few repo-specific observations

Where to go next

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages