Bean – a portable convergence gate for agent work

Bean, a portable convergence gate for AI agents, ensures tasks are not marked complete until claims are verified, conflicts resolved, and open questions named as residuals. It replaces phase-based workflows with a loop that compiles evidence and blocks agent termination until convergence is scored. The tool ships as small static binaries with a native Stop hook for Claude Code and Codex.

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 can fail for 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? | 1. Survey | Re-assess what's available this round — tools, sub-agents, data sources. | 2. Investigate | Attack the most decisive open question the compiler flagged. | 3. Record | Write findings as typed claims at honest evidence tiers into the ledger. | 4. Compile | Score convergence; optionally gate load-bearing claims on a real verifier. | 5. Revise beliefs | Supersede claims new evidence overturns; resolve conflicts. | 6. 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, so bean-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 https://rustup.rs : 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 https://github.com/grainulation/bean/releases 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 /grainulation/bean/blob/main/EXAMPLE.md for a worked before/after. Five self-contained binaries, no install dependency: — the compiler and gate. Reads bean-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 for bean-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 to bean-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 no bean-hook .bean/ ledger.— a read-only trace analyzer: reads bean-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 /grainulation/bean/blob/main/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 plus bean-hook . Any agent loop or CI pipeline — call bean-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 rides inside an 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 reduces silent 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 it external — 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 /grainulation/bean/blob/main/CONTRIBUTING.md . Run npm test and node test/conformance.mjs before a PR. MIT /grainulation/bean/blob/main/LICENSE © grainulation contributors.