bernstein

"To achieve great things, two things are needed: a plan and not quite enough time." - Leonard 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.

deterministic multi-agent CLI orchestration

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

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 task runs in its own git worktree behind lint/type/test gates. Results stay checkable after the fact: an always-on lineage spine and replay journal, plus an opt-in HMAC-chained audit log (--audit) 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. An always-on lineage spine and replay journal record every run; an opt-in HMAC audit chain (--audit) adds receipts you verify offline. Non-determinism surfaces as a hash mismatch at the exact step, not a flaky re-run.
• Isolated by construction. Every task runs in its own git worktree behind lint/type/test merge gates — no shared mutable state between agents.
• Broad and local. 40+ CLI agent adapters plus a generic --prompt wrapper, an air-gap install profile, file-based state, Apache-2.0 — no SaaS hop, no third-party data plane.

The feature matrix is the exhaustive index.

full capabilities

• 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.
• 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>.
• 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. Provider-side context mutations (server-side compaction and similar opaque state) are recorded as content-addressed journal entries, so a change to what the model actually saw surfaces as divergence at the exact step instead of drifting silently; deterministic runs request suppression and fail loudly if a mutation arrives anyway.
• HMAC-SHA256 audit chain per RFC 2104, one record per scheduling decision, tamper-evident. Enabled with --audit, BERNSTEIN_AUDIT=1, or a compliance preset; off by default. Operator guide: docs/security/audit-log.md.
• 40+ CLI agent adapters, plus a generic --prompt wrapper for anything else. Source of truth: the supported agents table below.
• 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.
• 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> ....
• 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.
• 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>.
• Live OTLP streaming of journal-anchored spans: with BERNSTEIN_OTEL_ENDPOINT set, runs stream that same journal projection to any stock OpenTelemetry collector as journal entries append -- live spans carry the identical journ