Bernstein
Deterministically orchestrate parallel CLI coding agents with offline-verifiable run records.
What does this agent do, and when should you use it?
Bernstein is a deterministic orchestrator for CLI coding agents including Claude Code, Codex CLI, and Gemini CLI. It decomposes a goal into tasks, then uses plain Python for scheduling; coding tasks run in separate Git worktrees, while artifact-mode tasks receive separate working directories. It verifies work through concrete signals such as tests, file existence, linting, and type checks before merging verified code into the main branch. Every run writes a lineage spine and replay journal, while BERNSTEIN_AUDIT=1 enables an HMAC audit chain and receipts that can be checked offline. The project exposes a CLI, live TUI, web UI, MCP server mode, YAML workflows, and an air-gap installation profile.
bernstein init creates a .sdd/ workspace and bernstein.yaml. With bernstein -g "...", Bernstein decomposes a goal into tasks with roles, file ownership, and completion signals, calls configured CLI agents inside per-task Git worktrees, and gates results on tests, file existence, linting, and type checks before merging them. bernstein run plan.yaml executes declarative multi-stage plans containing agent, command, and loop nodes. It writes run records to the replay journal and lineage spine; bernstein replay latest --verify, bernstein lineage verify <run_id>, and bernstein audit verify recompute recorded state. bernstein verify run creates a portable Ed25519-signed run receipt, and bernstein verify receipt verifies that receipt from the file alone.
- An engineering team running Codex CLI, Claude Code, or Gemini CLI in parallel against one repository can give each coding task its own Git worktree instead of sharing mutable files by default.
- A security, compliance, or review team that needs to inspect automated changes after execution can enable BERNSTEIN_AUDIT=1 and validate the audit chain and signed run receipts offline.
- A development lead with an explicit task DAG who does not want model-based planning can execute a YAML plan directly with bernstein run plan.yaml.
- A maintainer investigating where an automated run failed can use bernstein audit diagnose <run_id> --signal gate --sign-key KEY to produce a signed diagnostic receipt.
- A team deploying coding automation in an isolated environment without a third-party data plane can use its file-based state and air-gap installation profile.
What are this agent's strengths and limitations?
- The coordination loop uses plain Python rather than an LLM, which the project uses as the basis for replayable task graphs and deterministic runs.
- Coding tasks are isolated by default in one Git worktree per task and are checked through merge gates such as tests, linting, and type checks.
- The lineage spine and replay journal are always written; optional HMAC audit chains and Ed25519-signed run receipts support offline verification.
- It supports more than 40 CLI-agent adapters, a generic --prompt wrapper, local file-based state, and an air-gap installation profile.
- It requires Python 3.12+, Git, a shell environment, and a separately installed and configured CLI coding agent.
- Its default isolation relies on Git worktrees; disabling worktrees causes tasks to run in the shared checkout.
- Goal decomposition still makes one LLM call; the determinism claim applies to the subsequent coordination and replay flow.
- Cloudflare Workers execution with R2 workspace synchronization is experimental, and the hosted api.bernstein.run service is not yet available.
How do you install or deploy this agent?
The documented runtime requires Python 3.12+ and Git. Install with:
pipx install bernstein
Then initialize the target project:
bernstein init
You must also install a supported CLI coding agent on the machine. The README names Claude Code, Codex CLI, and Gemini CLI among others; bernstein integrations list --installed shows what is available locally. The supplied material does not document credential setup for individual agents.
How do you use this agent?
From an initialized project, start with:
bernstein -g "fix the failing test in tests/test_foo.py"
Use bernstein live to watch progress. For an existing plan file, run:
bernstein run plan.yaml
To preserve an auditable record, run:
BERNSTEIN_AUDIT=1 bernstein -g "fix the failing test in tests/test_foo.py"
Then validate recorded state with bernstein replay latest --verify and bernstein lineage verify <run_id>.