A portable convergence gate for agent work — for Claude Code and Codex.
bean keeps an agent from declaring a task "done" until its claims are verified, its conflicts are resolved, or its open questions are named as honest residuals. It records what the agent learns as a typed claim ledger, runs a compiler that scores whether the work has actually converged, and — installed as a runtime — blocks the agent from stopping until it has.
bean replaces "do these N phases" with "keep going until there's nothing decisive left to learn." Each round the agent:
Investigates the most decisive open question the compiler flags — an unresolved conflict, a weakly-evidenced claim, a coverage gap.Records what it learns as typed claims at honest evidence tiers (stated
→web
→documented
→tested
→production
), in a ledger that persists across rounds.Compiles— a check that canfailfor the whole task: conflicts, gaps, weak evidence, undischarged risks.Revises beliefs— when new evidence overturns a claim, it supersedes it instead of leaving the contradiction standing.
The loop ends only when there are no unresolved conflicts, every load-bearing claim meets its evidence bar, and a full round turns up nothing new — or an open question is named as a genuine residual. bean stops on scored evidence, not on the agent's say-so.
| Step | What happens |
|---|---|
| Frame (once) | |
| State the goal; seed the ledger with known constraints. Does it earn the loop? |
- Survey | Re-assess what's available this round — tools, sub-agents, data sources. |
- Investigate | Attack the most decisive open question the compiler flagged. |
- Record | Write findings as typed claims at honest evidence tiers into the ledger. |
- Compile | Score convergence; optionally gate load-bearing claims on a real verifier. |
- Revise beliefs | Supersede claims new evidence overturns; resolve conflicts. |
- Converged? | No conflicts + evidence bar met + a dry round → deliver. Otherwise, loop again. |
Plugin-only (advisory). The/bean
skill gives the agent the convergence loop as guidance.Installed runtime (enforced)../install.sh
builds the binaries and registers a native Stop hook, sobean-check
becomes a hard gate: the agent cannot finish a bean-tracked task until the ledger converges or names its residuals.
bean ships as small static binaries (no runtime dependencies) plus the /bean
skill and the native hook.
From source (needs Rust):
git clone https://github.com/grainulation/bean.git
cd bean && ./install.sh
This builds the runtime, installs the /bean
skill, and registers the Stop hook for Claude Code and Codex.
Prebuilt binaries (no Rust): download the tarball for your platform from the latest release and put the binaries on your PATH
.
/bean <your task>
/bean quiet <your task> # terse — failures still surfaced
bean engages when a task is worth the loop — "do this thoroughly," or work that spans multiple files, sources, or sessions — and stays out of the way for a trivial one-pass task. See EXAMPLE.md for a worked before/after.
Five self-contained binaries, no install dependency:
— the compiler and gate. Readsbean-check
.bean/claims.json
(and optional.bean/run.json
) and exits nonzero until the loop converges: conflicts, undischarged risks, below-bar load-bearing claims, a dry round, the round budget, and the optional verifier gate. Emits a deterministic certificate.— runs a declared verifier (a command, with the claim on stdin) and records a scrubbed verdict forbean-verify
bean-check
to adjudicate.— the driver: injects the compiler's signal into the agent each round, records what it emits, enforces forward progress, and writes a per-run trace tobean-run
.bean/runs/<run_id>.json
. Works with any agent command.— the native Stop hook for Claude Code and Codex; blocks the agent from finishing until the loop converges, and is inert when a project has nobean-hook
.bean/
ledger.— a read-only trace analyzer: readsbean-lessons
.bean/runs/*.json
and writes a ranked report of recurring failure patterns to.bean/lessons.json
. Deterministic; it proposes, never applies.
A load-bearing claim can require an external verifier — your test suite, a type check, a state assertion — instead of trusting a self-asserted evidence tier. Set the mode in .bean/run.json
→ verification.mode
:
compat
(default) — no verifier required.advisory
— warn on an unverified load-bearing claim.strict
— require a passing verifier or a named residual.
See skills/bean/references/oracle-gate.md.
The gate is a self-contained binary, so the same core runs in more than one place:
Claude Code and Codex— as a native Stop hook (the/bean
skill plusbean-hook
).Any agent loop or CI pipeline— callbean-check
/bean-verify
as a verification step that blocks "done" until the ledger converges.
bean works standalone with local files and binaries — no network, no service, no account.
Not an agent framework. It ridesinsidean agent loop as the verification layer; it complements an agent framework, it doesn't replace one.Not an accuracy booster. It doesn't make a model smarter. It reducessilent false completion— turning "confidently wrong and done" into verified, fixed, or honestly blocked.
Lean. Static binaries, zero runtime dependencies, no network by default, no telemetry.A real gate.bean-check
makes convergence falsifiable; the verifier gate makes itexternal— auditable verification, not a self-graded checkmark.Coupled, not advisory. With the runtime installed, the native hook means the discipline can't be silently skipped.Discipline, not a transplant. bean shapes the procedure an agent follows; it doesn't raise the model's ceiling. A weak model with bean converges on its answer more honestly, not more brilliantly.
See CONTRIBUTING.md. Run
npm test
and node test/conformance.mjs
before a PR.MIT © grainulation contributors.