bernstein

Purpose

Bernstein is an open-source governance layer for AI agents, with the core idea of "policy as code": users declaratively write rules (who can do what, what requires approval, what must be recorded), and Bernstein enforces them and generates verifiable records. It aims to solve problems that arise when running multiple coding agents in parallel, such as nondeterministic merges, opaque costs, and difficulty auditing after the fact.

Main Capabilities

• No LLM in the coordination layer: Scheduling uses pure Python, and runs are reproducible end to end. Replaying yesterday's plan yields yesterday's task graph.
• Inspectable after the fact: A replay journal records every run; an always-on lineage spine records every step with its lineage; an optional HMAC-chained audit log (set BERNSTEIN_AUDIT=1) generates receipts that can be verified offline. Nondeterminism shows up as a hash mismatch at the exact step, rather than as unstable reruns. The same applies to non-code deliverables: tasks can declare artifact contracts (reports, datasets, action logs, operational results), with completion conditioned on signed lineage receipts rather than git commits.
• Isolated by construction: Each coding task has its own git worktree and is placed behind merge gates; artifact-mode tasks get a working directory under .sdd/workspaces/. By default, agents do not share mutable workspaces; the only shared state is the task to-do list, which is claimed atomically. Stricter filesystem enforcement is optional and provided by the sandbox backend. If worktrees are disabled, all tasks run in a shared checkout.
• Broad and local: More than 50 selectable CLI agent adapters, plus a generic --prompt wrapper; file-based state, no SaaS relay, no third-party data plane.

Usage

Installation: pipx, pip, brew, dnf, npm, and Docker are all covered in the installation guide; air-gapped environments have a separate wheelhouse guide.

Declarative workflows: A single YAML file declares a run—stages, roles, dependencies, and the conditions under which nodes run. The scheduler executes it as pure Python; the file contents are not a prompt, and the model does not decide the next step.

Execution per node: Nodes are handled by agents in the roles allowed by the stageBody claim; role fences and approval gates are not affected by agent behavior within a task. Coding nodes complete after passing the merge gate in their own git worktree; artifact-contract-type nodes instead name deliverables (reports, datasets, scans, action logs) and use signed lineage receipts rather than commits as the completion condition. Same scheduler, same log, same offline verification, whether the task graph produces code, research, ops changes, or a mix of all three. Ready-made workflow graphs are located in .bernstein/scenarios/.

Audit verification: Run in audit mode, then verify the record. The log is written on every run; the lineage spine is always on.bernstein audit verify Only when BERNSTEIN_AUDIT=1 is set at runtime, a compliance preset is used, or bernstein run --audit is used is there a chain to inspect.--audit flag belongs to bernstein run; in the bernstein -g form above, set the environment variable.

Single-run receipt: Under a single Ed25519-signed subject, bind the log head, the lineage spine head (if the run wrote spine entries), and an optional audit chain interval, and embed the public key. A reviewer holding that file and the operator public key can confirm that the embedded actions and chain have not been altered: no HMAC key, no live .sdd/ directory, and on tampering exit with code 2 and point out the first divergent step.

Verifiability of evaluation numbers:bernstein bench run <suite> --reliability k(also written as bernstein eval --reliability k) runs each task k times under fixed coordination, then reports the pass^k lower bound (all k attempts must pass) and the pass@1 upper bound. Results are sealed in a signed receipt,bernstein bench reliability-verify can be recomputed offline, so a forged lower bound cannot pass verification.

Goal four phases:

1. Decomposition: The manager splits the goal into tasks with roles, owned files, and completion signals. One LLM call, then pure Python afterward.
2. Derivation: Agents start in isolated git worktrees, one per coding task; artifact-mode tasks get a plain working directory. The main branch stays clean.
3. Verification: The janitor checks concrete signals—tests pass, files exist, lint is clean, types are correct.
4. Merge: Verified work is merged into main. Failed tasks are retried or routed to another model.

Workflow command:bernstein workflow runs a declarative YAML DAG composed of agent, command, and loop nodes, supporting recovery after an interrupted run. Run state is checkpointed at each node to .sdd/runs/<run_id>/. On recovery, the manifest digest is verified at the start of the run, so spec changes are rejected rather than silently executing a different manifest.

Repository hygiene gating:bernstein readme-l10n verify fails PRs where translated READMEs drift from the English source (and points out stale sections),bernstein readme-l10n sync rebinds them after English edits.

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 others. The adapter index provides install commands for 30 of them.bernstein integrations list Enumerate all 56 onboarded integrations (from src/bernstein/adapters/registry.py, the single source of truth for parsing results). Of these, 54 are selectable agent adapters; the other two rows are a mock test stub and a self-hosted endpoint configuration. Any tool with a --prompt flag can be used through the generic wrapper. Agents can be mixed within the same run: cheap local models handle boilerplate, heavier cloud models handle architecture.bernstein integrations list --installed Show what is available on this machine.

Volunteer computing: Projects can mark issues as open to volunteers, and anyone can run them on their own machine without an account or coordinator. Projects declare in a volunteer.json manifest what tasks are allowed to do (sandbox backend, network allowlist, wall-clock and memory limits), and donors' own limits can only narrow, not widen, them. Receipts generated by completed tasks bind the result to the isolation decisions made when it ran. The donor guide covers running a worker and setting budgets, the project guide covers declaring manifests, and the threat model explains what each boundary does and does not protect. A one-click runner has not yet been released: the currently available subcommands are verify, browse, budget, verify-bundle, and hub.

When to use it

• Running multiple CLI coding agents in parallel and needing deterministic, reproducible coordination;
• Compliance or enterprise scenarios requiring after-the-fact auditing and verifiable evidence bundles;
• Governance of non-code deliverables such as research, documentation, and operational changes;
• Air-gapped/offline deployment;
• Scenarios where the project declares the isolation boundary and volunteers contribute compute.

Limitations

• Status is beta, maintained by an individual, under active development. Version numbers only count releases and do not indicate maturity—minor versions may change interfaces. Pin versions for any dependency; regressions are fixed quickly and can be reported via issues.
• The air-gapped installation configuration is included in the project, but the one-click volunteer runner has not yet been released.
• Only when auditing is enabled at runtime,bernstein audit verify is there a chain to inspect.
• Without --public-key pinning, inspection of the receipt file alone is only an integrity check—it proves the receipt is internally consistent, not who signed it; the verdict states this.
• Proving that a state is fully completed still requires an independent head/count seal.
• More details on charging, pricing, platform, etc. are not yet available in the materials.

License and attribution

Apache-2.0, free. The project name is based on Leonard Bernstein (American conductor and composer). Citation metadata is in CITATION.cff, and the project name is additionally covered by TRADEMARKS.md.