# Bernstein

> 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. An always-on lineage spine and replay journal record what happened; an opt-in HMAC-chained audit log and signed receipts make results independently verifiable, offline if needed. Air-gap install profile included. Apache-2.0. Built by Alex Chernysh.

## What you get

State is file-based (`.sdd/`), so there is no server to provision. Per-agent credential scoping keeps each agent's keys out of the others' environments. Pluggable cloud sandboxes, cloud artifact sinks, progressive skill packs, and Cloudflare cloud execution are available on top of the local worktree default.

## Docs

- [Documentation](https://bernstein.readthedocs.io/): Full technical documentation
- [Architecture](https://bernstein.readthedocs.io/en/latest/ARCHITECTURE/): System architecture and design
- [Getting Started](https://bernstein.readthedocs.io/en/latest/GETTING_STARTED/): Installation and quickstart
- [Adapter Guide](https://bernstein.readthedocs.io/en/latest/ADAPTER_GUIDE/): Supported agents and how to add your own
- [API Reference](https://bernstein.readthedocs.io/en/latest/openapi-reference/): Task server REST API
- [Cloudflare Guide](https://bernstein.readthedocs.io/en/latest/cloudflare-overview/): Cloud execution on Cloudflare Workers
- [Configuration](https://bernstein.readthedocs.io/en/latest/CONFIG/): bernstein.yaml reference
- [CHANGELOG](https://bernstein.readthedocs.io/en/latest/CHANGELOG/): Release notes per version

## Site pages

- [Why Bernstein](https://bernstein.run/why-bernstein): Positioning vs LLM frameworks (CrewAI / LangGraph) and CLI orchestrators (Composio / emdash); the audit-grade wedge
- [Cost calculator](https://bernstein.run/cost): Token-bill estimator for a Bernstein run with the contextual bandit router enabled; shows the per-model cost band against an unrouted baseline
- [Adapter comparisons](https://bernstein.run/vs): Index of side-by-side feature matrices for every supported CLI agent (Aider, Claude Code, Codex, Cursor, Gemini, OpenAI Agents SDK, and more)
- [CLI quickstart](https://bernstein.run/cli-quickstart): Minimal walkthrough. Installing pipx, running the first task, reading the audit log
- [Ask the docs](https://bernstein.run/ask): DocsBot question surface backed by the readthedocs index plus blog content; cite-style answers with source chips
- [Sponsors](https://bernstein.run/sponsors): Public sponsors wall (GitHub Sponsors / OpenCollective integrations) and the sponsorship tier breakdown
- [Tools - agent.md bench](https://bernstein.run/tools/agent-md-bench): Free utility. Paste a project's agent file and get a token-cost estimate per supported model
- [Tools - orchestra picker](https://bernstein.run/tools/orchestra): Free utility. Pick a Bernstein agent line-up for a stack and budget combination
- [Benchmark - cli agent orchestrators](https://bernstein.run/benchmarks/cli-agent-orchestrators): Reproducible 10-task eval comparing Bernstein, Claude Squad, Conductor, Composio agent-orchestrator, and OpenCode. Operator-published scores; bernstein loses 4 of 10. Methodology and repro script linked.
- [RSS feed](https://bernstein.run/rss.xml): Blog updates

## Resources

- [GitHub](https://github.com/sipyourdrink-ltd/bernstein): Source code and issues
- [PyPI](https://pypi.org/project/bernstein/): Python package
- [npm](https://www.npmjs.com/package/bernstein-orchestrator): Node.js wrapper
- [Full Technical Reference](https://bernstein.run/llms-full.txt): Comprehensive 600+ line reference for LLMs
- [OpenAPI Spec](https://bernstein.run/openapi.yaml): REST API specification
- [Agent Card (A2A)](https://bernstein.run/.well-known/agent-card.json): A2A protocol manifest
- [MCP Server Card](https://bernstein.run/.well-known/mcp/server-card.json): MCP server discovery card
- [RSS Feed](https://bernstein.run/rss.xml): Blog updates

## Primitives

Canonical runnable examples for the four primitives an AI assistant needs to reason about Bernstein.

### Adapter (claude_code)

```yaml
# .sdd/bernstein.yaml
agents:
  - name: claude_code
    adapter: claude
    role: backend
    model: sonnet
```

### plan.yaml

```yaml
# plans/auth.yaml
name: "Add authentication"
stages:
  - name: api
    steps:
      - goal: "Implement /login endpoint"
        role: backend
        complexity: medium
  - name: tests
    depends_on: [api]
    steps:
      - goal: "Integration tests for /login"
        role: qa
```

Run with: `bernstein run plans/auth.yaml`

### MCP server

```bash
# Expose Bernstein as an MCP server (stdio transport)
bernstein mcp serve

# Or HTTP transport on :8765
bernstein mcp serve --transport http --port 8765
```

Exposed tools: `bernstein_run`, `bernstein_status`, `bernstein_tasks`, `bernstein_cost`, `bernstein_stop`.

### Worktree isolation

```bash
# Default: every task gets its own git worktree under .worktrees/
bernstein -g "refactor auth module"

# Bernstein creates .worktrees/<task-id>/ for each agent
ls .worktrees/
# task-001-backend-refactor-auth/
# task-002-qa-test-refactor/
```

Each agent commits to its own branch; merge queue serializes results into the trunk after quality gates pass.

## Blog

- [bernstein 3.x recap: deterministic replay, evidence bundles, tournament runs, and a run you can walk away from](https://bernstein.run/blog/v3-x-recap): The arc from 2.0 to 3.5.0, in one page. The 2.x line taught the orchestrator to do more. The 3.x line made each of those things carry its own proof: an always-on signed lineage spine, deterministic replay by default, content-addressed evidence bundles, a durable ledger that resumes on another machine, detached runs, tournament selection with no model in the decision path, cost-aware dispatch under USD caps, a run review board, SPIFFE identity, an MCP Tasks surface, a stateless chain-anchored MCP core, and provider-side context mutations recorded into the replay journal.
- [Running many agents on 2.16: the output-economy suite, safer summaries, and a lifecycle you can hold still](https://bernstein.run/blog/output-economy-and-agent-lifecycle): A walkthrough of what shipped across the 2.4 to 2.16 arc for operators running many agents at once: per-role response-style profiles, per-profile cost attribution, a three-arm cost-and-quality A/B harness, proactive context compaction with signed receipts, a credential-shaped-content gate on summaries, schema-enforced worker completion payloads, sha256-pinned team manifests, hold/release spawner control, per-agent run instrumentation, and the Windows adapter path fix.
- [bernstein 2.x recap: lineage, ten trackers, A2A capability cards, and a CI that started fixing itself](https://bernstein.run/blog/v2-x-recap): Thirteen releases since the 1.10 recap consolidated into nine themes: a per-artefact transparency log with Ed25519 signatures, ten tracker adapters from Jira to Plane, A2A capability cards, MCP client and server hardening, a Playwright sandbox for UI agents, a secrets broker, supply-chain coverage with SBOM and OSSF Scorecard, calibrated cost guards, and a web UI plus PWA in the wheel.
- [bernstein 2.0.0: a web UI ships in the wheel, CLI unchanged](https://bernstein.run/blog/v2-0-release): Bernstein 2.0 ships a FastAPI + React web UI inside the wheel. CLI and TUI surfaces are unchanged, configs do not move, agents and adapters keep working.
- [bernstein 1.10.x recap: agents.md sync, a2a, cost guards](https://bernstein.run/blog/v1-10-x-recap): five point releases in five days: agents.md cross-cli sync, runtime cost guards, a2a v1.0 signed agent cards, four new cli adapters.
- [Shipping the orchestrator onto someone else's box](https://bernstein.run/blog/orchestrator-on-someone-elses-box): On-prem deployment notes for Bernstein 1.10: cluster mTLS, signed lineage, air-gapped install, lethal-trifecta capability gate. Not an install guide.
- [We orchestrate the orchestrators now: Composio + ralphex adapters](https://bernstein.run/blog/orchestrate-the-orchestrators): Bernstein adapters for Composio's @aoagents/ao and umputun/ralphex. Leaf-node delegation, not deep meta-orchestration: each runs as a single agent in a plan.
- [A daemon that closes its own pull requests](https://bernstein.run/blog/autofix-daemon): How the Bernstein autofix daemon turns a red CI run on a Bernstein-opened PR into a fix commit. Capability gating and budget caps keep it from being a footgun.
- [bernstein 1.9.0: ACP bridge, CI autofix daemon, keychain creds](https://bernstein.run/blog/v1-9-release): ACP bridge so Zed can dispatch tasks, a daemon that closes its own pull requests, OS keychain credentials, sandboxed preview server with a public URL.
- [Four commands that take the glue out of multi-agent runs](https://bernstein.run/blog/operator-pack): Bernstein 1.8.14 ships pr, from-ticket, remote, hooks. The four shell snippets every multi-agent team ends up writing by hand, now built into the CLI.
- [Four commands that turn the orchestrator into a service](https://bernstein.run/blog/operator-commands): 1.8.15 ships a chat bridge, mid-run approval, a tunnel wrapper, and a daemon installer. Less script you sit next to, more thing you install once.
- [The install we should have shipped at launch](https://bernstein.run/blog/frictionless-install): Three months after launch Bernstein got a real curl | sh one-liner. It only happened because a community contributor picked up the issue we kept deferring.
- [orchestration primitive vs desktop ade: pick the right layer](https://bernstein.run/blog/orchestrator-vs-desktop-ade): multi-agent coding split into two shapes: orchestration primitives (bernstein, workz) vs desktop ades (emdash, conductor). when to reach for each.
- [getting started: first multi-agent claude code run in 5 min](https://bernstein.run/blog/getting-started): install bernstein, point it at claude code (or codex/gemini cli), run a goal in parallel, read the tui. five minutes if python 3.12 is ready.
- [community spotlight: april 2026 bernstein contributors](https://bernstein.run/blog/community-spotlight-april-2026): first community spotlight. contributors who shaped bernstein's architecture decomposition, adapter list, windows support, cost-aware router.
- [agents on cloudflare: workers, durable objects, r2, d1](https://bernstein.run/blog/cloudflare-cloud-execution): bernstein 1.8.4 cloudflare backend for ai coding agents: workers run agents, durable workflows handle multi-step tasks, r2 + d1 hold state.
- [refactor a 4,000-line python file with 11 parallel ai agents](https://bernstein.run/blog/module-decomposition): 11 parallel ai coding agents split a 4,198-line python file into 22 sub-packages in three hours. how the decomposition pass actually ran.
- [Picking a cheaper model when the task allows](https://bernstein.run/blog/cost-aware-routing): Bernstein's epsilon-greedy bandit picks a model per task. Internal runs cut roughly in half. Measure your own with bernstein cost.
- [bernstein 1.0: open-source orchestrator for ai coding agents](https://bernstein.run/blog/introducing-bernstein): Orchestrate Claude Code, Codex, Gemini CLI + 40 other CLI coding agents in parallel git worktrees. Deterministic scheduler, HMAC-signed audit chain.

## Author

- [Alex Chernysh](https://alexchernysh.com): Author of Bernstein, homepage and portfolio
- [Alex on GitHub](https://github.com/chernistry): Source of Bernstein and other open-source projects
- [Alex on X](https://x.com/alex_chernysh): @alex_chernysh - short notes and updates

## Related Projects

- [HireEx](https://hireex.ai): Personal multi-agent AI workspace by the same author - career intelligence is the first vertical artefact

## Optional

- [Changelog](https://bernstein.readthedocs.io/en/latest/CHANGELOG/): Version history
- [Contributing](https://bernstein.readthedocs.io/en/latest/CONTRIBUTING/): How to contribute
- [License](https://github.com/sipyourdrink-ltd/bernstein/blob/main/LICENSE): Apache 2.0