Warranted

Make AI research agents accountable — give every conclusion a traceable argument graph.

English | 简体中文

Coding agents have compilers and tests. Research agents have Warranted.

The problem

AI coding agents converge because compilers and tests provide objective failure signals. Research has no equivalent — conclusions live in natural language with no external verifier, so agents routinely declare work complete with no way to know what's missing.

Warranted fills that gap. It gives AI agents a persistent argument graph where every Claim requires Grounds and a Warrant, contradictions are recorded as Rebuttals rather than erased, and status can only advance after passing a logic check (compile). The result is research reasoning that is auditable, reproducible, and verifiable — not just plausible-sounding.

Good fit for: paper reproduction, hypothesis verification, multi-step scientific reasoning, research transparency.

Related MCP server: Mcp-Omega-Brain

Documentation

New here? Read in this order:

Release history: CHANGELOG.md

Upgrading to 0.5.0

0.5.0's behavior changes split into three classes with completely different discovery methods, so upgrading needs three actions, not one. Running a full compile finds the first class and structurally cannot find the other two.

① Graph-state changes — run compile_arguments over every Claim.

Claim-type Grounds are now judged by their own status, and Claims that report new errors are the places where an upper conclusion sits on an unsettled or refuted lower conclusion. That state has existed all along with no rule ever looking at it. Handle them one at a time: if the lower Claim is proposed, settle it first; if it is refuted, re-hang the upper Claim on a narrower Claim that survives the refutation (typically "this approach exists in the literature" rather than "this approach works"). A disputed lower Claim is fine and needs no action.

Expect this first pass to call the review model for every Claim, even ones you compiled before: the compile verdict moved out of the Claim node, which changed every argument hash, so nothing short-circuits on no-change this once.

Expect it to also move some statuses. A Claim that comes out of this pass without a passed verdict has its supported/disputed/refuted status reverted to proposed, and Claims resting on it are rechecked and may follow. That rule is not new — a non-proposed status has always required a passed compile — but it used to be checked only when the status was written, so a Claim settled before this release could be holding a verdict its argument no longer earns. Each revert is reported on the call, naming the Claim and why.

Settling statuses afterwards is safe — a lower status change does not invalidate the compile above it. What it can do is revert an upper supported/disputed/refuted back to proposed, when the lower Claim it counted on no longer counts as verified evidence. Those reverts are reported as warnings on the call that caused them; re-settle the lower Claim and you can set the upper one back without recompiling.

② Call-habit changes — audit your write-path callers now.

Compile cannot see these; they fire only on your next write. If you have scripts, automation, or custom skills that call create_statement or update_node, check them against these six before your next recording session:

• source is now required on create_statement.

• source="literature" must carry attachments.

• Every attachment path must resolve from the review working directory (URLs do not qualify).

• A review-infrastructure error now leaves the Statement pending and reports the error, rather than resting at verified.

• update_node(attachments=[]) against a verified Statement now errors.

• update_node(status="disputed") and status="refuted" now require a verified Rebuttal on the Claim or one of its Warrants. Recording the Rebuttal still always succeeds and lands pending; it is the status call that is gated, so a caller that recorded a contradiction and settled the Claim in one go now needs a verification step between the two.

③ Review configuration — make your config file self-sufficient.

The reviewer subprocess now runs isolated: it no longer reads ~/.claude/settings.json. If your review worked because the gateway address or the key lived in your own Claude Code settings rather than in the file you pass to --review-config, review will now fail to reach the endpoint. Put baseUrl and apiKey in that file. Also drop debounceMs if you set it (it was never read), and check that maxTurns/maxConcurrency are positive integers — an invalid value now warns and falls back to the default instead of being taken literally.

Setup with Claude Code

1. Clone and configure

Install Bun (>= 1.0.0), then:

git clone https://github.com/yqi96/warranted
cd warranted

# Optional: enable LLM logic review
cp review.json.example review.json
# Edit review.json and fill in apiKey

2. Register with marketplace (once per machine)

claude plugin marketplace add $(pwd)

3. Install the plugin in your project

cd your-project
claude plugin install warranted@warranted --scope local

On launch, toulmin-researcher becomes the primary agent and the MCP server starts automatically.

When LLM review is enabled, node definitions are reviewed on creation and compile_arguments runs a full logic-chain audit.

Hitting install or version issues? See known-working versions for a verified dependency snapshot.

Visualizer

From the warranted directory:

bun run viz

Open http://localhost:3456 in your browser.

Interaction

The ⬚ / ✥ buttons in the toolbar switch between box-select and pan mode.

Selection as context

The visualizer server tracks the current selection. Once the plugin is running, every message you send to Claude automatically includes the selected nodes as context — no need to describe which nodes you mean, just select and ask.

Agents

Skills