A terminal-first, local multi-LLM workflow control plane for evidence-backed software changes.
한국어 README · Product plan · Runtime closure contract
Beaver coordinates model selection, model-specific prompts, durable workflow state, Git isolation, verification evidence, human approval, and token/USD accounting in one SQLite ledger. The product surface is a small CLI plus a headless TypeScript API. There is no Tauri application or desktop GUI.
Beaver is under active development. The durable v1 kernel is real and tested, but the default beaver run command still uses the legacy natural-language goal path. Read the status and limitations below before using it on important repositories.
The initial target is an AI-native software team with roughly 5–50 developers that already uses two or more coding-model providers, works in Git, and has repeatable lint/test/build commands. Beaver is useful when the team needs to answer:
- Why was this model selected for this role and attempt?
- Which prompt components, policy, context, and harness identity reached the invocation boundary?
- Which files changed, which commands ran, and what evidence justified success?
- Can an interrupted run resume without repeating an external effect?
- How many input/output tokens were observed, and what USD amount was calculated?
Regulated platform teams are a later target. Signed exports, private rotating eval sets, RBAC/SSO, retention policy, and stronger sandboxing are not yet complete.
| Area | Status | What is true today |
|---|---|---|
| Terminal surface | Implemented foundation | Exactly six public commands: init, run, inspect, answer, abort, and eval. A hidden v1 hook entry and attestation contract exist; production provider launchers do not yet install them. Older names remain hidden compatibility aliases. |
Default beaver run |
Compatibility path | Runs the existing goal/Plan/PRD orchestration path with model recommendation, route approval, prompt composition, worktrees, review, and accounting. It does not yet drive BeaverRuntimeV1. |
| Durable workflow kernel | Implemented foundation | Immutable typed IR, Plan/PRD adapters, typed events/projections, attempt and run leases, six executor kinds, checkpoints, effect receipts, workspace/evidence contracts, recovery, fork lineage, and terminal-event guards. |
| Headless API | Implemented foundation | BeaverRuntimeV1 exposes initialize, check-only compile, start, resume, observe, inspect, answer, cancellation request, and fork over the durable kernel. The embedding host supplies all six executors and the trusted evidence committer. |
| Cancellation recovery | Safe subset implemented | Effect-free expired attempts converge to CANCELLED/ABORTED. PREPARED/RUNNING/UNCERTAIN provider or effect boundaries, active hooks, and unresolved workspaces fail closed as UNCERTAIN; they are never automatically replayed. |
| Model routing and prompts | Partially implemented | The legacy path supports LLM role recommendations, explicit user approval, frontier-preferred orchestrator advice, deterministic selection, Senpi-inspired family presets, and ordered prompt manifests. Durable v1 provider-executor wiring and certification-based eligibility remain open. |
| Hook guard | Implemented contract, partial integration | Versioned manifest digests, host/session attestation, one-time nonce CAS, bounded deadlines, and terminal blockers are implemented. Production provider launchers do not yet install and pin the hidden hook for every v1 invocation. |
| Objective evaluation | Implemented foundation | Deterministic DF-0/DF-4 runner fixtures, strict metadata-only CAS artifacts, stable semantic digests, fault cases, and bundled CLI smoke tests. Live providers, adversarial targets, private holdouts, and container/resource isolation are explicitly unsupported. |
| Token and USD accounting | Implemented foundation | Invocation usage authority and rate provenance can be recorded and projected. Tokens and calculated USD are observational data only. Beaver has no budget cap, cost warning, or cost-triggered stop policy. |
No capability is promoted to production-ready merely because its schema exists. The exact definitions, code locations, success criteria, and remaining closure work are tracked in the runtime closure contract.
- Node.js 22.6 or later
- pnpm 10.15 or later
- Git
- Claude Code and/or Codex CLI for the legacy provider path
- macOS or Linux for the current full
pnpm check/bundle gate; DF-4 process-group recovery is not yet supported on Windows
git clone https://github.com/ashmoonori-afk/Beaver-AI.git
cd Beaver-AI
corepack enable
pnpm install --frozen-lockfile
pnpm check
# Put the built launcher on PATH, then enter the Git repository Beaver should operate on.
export PATH="$PWD/packages/cli/dist:$PATH"
cd /path/to/target-repository
beaver init
beaver run "fix the failing test and add a regression test"beaver init initializes .beaver/beaver.db in the current repository and reports whether the Claude and Codex CLIs are visible on PATH. Start from a clean, committed branch: the compatibility path creates worktrees and Git commits.
For non-TTY automation, generic review approval and model-route approval must be granted separately:
beaver run \
--auto-approve \
--approve-model-routes \
"verify the documentation links" </dev/nullusage: beaver <init | run | inspect | answer | abort | eval> [options]
| Command | Contract |
|---|---|
beaver init |
Initialize the local ledger and migrations in the current Git repository. |
beaver run "<goal>" |
Start the legacy-compatible natural-language goal path. A non-TTY run requires both approval flags. --replace-active is deliberately disabled. |
beaver inspect <run-id> [--section ...] [--json] |
Read a durable v1 run projection without mutation; legacy run rows are rejected. Use --latest only when the newest project run is v1. --models reads the built-in catalog independently. |
beaver answer <checkpoint-id> <response> |
Answer a checkpoint. Durable v1 answers require a locally attested TTY actor and the stored generation/payload binding. |
beaver abort <run-id> |
From an authenticated local TTY, request durable cancellation for a v1 run. It returns exit 3 while recovery is pending; it does not mark a legacy run as terminal or directly kill another process. |
beaver eval boundary [--json] |
Execute the trusted DF-0 runner-boundary fixture only. |
beaver eval boundary-recovery [--json] |
Execute the trusted DF-4 runner-boundary suite: one normal control and five fault/recovery cases. |
The old status, logs, checkpoints, costs, models, refine, resume, and wiki names are compatibility aliases and are intentionally absent from public help. The resume alias is non-mutating until the durable run surface is wired to the v1 CLI.
Durable v1 inspection examples (--models is the catalog-only exception):
beaver inspect --latest --section summary
beaver inspect --latest --section cost --json
beaver inspect --models --json
beaver inspect <run-id> --section eventsPressing Ctrl-C during the compatibility run requests an abort from the local provider and closes checkpoint waits. The CLI intentionally does not write a terminal state from the signal handler. Cross-process cancellation requests are accepted only for durable v1 runs. They do not settle autonomously: an embedding v1 host must drive cancellation recovery through the ledger, and public run --resume is not yet available.
| Code | Meaning |
|---|---|
0 |
The requested command completed successfully. |
1 |
Execution or verification failed. |
2 |
Usage, policy, unsupported mode, or trust-boundary rejection. |
3 |
A durable cancellation request is accepted but recovery is still pending. |
130 |
The foreground compatibility run observed Ctrl-C. |
In the compatibility path, an LLM advisor recommends the orchestrator and role-specific models from the enabled catalog. The user must approve that route set before planning or worker execution. The orchestrator recommendation prefers an enabled frontier-tier profile from the static catalog. It does not probe live credentials, provider capacity, or complete capability/data eligibility.
After approval, route selection is deterministic:
explicit override
> approved recommendation
> task hint
> role default
> global default
The prompt structure is inspired by Senpi's model-family prompt presets without copying its prompt text wholesale:
Beaver policy envelope
→ common execution core
→ model-family tuning
→ role contract
→ task instruction and context manifest
Each resolved prompt records an ordered component manifest and digest. Existing deterministic tests prove composition and route ordering. The optional live wrapper currently exercises only the legacy compatibility transport path: it proves a pre-dispatch composed manifest plus semantic nonce reproduction, not exact upstream bytes, security resistance, or durable v1 hook integration.
Beaver records token and calculated cost observations when the provider supplies or permits them. Durable v1 distinguishes authoritative, provider-estimated, locally estimated, and unavailable usage. Unavailable usage is not silently treated as zero.
There are deliberately no budget limits, spend warnings, or cost-triggered stop transitions. Retry, parallelism, process timeout, and lease deadlines remain bounded for runtime correctness; they are not financial controls.
# Prompt composition tests plus the DF-0 boundary runner.
pnpm eval:fast
# Scheduler/recovery/hook/migration tests plus one normal control and five DF-4 faults.
pnpm eval:recovery
# The smaller terminal-visible boundary subsets.
beaver eval boundary --json
beaver eval boundary-recovery --jsonThe evaluator runs one normal control and five DF-4 fault/recovery cases. It sends only strict target input to a separate trusted fixture process, keeps evaluator labels in the parent, bounds stdin/stdout/stderr and wall time, and persists only typed derived metadata. On POSIX it can terminate the original process group. It cannot prove that a descendant did not create a new session, and it provides no CPU, memory, disk, PID, network, filesystem, container, or namespace isolation. The recovery gate and bundled smoke test therefore require POSIX process-group support and are unsupported on Windows. Adversarial target execution, DF-3 security claims, live-provider certification, and private holdouts remain unsupported.
The report exposes two digests:
reportDigest: the CAS identity of this evidence instance.semanticResultDigest: a stable comparison identity that excludes timestamps, UUIDs, and elapsed time.
BeaverRuntimeV1 is the non-legacy integration surface. It requires an exact registry for these executor kinds:
llm · agent · approval · command · evaluator · git-integrate
The host must also provide a trusted commitPassingEvidence implementation. Executors cannot return an arbitrary success result; they return an evidence candidate, and the scheduler marks an attempt as successful only after the committer atomically binds a passing evidence bundle.
The API currently supports:
initialize()and purecompile({ mode: "check-only", ... })start()and fencedresume()- read-only
observe()andinspect() - generation-bound
answer() - durable
requestAbort()and safe cancellation recovery fork()at a proven workflow boundary
Concrete production executor factories, the UNCERTAIN disposition reconciler, fork comparison, and a public durable-workflow CLI are still open. See packages/beaver-ai/src/runtime.ts for the exact TypeScript contract.
Runtime state lives under .beaver/ and uses forward-only SQLite migrations. Current v1 migrations cover workflow runtime, evidence provenance, hook runtime, fork lineage, and terminal event guards through migration 012.
Safety properties already enforced in the v1 kernel include:
- immutable workflow/compiler/source-adapter identity;
- typed event + projection transactions;
- run and attempt lease epochs with stale-writer fencing;
- prepare/commit effect receipts and fail-closed uncertainty;
- generation-bound checkpoints with first-answer-wins CAS;
- evidence-required success and a globally unique final terminal event;
- hook manifest/session/nonce attestation;
- cancellation that never infers a PREPARED provider call was not dispatched.
Important limitations:
- The public
runcommand and legacy Plan/PRD dispatchers do not yet share the durable v1 kernel. abortcannot cancel legacy runs; use Ctrl-C for the foreground compatibility process.- PREPARED/RUNNING/UNCERTAIN external boundaries require an operator-facing disposition workflow that is not yet implemented.
- Production provider launchers do not yet pin and install the hidden v1 guard hook.
- Workspace isolation is Git-based, not a security sandbox.
- Objective eval fixtures are not a security certification.
pnpm install --frozen-lockfile
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
# Or run the complete gate.
pnpm checkpnpm build produces the terminal bundle in packages/cli/dist/, copies its runtime data and deterministic eval target, bundles Node, and black-box tests both public eval boundary suites.
Key locations:
| Path | Purpose |
|---|---|
packages/core/src/workflow/ |
Workflow schema, compiler, adapters, persistence, executor registry |
packages/core/src/scheduler/ |
Durable scheduler, coordinator, recovery, fork contracts |
packages/core/src/runtime/ |
Leases, effects, checkpoints, hook attestation |
packages/core/src/verification/ |
Command verification and evidence bundles |
packages/beaver-ai/src/runtime.ts |
Durable headless v1 facade |
packages/beaver-ai/src/evals/ |
Objective evaluator, runner, artifact contracts, reports |
packages/cli/src/ |
Six-command terminal surface and hidden hook entry |
docs/product/ |
Product plan and normative runtime closure contract |
Keep changes small enough to review as a runtime contract: migration/schema, domain transition, terminal projection, and fault test should agree. Do not upgrade a README status unless the stated success criteria are tested. Before opening a pull request, run pnpm check and include the relevant dogfood gate.
Package metadata declares the project as MIT licensed. A repository-level license text is not currently present.