# Bernstein

> Bernstein is the open-source governance layer for AI agents, with a deterministic scheduler driving 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 let a reviewer who did not execute the run check it offline, without rerunning it. Signature and hash-chain checks read the on-disk records alone; the HMAC leg needs the key the chain was written with. Cluster mode and an air-gap install profile included. Apache-2.0. Status: beta, solo-maintained - pin the version you depend on. Built by Alex Chernysh.

## What you get

- [No server to provision](https://bernstein.run/q/self-hosted-ai-coding-agent-orchestrator): State is file-based (`.sdd/`); the orchestrator and every agent it spawns run on your machine
- [Per-agent credential scoping](https://bernstein.run/q/how-does-bernstein-scope-permissions): An agent sees only the environment it declared needing, so one agent's keys stay out of the others' processes
- [Pluggable sandbox backends](https://bernstein.run/q/what-sandbox-backends-does-bernstein-support): Docker, E2B, Modal, Blaxel, Cloudflare, Daytona, Runloop, Vercel - on top of the local git-worktree default

Cloud artifact sinks, progressive skill packs, and Cloudflare cloud execution are available on top of the same defaults.

## Docs

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

## Site pages

- [Why Bernstein](https://bernstein.run/why-bernstein): What the governance layer covers, and what an auditable run buys you
- [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
- [Benchmarks](https://bernstein.run/benchmarks): Simulated parallel-scheduling speedup model plus a community cost benchmark, each labelled by source

## 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
- [MCP (remote, read-only)](https://mcp.bernstein.run/mcp): Streamable HTTP endpoint, anonymous - verify run receipts, list presets and adapters
- [Verify a run receipt](https://mcp.bernstein.run/verify): Run-receipt verifier
- [Authentication](https://bernstein.run/auth.md): There is none. What is public, which write endpoints are anonymous, and why the OpenAPI document's server is the reader's own machine rather than this host
- [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. Each bullet points at the stand-alone answer page; the same example is inlined underneath.

- [Adapter (claude_code)](https://bernstein.run/q/how-to-add-a-cli-adapter): Declaring a CLI agent in bernstein.yaml - name, adapter, role, model
- [plan.yaml](https://bernstein.run/q/how-to-write-a-bernstein-plan-yaml): Plan-file shape - stages, depends_on, per-step role and complexity
- [MCP server](https://bernstein.run/q/mcp-server-for-multi-agent-coding): Running Bernstein as an MCP server over stdio or HTTP, and the tool tiers
- [Worktree isolation](https://bernstein.run/q/git-worktree-parallel-ai-agents): One git worktree per task; the merge queue serializes results once the gates pass

### 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

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

Exposed tools (default `standard` tier; `--mcp-tier {core|standard|all}` widens or narrows the list): `bernstein_run`, `bernstein_status`, `bernstein_run_status`, `bernstein_approve`, `bernstein_complete`, `bernstein_cancel`, `bernstein_claim`, `bernstein_post_message`, `bernstein_post_artifact`, `bernstein_task_capsule`, `bernstein_shutdown_orchestrator`, `load_skill`.

### Worktree isolation

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

# Bernstein creates .sdd/worktrees/<session-id>/ for each agent
ls .sdd/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.14.159: the stranger's ninety minutes](https://bernstein.run/blog/v3-14-159-pi): A first-use report described ninety minutes of setup that ended in nothing. v3.14.159 answers it: the plan loader raises named errors instead of swallowing malformed fields, five commands are removed and the rest fold with deprecation windows, the reference docs are CI-gated against the registered CLI, and the README says beta. Also new: a Muse Code adapter, Agent Plugins v1.0.0 manifests, a signed run receipt that verifies offline, and bernstein audit diagnose.
- [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 fleet you can pin](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 off the spend ledger, a three-arm cost-and-quality A/B harness, proactive context compaction with chained receipts, a credential-shaped-content gate on compaction input, schema-enforced worker completion payloads with typed refusals, digest-pinned team manifests with drift detection, 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.
- [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's cloudflare integration for ai coding agents: workers run agents, workflows carry multi-step tasks, r2 + d1 hold workspace and metering state. experimental; runs on your own account.
- [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 contextual bandit picks a model and effort level 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 and 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

## Optional

- [Contributing](https://docs.bernstein.run/en/latest/contributing/): How to contribute
- [License](https://github.com/sipyourdrink-ltd/bernstein/blob/main/LICENSE): Apache 2.0