sipyourdrink-ltd/bernstein

---

Estado: beta. Mantenido por una sola persona, en desarrollo activo. El número de versión cuenta lanzamientos, no madurez; las versiones menores pueden cambiar interfaces. Fija la versión para cualquier cosa de la que dependas; las regresiones se corrigen rápido, notifícalas.

Bernstein es la capa de gobernanza open source para agentes de IA. Funciona con policy as code: tú escribes la política - quién puede hacer qué, qué necesita aprobación, qué debe quedar registrado - y Bernstein la aplica y produce el registro verificable. Un planificador determinista - sin modelo en el bucle de coordinación - ejecuta agentes en paralelo, filtra lo que producen con gates y registra cada paso, de modo que una ejecución puede verificarse a posteriori, offline, solo con los artefactos. Los agentes CLI de código funcionan de serie (Claude Code, Codex, Gemini CLI y 50+ más), y la misma capa gobierna cualquier carga agéntica: el entregable puede ser un diff, un informe de investigación, un dataset o un paquete de evidencias de auditoría. Perfil de instalación air-gap incluido. Apache-2.0.

de un vistazo

Cinco cosas lo distinguen; el resto son detalles.

• Sin LLM en el bucle de coordinación. La planificación es Python puro, por lo que una ejecución es reproducible de extremo a extremo. Reproduce el plan de ayer y obtén el grafo de tareas de ayer.
• Evidencia de claves físicas. Los verificadores sin conexión de custodia PIV y aprobación FIDO2 comparten el protocolo de recibos, con confianza fijada y tiempo explícito. La custodia del token no eleva los niveles de confianza TRACE. Evidencia de claves físicas.
• Verificable a posteriori. El journal de reproducción registra cada ejecución, y la columna vertebral de linaje siempre activa registra cada paso con linaje; el registro de auditoría opcional encadenado con HMAC (BERNSTEIN_AUDIT=1) añade recibos que puedes verificar offline. El no determinismo se manifiesta como una discrepancia de hash en el paso exacto, no como una reejecución inestable. Los entregables que no son código reciben el mismo tratamiento: una tarea puede declarar un contrato de artefactos (informe, conjunto de datos, registro de acciones, resultado de ops) y se completa con un recibo de linaje firmado en lugar de un commit de git.
• Aislado por diseño. Cada tarea de codificación obtiene su propio git worktree tras puertas de merge; las tareas en modo artefacto obtienen un directorio de trabajo bajo .sdd/workspaces/. Los agentes no comparten ningún espacio de trabajo mutable por defecto; el único estado compartido es el backlog de tareas, que se reclama de forma atómica. La aplicación más estricta del sistema de archivos es opcional, desde los backends de sandbox. Desactiva los worktrees y cada tarea se ejecuta en el checkout compartido.
• Amplio y local. Más de 53 adaptadores de agentes CLI más un contenedor genérico --prompt, estado basado en archivos, sin saltos SaaS, sin plano de datos de terceros.

La lista completa está en la página de capacidades; la matriz de características es el índice exhaustivo.

cómo es una ejecución

Un único archivo YAML declara la ejecución: fases, roles, dependencias y las condiciones bajo las que un nodo llega a ejecutarse. El planificador lo ejecuta como Python puro - nada en el archivo es un prompt y ningún modelo decide qué pasa después. Este grafo produce un paquete de evidencias de auditoría; el archivo completo está en .bernstein/workflows/audit-evidence-pack.yaml.

name: audit-evidence-pack
version: "1.0.0"

phases:
  - name: scope
    allowed_roles: [manager, architect]
  - name: collect
  - name: validate
    allowed_roles: [qa, security]
  - name: deliver
    allowed_roles: [security, manager]

nodes:
  define-control-inventory:
    phase: scope
    role: architect

  collect-audit-logs:
    phase: collect
    role: security
    depends_on: [define-control-inventory]

  # three more evidence streams collect in parallel:
  # collect-sboms-and-attestations, collect-runbooks-and-policies,
  # collect-eval-results

  assemble-pack:
    phase: validate
    role: docs
    depends_on:
      - collect-audit-logs
      - collect-sboms-and-attestations
      - collect-runbooks-and-policies
      - collect-eval-results

  mock-auditor-pass:
    phase: validate
    role: qa
    depends_on: [assemble-pack]

  remediate-findings:
    phase: collect
    role: docs
    depends_on:
      - source: mock-auditor-pass
        condition: "status == 'failed'"
    retry:
      max_attempts: 3
      until: "status == 'done'"

  sign-and-deliver:
    phase: deliver
    role: security
    depends_on:
      - source: mock-auditor-pass
        condition: "status == 'done'"

flowchart LR
    inv[define-control-inventory] --> logs[collect-audit-logs]
    inv --> sbom[collect-sboms-and-attestations]
    inv --> rb[collect-runbooks-and-policies]
    inv --> ev[collect-eval-results]
    logs --> pack[assemble-pack]
    sbom --> pack
    rb --> pack
    ev --> pack
    pack --> gate{mock-auditor-pass}
    gate -->|failed| fix["remediate-findings (retry x3)"]
    gate -->|done| sign[sign-and-deliver]

Cada nodo lo reclama un agente cuyo rol permite la fase; las vallas de rol y los gates de aprobación se mantienen haga lo que haga el agente dentro de la tarea. Un nodo de código termina tras merge gates en su propio git worktree. Los nodos de arriba terminan distinto: un contrato de artefacto nombra el entregable (informe, dataset, escaneo, registro de acciones) y el nodo se cierra con un recibo de lineage firmado en lugar de un commit. Mismo planificador, mismo journal, misma verificación offline - ya lleve el grafo código, investigación, un cambio de ops o una mezcla de los tres. Hay grafos listos para software, investigación, documentación, enterprise y flujos de contribución en .bernstein/scenarios/.

instalación en 30 segundos

uv tool install bernstein    # or: pipx install bernstein
bernstein init
bernstein doctor             # checks a CLI agent is installed and authenticated
bernstein -g "fix the failing test in tests/test_foo.py"

pipx, pip, brew, dnf, npm y Docker están cubiertos en la guía de instalación; el wheelhouse air-gap tiene su propia guía air-gap.

La grabación anterior es una ejecución real y viene con su propia prueba. La grabación, el recibo firmado derivado del journal de esa ejecución y la clave pública que lo fija todo viven en docs/assets/demo-run/. Verifica la ejecución que acabas de ver, offline:

bernstein verify receipt docs/assets/demo-run/run-receipt.json \
    --public-key docs/assets/demo-run/run-receipt.pub.pem

El recibo guardado puede verificarse de nuevo en cualquier momento con el comando anterior; una copia alterada no supera la misma comprobación. scripts/record_demo.sh regenera la grabación, el recibo y la clave a partir de una ejecución real fresca; nada dentro de la terminal es sintetizado.

Una ejecución en curso se puede observar desde cualquiera de las dos interfaces de operador. Ambas leen la misma API de tareas, por lo que ninguna es un reflejo rezagado de la otra. En bernstein live, las columnas izquierda y derecha se desplazan de forma independiente como paneles completos, por lo que los widgets debajo del pliegue permanecen accesibles en terminales más cortas.

bernstein live — el panel de terminal	bernstein gui serve — el panel de navegador

probar una ejecución

El determinismo aquí es algo que verificas, no algo que aceptas por fe. Ejecuta una vez con auditoría habilitada y luego verifica lo que se registró:

BERNSTEIN_AUDIT=1 bernstein -g "fix the failing test in tests/test_foo.py"
bernstein replay list                 # run ids recorded on disk
bernstein replay latest --verify      # recompute the journal head, name the first divergent step
bernstein lineage verify <run_id>     # recompute the always-on lineage spine
bernstein audit verify                # HMAC chain + Merkle seal (written because audit was enabled)
bernstein audit diagnose <run_id> --signal gate --sign-key KEY
                                      # name the exact step a failure entered the run, as a signed receipt
bernstein verify run <run_id> --signing-key-path key.pem   # sign one portable run receipt
bernstein verify receipt .sdd/runs/<run_id>/run-receipt.json  # verify it offline: file only

El journal se escribe en cada ejecución; la columna vertebral de linaje siempre está activa y gana una entrada por cada paso con linaje, por lo que una ejecución corta puede terminar con una columna válida y vacía. bernstein audit verify solo tiene una cadena para verificar cuando la ejecución se inició con BERNSTEIN_AUDIT=1, un preajuste de cumplimiento o bernstein run --audit. El flag --audit pertenece a bernstein run; en la forma bernstein -g anterior, establece la variable de entorno.

Un recibo de ejecución vincula el encabezado del journal, el encabezado de la columna de linaje cuando la ejecución escribió entradas de linaje y, opcionalmente, un rango de cadena de auditoría, bajo un único sujeto firmado con Ed25519 con la clave pública incrustada. Un revisor con ese archivo y la clave pública del operador puede confirmar que las acciones y cadenas incrustadas no se modificaron: sin clave HMAC, sin .sdd/ en vivo, y salida 2 indicando el primer paso divergente ante manipulaciones. Ese recibo identifica el estado del journal que incrusta; demostrar que ese estado es el journal terminado completo requiere adicionalmente un sello independiente de encabezado/conteo. Con el archivo solo y sin la fijación --public-key, la verificación es solo de integridad: prueba que el recibo es internamente consistente, no quién lo firmó, y el veredicto lo indica. Detalles en reproducción determinista.

La misma verificabilidad se aplica a los números de evaluación. bernstein bench run <suite> --reliability k (también escrito como bernstein eval --reliability k) ejecuta cada tarea k veces bajo coordinación fija, luego reporta un límite inferior pass^k (todos los k intentos deben pasar) junto con el límite superior pass@1. Ese resultado queda sellado en un recibo firmado que bernstein bench reliability-verify recalcula offline, de modo que un límite inferior fabricado falla la verificación. Detalles: límite de fiabilidad pass^k.

cómo funciona

Cada objetivo avanza a través de cuatro etapas:

1. Descomponer (Decompose). El gestor divide tu objetivo en tareas con roles, archivos asignados y señales de finalización. Una llamada LLM y, a partir de ahí, solo Python puro.
2. Generar (Spawn). Los agentes se inician en git worktrees aislados, uno por tarea de codificación; una tarea en modo artefacto obtiene un directorio de trabajo normal en su lugar. La rama principal permanece limpia.
3. Verificar (Verify). El conserje (janitor) comprueba señales concretas: las pruebas pasan, los archivos existen, lint limpio, tipos correctos.
4. Fusionar (Merge). El trabajo verificado se incorpora a main. Las tareas fallidas se reintentan o se redirigen a un modelo diferente.

Por qué el planificador es Python puro y a qué se renuncia con ello: por qué determinista.

comandos cotidianos

cd your-project
bernstein init                    # creates .sdd/ workspace, bernstein.yaml + templates/
bernstein -g "Add rate limiting"  # agents spawn, work in parallel, verify, exit
bernstein live                    # watch progress in the TUI dashboard
bernstein run plan.yaml           # multi-stage plan: skip LLM planning, execute directly
bernstein stop                    # graceful shutdown with drain

Toda la superficie del operador (automatización de PR, programaciones, puentes de chat, el demonio de autofix) se encuentra en comandos del operador.

bernstein workflow ejecuta DAGs declarativos en YAML de nodos de agente, comando y bucle - con soporte de reanudación para ejecuciones interrumpidas:

bernstein workflow run idea-to-pr -g "Add JWT auth"   # prints run_id
bernstein workflow resume <run_id>                    # picks up at the first non-completed node

El estado de ejecución guarda un punto de control en .sdd/runs/<run_id>/ en cada nodo. La reanudación valida la huella del manifiesto al inicio de la ejecución, de modo que un cambio de especificación se rechaza en lugar de ejecutar silenciosamente un manifiesto diferente. Consulta manifiestos de workflow.

Puertas de higiene del repositorio: bernstein readme-l10n verify falla una PR cuyos READMEs traducidos se hayan desfasado de la fuente en inglés (indicando la sección obsoleta), bernstein readme-l10n sync los vuelve a vincular tras una edición en inglés. Consulta readme-l10n.

agentes compatibles

Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, Aider, Goose, Muse Code, OpenAI Agents SDK, Amp, Cody, Continue, Devin Terminal, Junie, Kilo, Kiro, AWS Q Developer, Ollama, OpenCode, OpenHands, Open Interpreter, gptme, Plandex, AIChat, Letta Code, Qwen y más. El índice de adaptadores incluye comandos de instalación para 30 de ellos. bernstein integrations list enumera las 56 integraciones conectadas desde src/bernstein/adapters/registry.py, la única fuente de verdad para lo que se resuelve. 54 de ellas son adaptadores de agentes seleccionables; las otras dos filas son el stub de prueba mock y el perfil de endpoints self-hosted-endpoints. Cualquier otra cosa con un flag --prompt funciona a través del contenedor genérico.

Combina agentes en la misma ejecución: modelos locales económicos para código repetitivo, modelos en la nube más pesados para arquitectura. bernstein integrations list --installed muestra lo que está disponible en tu máquina.

cómputo voluntario

Un proyecto puede marcar incidencias como abiertas a voluntarios, y cualquiera puede ejecutar una en su propia máquina sin cuenta ni coordinador. El proyecto declara lo que una tarea tiene permitido hacer en un manifiesto volunteer.json - backend de sandbox, lista de red permitida, techos de tiempo de reloj y memoria - y los límites propios del donante solo pueden estrecharlo, nunca ampliarlo. El recibo que produce una tarea terminada vincula el resultado a la decisión de contención bajo la que se ejecutó, de modo que un mantenedor puede comprobar meses después a qué se le permitió realmente acceder al trabajo.

bernstein volunteer verify .
bernstein volunteer browse --budget 60

La guía del donante cubre la ejecución de un worker y el presupuesto que fijas, la guía del proyecto cubre la declaración de un manifiesto, y el modelo de amenazas indica qué protege y qué no cada frontera. El ejecutor de un solo comando aún no se ha publicado: hoy verify, browse, budget, verify-bundle y hub son los subcomandos que funcionan. autopilot está registrado, pero se niega a ejecutarse hasta que se implemente un TaskSource.

más allá de la portada

Todo lo profundo vive en el sitio de documentación:

página	lo que cubre
capabilities	la lista completa de capacidades: modo servidor MCP, tarjetas de agente firmadas, backends de sandbox, sumideros de artefactos, mapeos regulatorios
bernstein_create_task	POST /api/v1/tasks → bernstein_claim → bernstein_complete
who this is for	dónde reside el valor y dónde Bernstein es la herramienta equivocada
workflows	DAGs declarativos en YAML de nodos de agente / comando / bucle
web UI	panel de navegador sobre la misma API que utiliza la TUI
cloud execution	experimental: ejecuta agentes en Cloudflare Workers con sincronización de workspace en R2 contra tu propia cuenta. El servicio alojado api.bernstein.run aún no está disponible
datasources	recibos de consulta de solo lectura, más un controlador de consultas que vincula cada resultado con la instantánea del esquema a partir de la cual se obtuvo
agent catalogs	apunta roles a definiciones de agentes fuera de las plantillas integradas: un directorio YAML/SKILL.md genérico o un árbol con estructura de plugin de Claude Code
security	scorecard, fuzzing, securización
architecture	cómo funciona por dentro

¿por qué este nombre?

Bernstein lleva el nombre de Leonard Bernstein, el director de orquesta y compositor estadounidense. El proyecto orquesta a un equipo de agentes de codificación CLI de la misma manera que Bernstein dirigía la Filarmónica de Nueva York: cada músico a tiempo, la partitura determinista, el director responsable del resultado.

escribí bernstein porque pagaba $400 al mes en facturas de claude ejecutando tres agentes de codificación en paralelo y obteniendo merges no deterministas. Apache 2.0, mantenido por una sola persona. Estadísticas en vivo: bernstein.run.

mencionado en

Incluido en vinta/awesome-python, cubierto en el resumen de Augment Code de orquestadores de agentes de código abierto y listado en Python Weekly #742. También documentamos el enfoque como el patrón de orquestación determinista sin LLM en awesome-agentic-patterns.

Toda la cobertura: más de 20 listas awesome, directorios, boletines y citas de colegas

La lista completa rastreada, incluyendo cada entrada en listas awesome, listados en catálogos, citas de estado del arte y menciones en boletines, se encuentra en docs/mentions.md. Las entradas se añaden a medida que aparecen; las correcciones son bienvenidas mediante issue o PR.

ejecuciones administrativas

Usa bernstein_run(template="administrative", goal="Weekly sprint") para crear un contenedor vacío y auditado sin planificador ni procesos de agentes. Añade tareas manuales con bernstein_create_task(title="Review brief", description="...", run_id="admin-...") y consulta bernstein_run_status(run_id="admin-..."). Las tareas se pueden reclamar mediante la API habitual, pero quedan fuera de la orquestación automática. Una ejecución con tareas termina cuando cada tarea tiene el estado done, closed o cancelled; una ejecución vacía permanece abierta. Flujo operativo.

contribución, soporte, licencia

Las PRs son bienvenidas; CONTRIBUTING.md contiene la configuración y el estilo de código. Los informes de seguridad se gestionan a través de SECURITY.md. Si Bernstein te ahorra tiempo: GitHub Sponsors. Contacto: [email protected].

Los metadatos de citación viven en CITATION.cff. Licencia: Apache-2.0; el nombre del proyecto está cubierto por separado en TRADEMARKS.md.

---

Alex Chernysh · GitHub · X · bernstein.run · task notifications