Bernstein

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.

Bernstein is a deterministic Python scheduler that runs a crew of CLI coding agents (Claude Code, Codex, Gemini CLI, and 40 more) against a single goal in parallel git worktrees, with an HMAC-signed audit chain over every step.

at a glance

• 46 CLI agent adapters: 43 third-party wrappers, 2 leaf-node delegators, plus a generic --prompt wrapper. Source of truth: the supported agents table below.

• HMAC-SHA256 audit chain per RFC 2104, one record per scheduling decision, tamper-evident. Operator guide: docs/security/audit-log.md.

• Bearer-token task server authenticates the manager and every worker. Per-session zero-trust JWT in .sdd/runtime/agent_tokens/, legacy BERNSTEIN_AUTH_TOKEN fallback, opt-out via BERNSTEIN_AUTH_DISABLED=1. Flow + diagnostics: docs/security/manager-auth.md.

• Signed agent cards use detached JWS (RFC 7515 §A.5) over RFC 8785 (JCS) canonicalization, with Ed25519 / EdDSA keys. Code: src/bernstein/core/security/agent_card_signer.py.

• Per-artefact lineage records every adapter file write, without per-adapter opt-in, as one Merkle-chained, HMAC-tagged entry in an always-on lineage spine (.sdd/lineage/<run_id>/spine.jsonl). The chain head hash is the run's artifact-provenance identity. CLI: bernstein lineage verify <run_id> (recompute the chain, distinct NO ENTRIES status for empty runs) and bernstein lineage replay <run_id>.

• Content credentials: a C2PA 2.2 manifest for any produced artifact is a deterministic projection of that artifact's lineage-spine subtree, signed with the install-identity key so one attestation root covers both who ran it and what was produced. Stripping the spine makes the manifest unproducible, not merely unsigned. Watermark/fingerprint soft-binding layers are pluggable. CLI: bernstein credential emit <artifact> --run-id <run_id> and bernstein credential verify <artifact>.

• Tamper-evident memory: every cross-session memory write is an append-only, HMAC-tagged chained record attributing a claim to an actor at a time (entry_hash = H(prev, source_hash, actor, claim, model, timestamp, ...)), stored per identity scope (user / agent / run / app) under .sdd/memory/chain/<scope>/<namespace>.jsonl and anchored to the lineage spine that produced it. Forgetting appends a signed tombstone rather than deleting, so the original stays provable. CLI: bernstein memory verify --scope <s> --namespace <ns> (proves a fact was written by the claimed actor and never edited), bernstein memory why <fact> ... (returns the originating run and step), and bernstein memory forget <entry_hash> ....

• Always-on replay journal: every run records into one Merkle-chained event journal (.sdd/runs/<run_id>/journal.jsonl) whose head hash is the run identity; no on/off flag, BERNSTEIN_REPLAY_RETENTION caps disk. Non-determinism surfaces as a hash mismatch: bernstein replay <run_id> --verify recomputes the head and reports the exact first divergent step, and bernstein replay <run_id> --from-step N rebuilds deterministic state. The journal head is sealed into the lineage spine so replay identity and artefact provenance share one root.

• Compaction receipts: every context compaction of a long-running worker is validated mechanically (code blocks and error text must survive) and recorded as an HMAC-chained receipt. CLI: bernstein compaction log --task <id>. Operator guide: docs/operations/context-compaction.md.

• Deterministic scheduler: zero LLM in the coordination loop. Plain Python decides who runs, where, with what budget. Replay yesterday's plan, get yesterday's task graph.

• Cost-aware scheduling (USD budgets, pools, batch and cache policies): USD ceilings per task / run / day are enforced before dispatch against a hash-pinned, config-overridable price table (no network lookup in the scheduling loop). Every budget decision is a pure function of (price table, spend ledger, caps), so two operators with the same ledger reproduce byte-identical decisions; a halt is a sealed receipt naming the exact policy inputs (price_table_hash, ledger_state_hash, policy_hash) and the projected overrun, anchored in the lineage spine and mirrored into the audit chain (cost.dispatch_receipt). bernstein cost policy verify <decision_hash> recomputes the decision from the stored bytes and re-checks the spine anchor offline; a forged admit or zeroed overrun fails like a tampered chain entry. Usage is attributed to named pools (api, subscription) with independent caps, and bernstein cost policy preflight surfaces pool exhaustion before a run starts rather than mid-run. Batch dispatch and cache-window fan-out (one warm-up call primes a shared prompt prefix for M cache-hitting workers) are gated on a declared adapter capability map -- refused, never faked, on an adapter without the surface, and cache windows default off. bernstein doctor flags a stale price table.

• Signed OTel span projection: the OpenTelemetry GenAI export is a deterministic projection of the run event journal rather than random-id telemetry. Every span id is derived from the journal entry hash it projects, each span carries bernstein.journal.entry_hash, and the whole span set is signed with the install identity. Two replays export a byte-identical trace, a tampered span breaks the entry-hash binding, and the local JSONL store emits even with no OTLP endpoint set. CLI: bernstein trace project <run_id> and bernstein trace verify-projection <run_id>.

• Verifiable spending mandates: when an agent spends against an external service, the signed intent, the tool calls it authorized, and the settlement reference become one journal-anchored consent receipt binding {mandate_hash, authorized_tool_calls_hash, settlement_ref, journal_entry_hash}, so "this payment was authorized by this exact intent" is provable offline. AP2-style Intent and Cart mandates are signed and revocable; per-task spend caps are enforced by the cost ledger and a cap breach is refused; revocation appends a signed entry so subsequent actions are refused. The authorized action set is a deterministic projection of (mandate, state, time), and the HTTP 402 pay-and-retry settlement (x402 / AP2 shapes) is bound into the receipt so decision-to-pay and settlement cross-verify. CLI: bernstein mandate emit, bernstein mandate verify <mandate_hash> (proves the action was authorized by the recorded intent), and bernstein mandate revoke <mandate_hash>.

• Journal-anchored native subagent delegation: the deterministic scheduler keeps the coordination plan and delegates each leaf's mechanical execution to a native subagent (Claude Code, Codex) with per-agent model / effort / tools / background / batch settings. Each native structured result is schema-validated at the worker boundary (hallucinated keys and missing fields rejected) and anchored into the run event journal as a subagent.delegation entry carrying a replay-invariant node hash plus the result content hash. The outer DAG is a pure function of the plan, so it replays byte-identically even when inner execution is stochastic; non-interactive fan-out runs on the batch tier and its discount plus prompt-cache reads are attributed in the spend ledger.

• Stateless MCP core: the open stateless MCP protocol drops the initialize handshake and Mcp-Session-Id, so any request can land on any server instance and the protocol no longer provides cross-call ordering. Bernstein carries client capabilities in a per-request _meta field, emits W3C Trace Context (traceparent/tracestate/baggage) whose span id is derived from the call's content hash and trace id from the run root hash (two replays emit byte-identical _meta), and resolves the deprecated Sampling in-orchestrator with no LLM callback into the client. An InputRequiredResult retry base64-encodes its requestState so a different server instance resumes with no shared session memory. Each call is an ordered entry in the run event journal with its content-derived span id and is anchored into the HMAC audit chain, so cross-call continuity is chain-anchored rather than session-anchored; a cache hit references the content hash of the run that produced it. Deprecated Roots/Sampling/Logging stay behind a 12-month compatibility shim.

• Attested PR review receipts: a review run emits one signed receipt binding the issue body, the plan, the run journal head (every executed tool call), and the diff into {issue_hash, plan_hash, journal_head, diff_hash, findings, verdict}, signed with the install's Ed25519 identity and anchored in the review lineage spine, so "this PR was reviewed against this ticket without operator override" is provable offline. bernstein review-receipt verify --pr <url> recomputes issue_hash and diff_hash from the PR inputs and checks the signature and spine anchor; a tampered diff fails because diff_hash no longer matches. Autofix runs a reviewer finding's fix in an isolated git worktree, runs the gate, and emits a second receipt linking finding to fix-commit to test-result. The tracker comment is a projection of the receipt (short verdict + verify command), never the receipt body.

• Verifiable governance (RBAC, budgets, seats): for teams, every access check, budget check, and per-seat attribution is a deterministic projection over the signed lineage spine rather than mutable, separately-logged database state. Each decision is a signed, anchored record binding {subject, action, verdict, inputs_hash, journal_entry_hash}: a denied action writes a signed deny record and a budget breach a signed refuse that blocks the action. IDP groups map to roles via signed role bindings, and per-profile spend caps are enforced against per-subject spend recomputed from the cost ledger (never a stored counter). bernstein governance verify <run> re-resolves and re-projects every recorded access and budget decision from the presented bindings and ledger and confirms the recorded verdicts; a tampered verdict, a widened permission binding, or a diverged ledger fails the check. Two replays of a governance-gated run produce byte-identical decision records.

• Audited webhook node: drop Bernstein into a no-code builder or event bus as the one node that leaves a verifiable record. An inbound webhook is verified per Standard Webhooks (webhook-id / webhook-timestamp / webhook-signature), then writes a signed receipt binding {event_hash, source, journal_root} and seeds a run journal whose root references the event hash; on completion the outbound webhook carries a signed receipt binding {result_hash, journal_head}, so the returned result is provably the projection of the executed run. Retry/backoff replays the same inbound event idempotently without spawning a duplicate run, and an invalid inbound signature is rejected before anything is written. bernstein webhook verify <event_id> recomputes the inbound event hash and the outbound result hash against the journal, re-checks both Ed25519 signatures offline, and re-anchors both receipts against the webhook-node lineage spine; a tampered receipt, spine, or journal fails.

• Journal-anchored stall escalation receipts: when a worker stalls, it leaves a signed receipt that fixes the exact failure window by binding the last N entries of the run's canonical event journal by their Merkle hash, references an f03 fork point for resume, and recommends a deterministic action (resume / escalate / park). bernstein escalation verify <id> reconstructs the same trailing window from the journal, walks the journal's Merkle chain, and confirms every bound entry hash matches; tamper one journal entry inside the window and the reconstruction diverges. The receipt reconstructs offline from the journal alone, so an operator can hand it to a postmortem and get cryptographic certainty about exactly what happened before the stall. The TUI/web supervisor surfaces the receipt as a projection (stall reason, recommended action, resume fork point, spine anchor), never the signature or raw window hashes.

• Typed activity boundary for any modality: the deterministic scheduler is validated for coding agents, but the same control plane runs research, browser/computer-use, data, and ops agents behind one typed boundary. Every modality returns an ActivityResult -- {artifact, artifact_hash, evidence_set_hash, terminal_state, reason_code} -- so the scheduler keeps the agent an opaque stochastic activity behind a hash-in / hash-out contract. A research activity content-addresses every fetched page at fetch time; a browser activity records an observation hash (screenshot / DOM snapshot) per decision step; the scheduler pins the evidence_set_hash into the run event journal as one activity.result entry, so a replay reattaches byte-identical evidence and refuses on any tamper. A malformed result is rejected at the boundary with a typed refusal before anything is journaled, and the scheduler refuses to add a stage whose evidence_set_hash equals a prior stage's (no new exogenous signal), logging the refusal. Each crossing is mirrored into the HMAC audit chain carrying only hashes, never the artifact body. A role declares its modality via agent_kind in the team manifest (default coding); bernstein activity verify <run> walks the journal, recomputes each evidence_set_hash, and reattaches the content-addressed evidence to prove the run across modalities. Data / ops modalities (deterministic-plan vs side-effecting split, signed input/output artifacts) build on the same substrate and are documented follow-ups.

• Signed A2A message receipts: Bernstein already signs A2A capability cards, but the cross-agent task messages themselves were not attestable. Now every inbound/outbound A2A v1.0 message is a signed lineage receipt binding {message_hash, peer_card_fingerprint, task_uuid, journal_entry_hash}, signed with the install's Ed25519 identity and anchored in the message-receipt lineage spine, so a reviewer can prove a cross-agent call happened with the exact inputs claimed without trusting either agent's logs. The A2A task lifecycle (submitted / working / input-required / completed / failed / canceled) maps 1:1 to journal terminal states with reason codes, using task_uuid as the trace root. An inbound peer card is verified against its issuer domain and cross-checked against the operator's trusted-issuer set (an untrusted card is rejected), and each inbound peer task runs in its own git worktree so no two collaborations share mutable state. bernstein interop a2a verify-thread --from-thread <task-uuid> recomputes every receipt binding, re-checks each Ed25519 signature offline, verifies the spine, and re-anchors each receipt against it, proving the visible cross-agent thread equals the executed actions; a tampered receipt, spine, or journal fails.

• Verification evidence bundles: "done" was a status plus logs; the artefacts that prove a task passed died with the worktree. Now a task declares evidence producers in its spec ({name, kind, command, required} -- test command, coverage, lint, an optional screenshot/recording for web-facing work) that run at gate time. Each output is stored content-addressed under a per-blob size cap with a gc that drops blobs no live bundle references, then bound into one signed EvidenceBundle whose canonical bytes are anchored in the evidence lineage spine and mirrored into the HMAC audit chain as an evidence.bundle event -- the bundle is the receipt, not a log beside it. Required producers gate completion; an advisory producer's failure attaches a failure record without blocking. Media evidence additionally flows through the C2PA content-credentials support, so a tampered screenshot fails its hard-binding check. Deterministic producers regenerate byte-identical bundle hashes, signatures, and spine anchors on replay. bernstein evidence show <task> renders a bundle and bernstein evidence verify <task> recomputes it offline; bernstein audit verify covers bundle integrity too, so a tampered evidence file is named and fails exactly like a tampered chain entry. PRs carry an evidence-summary block linking the bundle so review happens against sealed proof rather than rerun-and-hope.

• In-process verification gates: verification used to happen only after a worker finished -- the scheduler inspected results and re-dispatched on failure, paying a full round-trip for every miss. Now a gate-capable adapter (Claude Code) enforces the same policy the moment a worker believes it is done, inside the session, before the turn ends. At spawn the task's owned_files become a write allowlist and its required evidence_producers a completion check, persisted to .sdd/runtime/hook_gate/<session>.json; the adapter injects two blocking hooks that shell out to bernstein hook-gate check. A Stop hook runs the required verification in-session and refuses to end the turn while it fails; a PreToolUse matcher refuses an out-of-scope write (realpath-contained, so a .. traversal or an in-scope symlink resolving outside the worktree is refused). Every recordable outcome -- a blocked completion or a refused write -- is sealed as an EvidenceBundle and mirrored into the HMAC audit chain, reusing the verification-evidence schema verbatim: a verifier cannot tell from the schema whether the gate fired in-process or scheduler-side. The trust model stays explicit -- in-process hooks are defence in depth and a cost optimisation; the scheduler-side gate remains authoritative and runs regardless -- so an adapter with no blocking hook surface injects nothing and degrades to that gate with no policy weakening.

• Durable work ledger (crash-safe, machine-portable resume): run state used to die with the host -- a crash mid-run was recoverable on the same machine, but an in-flight goal could not move to another box, be handed to a colleague, or survive a reimage. Now every task-graph transition (run.open, task.scheduled/started/completed/failed, run.resumed) appends to a hash-chained JSONL ledger under .sdd/runtime/ledger/<run-id>/, using the same canonical-JSON hashing contract as the per-step replay journal: each entry links its predecessor's hash, ts stays metadata, and the redaction layer scrubs every payload string before the entry is hashed, so secrets never become portable. bernstein ledger anchor <run> verifies the chain and publishes it -- chunked, with a deterministic tree identity -- to a dedicated git ref (refs/bernstein/work-ledger/<run-id>) that travels with the repo and is mirrored into the HMAC audit chain as a work_ledger.anchor event. On any clone, bernstein ledger fetch <run> + bernstein ledger resume <run> verify the chain end to end, rebuild scheduler state by deterministic replay (byte-identical projection for the same chain), and hand the in-flight frontier to the resume watcher; a crash mid-write degrades to the last verified entry, a tampered entry fails with its exact position named, and two divergent resumes of the same ledger are detected at the fork entry and refused, never silently merged. bernstein ledger gc <run> squashes anchor history so long runs do not bloat the repo. The ledger is the shared resumable-state substrate: schedulers and long-horizon runners build on it instead of inventing new state files.

• Detached run service (submit, disconnect, reattach later): a run used to be tied to the invoking terminal and one machine's uptime -- closing the laptop or losing an SSH session killed the scheduler even though all run state was recoverable, so multi-hour goals needed tmux discipline. Now bernstein run-service submit "<goal>" --task <id>... opens a run on the durable work ledger and spawns a session-detached supervisor that owns execution and survives the terminal; the daemon is a projection of the ledger, not a separate state store. bernstein run-service attach <run> reattaches from any shell and, before rendering live progress, proves the current ledger head is a forward extension of the head last seen -- that continuity proof is the reattach artefact, so an operator can prove nothing happened off the record while they were away. Every lifecycle boundary (submit, detach, reattach, daemon restart, complete) appends a signed run.lifecycle receipt to the HMAC audit chain binding the ledger head; a supervisor killed mid-run recovers the ledger tip on restart and resumes with zero lost completed tasks (a hard-kill chaos test proves it in CI), and bernstein run-service verify <run> re-checks the audit chain, the ledger chain, and every continuity boundary offline. Off-host execution ships too: bernstein run-service submit --backend ssh runs each task on another host over ssh in its own isolated remote git worktree (one branch per task), appends a signed run.ssh_task receipt binding that worktree so an offline verifier can prove per-task isolation across the ssh boundary, resumes on the ssh backend from the ledger tip with zero lost completed tasks after a kill, and resolves any injected credentials from the credential vault only (--ssh-secret ENV=PROVIDER, never the ledger or the receipts); bernstein worker remains the cluster fan-out.

• SPIFFE-compatible workload identity: operators standardizing on SPIFFE workload identity saw a Bernstein fleet as unidentified processes and had to keep a parallel identity system beside the one their platform already ran. Now the Ed25519 install identity and each agent card map onto a deterministic SPIFFE ID (spiffe://<trust-domain>/bernstein/<install>/<agent>, where <install> is a stable fingerprint of the install public key), so two operators derive the same id for the same install and agent, and a verifier re-derives it later. When a SPIRE agent is present (optional bernstein[spiffe] extra), the X.509-SVID it issues is bound to a card by a receipt: bind_svid_to_card re-derives the SPIFFE ID, refuses any SVID whose id disagrees, stamps the reference onto the card, and appends a spiffe.svid_binding event into the HMAC audit chain carrying the binding's content hash. The binding is the receipt, not a log beside it -- strip the chain and the mapping loses its meaning. bernstein spiffe id derives the id offline; bernstein spiffe verify-binding <binding.json> --install-key <pem> --trust-domain <td> --audit-dir <dir> re-derives the id from the install key and proves the card-to-SVID binding against its chained receipt, so a tampered binding fails with its content hash no longer matching. The same SVID material projects onto the existing cluster mTLS config, so the task server enforces mutual TLS through the path it already uses. Without the extra the self-contained Ed25519 path stays the default and every existing flow is unchanged.

• Tournament runs (parallel attempts, deterministic selection): for a hard task a single attempt often lands mediocre, and operators used to re-run the task by hand and eyeball diffs, leaving no trace of why one attempt won. Now a task can declare attempts: N with scripted evaluators (test pass rate, lint status, coverage delta, mutation score, an arbitrary command); the scheduler fans out N sibling attempts in isolated worktrees with byte-identical inputs, and the winner is a pure function of the evaluator outputs with a stable attempt-hash tie-break -- no model call in the decision path. The artefact the operator sees is the proof: a signed, spine-anchored TournamentReceipt that names every attempt hash, every evaluator output, every score, the winner, and the lineage edges (one chosen, the rest sibling). Each attempt is recorded as a lineage sibling, and the selection is mirrored into the HMAC audit chain as a tournament.selection event. bernstein tournament show <task> renders a receipt and bernstein tournament verify <task> recomputes it offline -- it replays the deterministic scorer over the recorded outputs, so a tampered score or a hand-picked winner diverges from the replay and fails; bernstein audit verify covers selection integrity too. Fan-out is gated on the task's existing per-ticket budget ceiling, so it aborts with a clear error before spawning when projected spend would breach the cap, never silently multiplying cost.

• Spec-to-task-graph pipeline with requirement-hash lineage: teams that write specs first had no supported path from a requirements document to a gated task graph -- operators pasted specs into the goal prompt and hoped decomposition landed, the decomposition was not reviewable before tokens were spent, and after the run nothing could answer "which requirement produced this artefact". bernstein plan compile <spec> closes that gap with a three-stage pipeline holding at most one model call: draft extracts EARS-shaped acceptance lines into a content-addressed requirement set, approve binds the requirement-set hash into the HMAC audit chain as a spec.requirement_set receipt (the plan-approval gate for the spec), and compile turns the approved set into a task graph as a pure, model-free transformation. Each task node is content-addressed over the requirement lines it implements and nothing else, so the same approved set always compiles to a byte-identical graph (graph_hash is reproducible), every node carries at least one requirement hash (so every artefact traces back to spec lines through lineage), and editing one requirement re-plans only that node while every unaffected node keeps its exact identity -- the diff is a plain set difference over content-addressed node ids. The receipt is the artefact: a verifier can prove offline that a graph was compiled from the requirement set the operator signed off on, and any post-approval edit to a requirement line breaks the chain.

why this exists

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.

install in 30 seconds

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

See installed integrations: bernstein integrations list --installed.

sponsor

If Bernstein routed a model that saved you a Claude bill, $25 covers a month of my coffee.

github.com/sponsors/chernistry

who this is for

Specific shapes where the value lands:

• engineering teams running >=3 CLI coding agents in parallel: each agent gets its own git worktree, the merge queue serialises landings, no race conditions
• operators running compliance-sensitive workflows: every routing decision is plaintext, the audit log is HMAC-signed and tamper-evident, no SaaS hop, no third-party data plane
• platform teams that need an audit log of agent decisions: the orchestrator writes one row per scheduling decision, you can grep it
• anyone burning more than $1k/mo on coding agents who wants determinism: you can replay yesterday's plan and get yesterday's task graph
• forward-deployed engineers dropping into a client repo: credentials stay in your env, not the client's; agents you spawn are whichever CLI tool the client already trusts

If you nodded at two of those bullets, this fits.

who this is NOT for

• "I want one pair-programmer to chat with about my code": a single CLI agent is fine. Bernstein adds orchestration overhead you don't need.
• prototypes where merge gates are overkill: the lint/types/tests/cross-model-review pipeline is value when the cost of a bad merge is real, friction when you're throwing the repo away on Friday.
• non-coding tasks (research, writing, data analysis pipelines): Bernstein wraps CLI coding agents specifically, not generic LLM workflows.
• anyone who wants a SaaS wrapper with a credit-card form: Bernstein is on-prem only by design.
• teams that need a vendor with a support SLA and a contract: solo open-source project. GitHub issues are how support happens.
• research-shape "let the agents collaborate emergently" use cases: the deterministic scheduler is a hard wall there.

how it compares

Closest neighbours in this category live in docs/compare/README.md. What Bernstein does well is the auditability surface: HMAC-chained audit, signed agent cards, per-artefact lineage, air-gap deploy profile, plus the widest CLI adapter coverage.

what is this, in one paragraph

You tell Bernstein what you want built. It splits the work across several AI coding agents, runs them in parallel inside isolated git worktrees, records every handoff in an HMAC-SHA256-chained audit log (RFC 2104), runs the tests, and merges the code that actually passes. File-based state (.sdd/), per-agent credential scoping, signed audit trail.

other install methods

curl -fsSL https://bernstein.run/install.sh | sh        # macOS / Linux one-liner
irm https://bernstein.run/install.ps1 | iex             # Windows PowerShell
pip install bernstein                                   # pip
uv tool install bernstein                               # uv
brew tap chernistry/tap && brew install bernstein       # Homebrew

See the full install matrix for dnf copr, npx, optional extras, and the wheelhouse path for air-gapped sites.

why the scheduler is plain Python

Most agent orchestrators use an LLM to decide who does what. That is non-deterministic and burns tokens on scheduling instead of code. Bernstein does one LLM call to break down your goal, then the rest (running agents in parallel, isolating their git branches, running tests, routing retries) is plain Python. Every run is reproducible. Every step is logged and replayable.

No framework to learn. No vendor lock-in. Swap any agent, any model, any provider.

What you see while it runs:

$ bernstein -g "Add JWT auth"
[manager] decomposed into 4 tasks
[agent-1] claude-sonnet: src/auth/middleware.py  (done, 2m 14s)
[agent-2] codex:         tests/test_auth.py      (done, 1m 58s)
[verify]  all gates pass. merging to main.

YAML workflow manifests (optional)

When bernstein run -g "<goal>" is too coarse-grained, bernstein workflow runs a declarative DAG of agent / command / loop nodes. Manifests are plain YAML, validated up-front, dispatched through the same AgentSpawner the rest of Bernstein uses.

bernstein workflow list                          # bundled + user-installed
bernstein workflow run idea-to-pr -g "Add JWT auth"
bernstein workflow init my-flow                  # scaffold a starter manifest
bernstein workflow validate path/to/flow.yaml

Stock workflows shipping in the wheel: idea-to-pr, refactor-with-tests, security-review, doc-update, dependency-bump, hot-fix. Loop nodes re-fire until a bash predicate exits 0. fresh_context: true mints a new agent session per iteration. Per-step CLI/model routing: docs/workflows/per-step-routing.md.

use cases

• forward-deployed engineering: drop the crew onto a client repo when you arrive, take it with you when you leave.
• self-evolving projects: point Bernstein at its own repo and let it execute the backlog (this codebase is one).
• CI fleets: run a crew of agents in parallel on PRs, with per-agent credential scoping and signed audit trail.
• air-gapped deployment: install from a signed wheelhouse, run with --profile airgap to deny outbound by default. See Air-gap installation.

supported agents

Bernstein auto-discovers installed CLI agents. Mix them in the same run. Cheap local models for boilerplate, heavier cloud models for architecture.

46 CLI agent adapters: 43 third-party wrappers, 2 leaf-node delegators, plus a generic wrapper for anything with --prompt.

Any adapter also works as the internal scheduler LLM:

internal_llm_provider: gemini            # or qwen, ollama, codex, goose, ...
internal_llm_model: gemini-3.1-pro

Local runtimes (ollama, LM Studio, MLX servers) plug in as a first-class worker tier: declare a local_endpoints profile, route low-stakes roles (lint, test-writing, triage, doc sweeps) to it, and certify the endpoint with bernstein doctor --endpoint <url>. Certification is a signed, audit-chain-anchored receipt -- merge-critical roles refuse an uncertified endpoint at config validation. See Local endpoints and examples/local-fleet.

quick start

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 stop                    # graceful shutdown with drain

For multi-stage projects, define a YAML plan:

bernstein run plan.yaml           # skips LLM planning, goes straight to execution
bernstein run --dry-run plan.yaml # preview tasks and estimated cost

web UI

v2.0.0 ships a minimal web UI (operator-requested; UI is a side surface, core orchestrator is the priority).

bernstein gui serve               # http://127.0.0.1:8052/ui/
bernstein gui serve --dev         # expects `npm run dev` on :5173
bernstein gui serve --minimal     # skip the full /api/v1/* surface

The Vite bundle is committed under src/bernstein/gui/static/, so wheel installs work without a Node toolchain. Surface tour + per-task drawer: docs/web-ui.md.

The dashboard requires a credential: on a loopback bind an operator token is issued and printed at startup; a non-loopback bind refuses to start until one is configured. Issue read-only (viewer) or read-write (operator) tokens with bernstein auth dashboard-token issue --principal <name> --scope viewer; every grant and write authorization is a signed governance record (bernstein governance verify dashboard-auth).

how it works

Bernstein runs a four-stage pipeline per goal:

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 task. 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.

The orchestrator is a Python scheduler, not an LLM. Scheduling decisions are deterministic, auditable, and reproducible. Every step writes a record to the HMAC-chained audit log (.sdd/audit/YYYY-MM-DD.jsonl) per RFC 2104.

cloud execution (Cloudflare)

bernstein cloud runs agents on Cloudflare Workers with R2-backed workspace sync. See docs/cloudflare/.

bernstein cloud login      # authenticate with Bernstein Cloud
bernstein cloud deploy     # push agent workers
bernstein cloud run plan.yaml  # execute a plan on Cloudflare

capabilities

Bernstein ships parallel execution + worktree isolation + a janitor that gates merges on tests/lint/types, signed lineage records, MCP server mode, an HMAC-SHA256 audit chain, and 45 CLI adapters out of the box. Pluggable sandbox backends (worktree, Docker, E2B, Modal), pluggable artifact sinks (local, S3, GCS, Azure Blob, R2), progressive-disclosure skill packs, and a lethal-trifecta capability gate round it out.

Full feature matrix: docs/reference/FEATURE_MATRIX.md. Recent features: docs/whats-new.md.

regulatory anchors

Regulatory mappings (EU AI Act Article 12, SOC 2 CC4/CC7, DORA / NIS2, OWASP ASI06, RFC 2104/7515/8785/8037/7636/8707) live in docs/compliance/. These are mappings, not certifications.

operator commands

Highest-value commands; full list in docs/operations/commands.md.

retrieval & caching: what's actually under the hood

Bernstein deliberately uses no neural embeddings, no vector databases, and no external embedding APIs. There are two retrieval/caching layers, both keyword/lexical:

• Codebase RAG (core/knowledge/rag.py): SQLite FTS5 with BM25 ranking and AST-aware chunking for Python files.
• Semantic cache (core/knowledge/semantic_cache.py): TF (term-frequency) cosine similarity over word counts, not learned embeddings.

If you need real semantic retrieval (vector DB, neural embeddings), wire it yourself via the retrieval role/skill in templates/; nothing in core performs vector search.

install

The one-liner scripts check for Python 3.12+, bootstrap pipx when it's missing, fix PATH for the current session, and install (or upgrade) bernstein. Script sources: install.sh · install.ps1.

optional extras

Provider SDKs are optional so the base install stays lean.

Combine extras with brackets, e.g. pip install 'bernstein[openai,docker,s3]'.

Editor extensions: VS Marketplace · Open VSX

security

• OpenSSF Scorecard. Weekly run via .github/workflows/scorecard.yml. Results uploaded to GitHub Code Scanning. Badge above.
• Fuzzing. ClusterFuzzLite config at .clusterfuzzlite/ plus a cifuzz-pr workflow (.github/workflows/cifuzz-pr.yml) provide an OSSF-recognized fuzzing harness on top of the existing Hypothesis property-test suite.
• Vulnerability disclosure. See SECURITY.md.

contributing

PRs welcome. See CONTRIBUTING.md for setup and code style.

support

If Bernstein saves you time: GitHub Sponsors.

Contact: forte@bernstein.run.

featured in

• Augment Code - 9 Open-Source Agent Orchestrators for AI Coding (2026); editorial roundup.
• nibzard/awesome-agentic-patterns; Bernstein cited as the production implementation of the "deterministic zero-LLM orchestration" pattern.
• Python Weekly; newsletter mention.
• Future Digest; cost-cutting playbook write-up.

cite

Machine-readable metadata lives in CITATION.cff (CFF 1.2.0); GitHub renders the "Cite this repository" button automatically. A Zenodo DOI will be minted on the next release.

license

Apache License 2.0

Alex Chernysh · GitHub · X · bernstein.run

Translations available in 11 languages: see docs/i18n/.