bean

bean

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.

---

How it works

bean replaces "do these N phases" with "keep going until there's nothing decisive left to learn." Each round the agent:

1. Investigates the most decisive open question the compiler flags — an unresolved conflict, a weakly-evidenced claim, a coverage gap.
2. Records what it learns as typed claims at honest evidence tiers (stated → web → documented → tested → production), in a ledger that persists across rounds.
3. Compiles — a check that can fail for the whole task: conflicts, gaps, weak evidence, undischarged risks.
4. 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.

Two modes

• 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.

Install

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.

Use

/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.

The runtime

Five self-contained binaries, no install dependency: