bernstein 3.14.159

"To achieve great things, two things are needed: a plan and not quite enough time." - Leonard Bernstein

deterministic multi-agent CLI orchestration

website · docs · install · first run · glossary · limitations · name policy · sponsor

简体中文 · 繁體中文

Status: beta. Solo-maintained, under active development. The version number counts releases, not maturity - minor versions may change interfaces. Pin the version for anything you depend on; regressions get fixed fast, file them.

Bernstein is a deterministic orchestrator for CLI coding agents (Claude Code, Codex, Gemini CLI, and 40+ more). Scheduling is plain Python - no LLM in the coordination loop - so runs are reproducible end to end. Every coding task runs in its own git worktree behind lint/type/test gates; artifact-mode tasks, which complete on a signed lineage receipt instead of a commit, get a plain working directory instead. Results stay checkable after the fact: an always-on lineage spine and replay journal, plus an opt-in HMAC-chained audit log (BERNSTEIN_AUDIT=1) with receipts you can verify offline. Air-gap install profile included. Apache-2.0.

at a glance

Four things set it apart; everything after is detail.

• No LLM in the coordination loop. Scheduling is plain Python, so a run is reproducible end to end. Replay yesterday's plan and get yesterday's task graph.
• Checkable after the fact. The lineage spine and replay journal record every run; the opt-in audit chain adds receipts you verify offline. Non-determinism surfaces as a hash mismatch at the exact step, not a flaky re-run. Non-code deliverables get the same treatment: a task can declare an artifact contract (report, dataset, action log, ops result) on a plan step, a backlog entry, or the task CLI and complete on a signed lineage receipt instead of a git commit.
• Isolated by construction. Each coding task gets its own git worktree behind merge gates; artifact-mode tasks get working-directory separation under .sdd/workspaces/. Under this default isolation there is no shared mutable state between agents; filesystem enforcement beyond that separation is opt-in, from the sandbox backends (disabling worktrees runs every task in the shared checkout).
• Broad and local. 40+ CLI agent adapters plus a generic --prompt wrapper, file-based state, no SaaS hop, no third-party data plane.

The full list is on the capabilities page; the feature matrix is the exhaustive index.

install in 30 seconds

pipx install bernstein
bernstein init
bernstein -g "fix the failing test in tests/test_foo.py"

pip, uv, brew, dnf, npm, Docker, and the air-gapped wheelhouse are covered in the install guide.

The recording above is a real run, and it ships with its own proof: the cast, the signed run receipt that exact run produced, and the public key that pins it live together in docs/assets/demo-run/. Verify the run you just watched, offline:

bernstein verify receipt docs/assets/demo-run/run-receipt.json \
    --public-key docs/assets/demo-run/run-receipt.pub.pem

CI re-verifies the committed receipt on every push — and proves a tampered copy fails — so the published evidence cannot rot into a decorative file. scripts/record_demo.sh regenerates the recording, receipt, and key from a fresh real run; nothing inside the terminal is synthesised.

A run in flight is watchable from either operator surface. Both read the same task API, so neither is a lagging mirror of the other.

bernstein live — the terminal dashboard	bernstein gui serve — the same run in a browser

prove a run

Determinism here is something you check, not something you take on faith. Run once with audit enabled, then verify what was recorded:

BERNSTEIN_AUDIT=1 bernstein -g "fix the failing test in tests/test_foo.py"
bernstein replay list                 # run ids recorded on disk
bernstein replay latest --verify      # recompute the journal head, name the first divergent step
bernstein lineage verify <run_id>     # recompute the always-on lineage spine
bernstein audit verify                # HMAC chain + Merkle seal (written because audit was enabled)
bernstein audit diagnose <run_id> --signal gate --sign-key KEY
                                      # name the exact step a failure entered the run, as a signed receipt
bernstein verify run <run_id> --signing-key-path key.pem   # sign one portable run receipt
bernstein verify receipt .sdd/runs/<run_id>/run-receipt.json  # verify it offline: file only

The journal and the lineage spine are written on every run. bernstein audit verify only has a chain to check when the run was started with BERNSTEIN_AUDIT=1, a compliance preset, or bernstein run --audit. The --audit flag belongs to bernstein run; on the bernstein -g form above, set the environment variable.

The run receipt binds the journal head and the lineage-spine head (plus, opt-in, an audit-chain range) under one Ed25519-signed subject with the public key embedded, so a reviewer holding the file and the operator's public key can confirm the recorded actions are exactly what executed - no HMAC key, no live .sdd/, exit 2 naming the first divergent step on tamper. With the file alone (no --public-key pin) the check is integrity-only: it proves the receipt is internally consistent, not who signed it, and the verdict says so. Details in deterministic replay.

The same checkability applies to evaluation numbers: bernstein bench run <suite> --reliability k (also spelled bernstein eval --reliability k) runs every task k times under fixed coordination and reports a pass^k floor (all k attempts must pass) alongside the pass@1 ceiling, sealed in a signed receipt that bernstein bench reliability-verify recomputes offline — a fabricated floor fails verification. Details: pass^k reliability floor.

how it works

Each goal moves through four stages:

1. Decompose. The manager breaks your goal into tasks with roles, owned files, and completion signals. One LLM call, then plain Python from there.
2. Spawn. Agents start in isolated git worktrees, one per coding task; an artifact-mode task gets a plain working directory instead. Main branch stays clean.
3. Verify. The janitor checks concrete signals: tests pass, files exist, lint clean, types correct.
4. Merge. Verified work lands in main. Failed tasks get retried or routed to a different model.

Why the scheduler is plain Python, and what that trades away: why deterministic.

everyday commands

cd your-project
bernstein init                    # creates .sdd/ workspace + bernstein.yaml
bernstein -g "Add rate limiting"  # agents spawn, work in parallel, verify, exit
bernstein live                    # watch progress in the TUI dashboard
bernstein run plan.yaml           # multi-stage plan: skip LLM planning, execute directly
bernstein stop                    # graceful shutdown with drain

The full operator surface (PR automation, schedules, chat bridges, the autofix daemon) is in operator commands.

Repository hygiene gates: bernstein readme-l10n verify fails a PR whose translated READMEs drifted from the English source (naming the stale section), bernstein readme-l10n sync rebinds them after an English edit. See readme-l10n.

supported agents

Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, Aider, Goose, Muse Code, OpenAI Agents SDK, Amp, Cody, Continue, Devin Terminal, Junie, Kilo, Kiro, AWS Q Developer, Ollama, OpenCode, OpenHands, Open Interpreter, gptme, Plandex, AIChat, Letta Code, Qwen, and more. The adapter index carries install commands for 30 of them; bernstein integrations list enumerates all 51 wired-in adapters from the registry in src/bernstein/adapters/registry.py, which is the single source of truth for what resolves; src/bernstein/adapters/use_cases.py carries the end-user copy for each one. Anything else with a --prompt flag works through the generic wrapper.

Mix agents in the same run: cheap local models for boilerplate, heavier cloud models for architecture. bernstein integrations list --installed shows what is available on your machine.

beyond the front page

Everything deep lives on the docs site:

why the name?

Bernstein is named after Leonard Bernstein, the American conductor and composer. The project orchestrates a crew of CLI coding agents the way Bernstein conducted the New York Philharmonic: every player on cue, the score deterministic, the conductor accountable for the result. He is the original orchestrator the project takes its name from.

i wrote bernstein because i was paying $400/month in claude bills running three coding agents in parallel and getting nondeterministic merges. Apache 2.0, solo maintained. Live stats: bernstein.run.

mentioned in

Listed in vinta/awesome-python, covered in Augment Code's open-source agent orchestrators roundup, cited by awesome-agentic-patterns as the production implementation of deterministic zero-LLM orchestration, featured in Python Weekly #742, and ranked as the orchestration layer in a ten-repo Claude Code agent-system breakdown.

contributing, support, license

PRs welcome; CONTRIBUTING.md has setup and code style. Security reports go through SECURITY.md. If Bernstein saves you time: GitHub Sponsors. Contact: forte@bernstein.run.

Citation metadata lives in CITATION.cff. License: Apache-2.0; the project name is covered separately in TRADEMARKS.md.

Alex Chernysh · GitHub · X · bernstein.run