bernstein

# 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 coding task runs in its own git worktree behind lint/type/test gates;
> artifact-mode tasks complete on a signed lineage receipt in an isolated
> plain directory instead. An
> always-on lineage spine and replay journal record what happened; an opt-in
> HMAC-chained audit log and signed receipts make results independently
> checkable after the fact. `bernstein artifact verify` and `bernstein audit
> verify --merkle-only` check from the on-disk artefacts alone; replaying the
> HMAC chain needs the install's audit key. Air-gap install profile included.
> Apache-2.0.

This document is the long-form `llms-full.txt` variant per the llms.txt spec
(<https://llmstxt.org/>). It expands on the short `llms.txt` with more context
for ingestion by language models. Machine-readable Markdown, link-rich.

## What Bernstein is

Bernstein takes a goal, breaks it into tasks, assigns them to AI coding agents
running in parallel, verifies the output, and merges the results. The orchestrator
itself is deterministic Python - zero LLM tokens on scheduling. Every run is
reproducible. Every step is logged and replayable.

- Pure Python orchestration. No LLM in the coordination loop.
- 40+ CLI agent adapters. Mix Claude Code, Codex, Gemini CLI, Aider, Cursor,
  and more in the same run.
- Git worktree isolation per agent. Main branch stays clean.
- Janitor verification: tests, lint, types, PII gating.
- File-based state in `.sdd/`. No database. Inspect with `cat`, back up with
  `cp -r`.

## Dropping into an unfamiliar repo

Bernstein stands up an AI engineering crew in minutes. State lives in
`.sdd/` - no server to provision. Per-agent credential scoping keeps your
keys out of the target environment. The multi-adapter spread means the crew
runs on whichever CLI agent the repo's owners already trust (Claude Code,
Codex, Gemini CLI, Aider, and more). Every step lands in the always-on
replay journal and lineage spine; run with `--audit` and every step is also
an HMAC-signed audit record, replayable for compliance review.

## Primary use cases

- **Client and contract work** - drop the crew onto a 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.
- **CI fleets** - run a crew of agents in parallel on PRs, with per-agent
  credential scoping and an opt-in signed audit trail.

## Install

```bash
pipx install bernstein
# or: pip install bernstein
# or: uv tool install bernstein
# or: brew tap sipyourdrink-ltd/bernstein && brew install bernstein
```

One-liner installers (macOS / Linux / Windows):

```bash
curl -fsSL https://bernstein.run/install.sh | sh
```

```powershell
irm https://bernstein.run/install.ps1 | iex
```

## Quick start

```bash
cd your-project
bernstein init                          # creates a .sdd/ workspace
bernstein -g "Add JWT auth with refresh tokens, tests, and API docs"
bernstein live                          # TUI dashboard
bernstein stop                          # graceful shutdown
```

## How it works

1. **Decompose**. The manager breaks your goal into tasks with roles, owned
   files, and completion signals.
2. **Spawn**. Agents start in isolated git worktrees, one per task.
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.

## Core Documentation

- [Getting Started](https://docs.bernstein.run/en/latest/getting-started/GETTING_STARTED/) - Install, configure, run first orchestration in 60 seconds
- [Architecture](https://docs.bernstein.run/en/latest/architecture/ARCHITECTURE/) - Task server, agent spawner, janitor verification, worktree isolation
- [Why deterministic](https://docs.bernstein.run/en/latest/architecture/WHY_DETERMINISTIC/) - Design rationale for zero-LLM scheduling
- [Lifecycle FSM](https://docs.bernstein.run/en/latest/architecture/LIFECYCLE/) - Task and agent state machines with transition tables
- [Adapter Guide](https://docs.bernstein.run/en/latest/adapters/ADAPTER_GUIDE/) - Supported agents and how to add your own
- [Sandbox backends](https://docs.bernstein.run/en/latest/architecture/sandbox/) - Worktree, Docker, E2B, Modal
- [Artifact sinks](https://docs.bernstein.run/en/latest/architecture/storage/) - Local, S3, GCS, Azure Blob, Cloudflare R2
- [Skills](https://docs.bernstein.run/en/latest/architecture/skills/) - Progressive-disclosure skill packs (OpenAI Agents SDK pattern)
- [Configuration](https://docs.bernstein.run/en/latest/operations/CONFIG/) - `bernstein.yaml` reference
- [API Reference](https://docs.bernstein.run/en/latest/reference/openapi-reference/) - Task server REST API on `:8052`

## Capabilities

- **Core orchestration**. Parallel execution, git worktree isolation, janitor
  verification, quality gates (lint, types, PII scan), cross-model code review,
  circuit breaker for misbehaving agents, token growth monitoring with
  auto-intervention.
- **Intelligence**. Contextual bandit router for model/effort selection.
  Knowledge graph for codebase impact analysis. Semantic caching saves tokens
  on repeated patterns. Cost anomaly detection (burn-rate alerts). Behavior
  anomaly detection with Z-score flagging.
- **Sandboxing**. Pluggable `SandboxBackend` protocol - local git worktrees
  (default), Docker containers, E2B Firecracker microVMs, Modal serverless
  containers (with optional GPU).
- **Artifact storage**. `.sdd/` state can stream to pluggable `ArtifactSink`
  backends: local filesystem (default), S3, Google Cloud Storage, Azure Blob,
  Cloudflare R2.
- **Controls**. HMAC-chained audit logs, policy engine, PII output gating,
  WAL-backed crash recovery, OAuth 2.0 PKCE.
- **Observability**. Prometheus `/metrics`, OTel exporter presets, Grafana
  dashboards. Per-model cost tracking (`bernstein cost`). Terminal TUI and
  web dashboard.
- **Ecosystem**. MCP server mode, A2A protocol support, GitHub App integration,
  pluggy-based plugin system, multi-repo workspaces, cluster mode for
  distributed execution.

## Resources

- [GitHub Repository](https://github.com/sipyourdrink-ltd/bernstein) - Source code, issues, discussions
- [PyPI Package](https://pypi.org/project/bernstein/) - `pip install bernstein`
- [npm wrapper](https://www.npmjs.com/package/bernstein-orchestrator) - `npx bernstein-orchestrator`
- [Website](https://bernstein.run)
- [Documentation](https://docs.bernstein.run/)
- [Author](https://alexchernysh.com) - Built by Alex Chernysh
- [X / Twitter](https://x.com/alex_chernysh) - `@alex_chernysh`

More agent context in chernistry/bernstein

15 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• sipyourdrink-ltd/bernstein1.4k