sipyourdrink-ltd/bernstein

Bernstein – Governance Layer for AI Agents

What it is – Bernstein is an open‑source framework that sits between AI‑driven coding agents (Claude Code, Gemini CLI, OpenAI Agents SDK, etc.) and the code‑base they work on. It lets you describe a policy‑as‑code workflow in a simple YAML file, then runs the agents in isolated work‑trees, records every step, and produces a cryptographically signed receipt that can be verified offline. In short, it gives you deterministic, auditable orchestration of AI agents without putting an LLM in the coordination loop.

Key ideas

• Deterministic scheduler – the planner is plain Python, not an LLM, so the same YAML plan always yields the same task graph.
• After‑the‑fact verification – a journal records every action; an optional HMAC‑chained audit log adds signed receipts. Any mismatch shows exactly which step diverged.
• Isolation by default – each coding task runs in its own Git work‑tree (or a sandboxed directory for non‑code artifacts). Shared state is limited to the atomic task backlog.
• Broad agent support – 50+ built‑in adapters for popular CLI agents plus a generic --prompt wrapper, all runnable locally without SaaS hops.

Typical workflow

1. Write a bernstein.yaml (or similar) that defines phases, roles, dependencies and optional conditions.
2. Run bernstein -g "<goal>" or bernstein workflow run <plan>.yaml.
3. The scheduler spawns the appropriate agents, each working in its own isolated workspace.
4. When a node finishes, Bernstein checks the declared artifact contract (e.g., tests pass, files exist) and records a signed lineage receipt.
5. After the run you can replay, verify, or audit the entire execution with commands like bernstein replay latest --verify or bernstein verify receipt ….

Why it matters

• Compliance & auditability – organizations can prove that an AI‑generated change was reviewed, tested, and merged according to a pre‑approved policy.
• Reproducibility – because the coordinator is deterministic, you can replay a previous run and get the exact same task graph, useful for debugging or regulatory review.
• Safety – isolation prevents agents from stepping on each other’s files, and sandbox back‑ends can enforce network or resource limits.

Getting started

uv tool install bernstein   # or pipx install bernstein
bernstein init               # creates .sdd/ workspace and template files
bernstein doctor            # checks that your chosen CLI agents are installed
bernstein -g "fix the failing test in tests/test_foo.py"

Installation works via pip, pipx, Homebrew, Docker, or an air‑gapped wheelhouse.

User interfaces

• bernstein live – a terminal UI showing agents, logs, and a task board.
• bernstein gui serve – a web dashboard with task lists and diff previews.
• CLI commands for replay, lineage verification, benchmarking, and localisation checks.

License & status – Apache‑2.0, beta‑stage, solo‑maintained, with fast‑moving minor releases. The project is actively CI‑tested, has a CodeQL scan, and provides Docker images via GHCR.

---

For a deeper dive, see the official docs: https://docs.bernstein.run/