Warranted

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

English | 简体中文

Code has compilers and tests. Research needs failure signals too.

What it does

Warranted gives a research agent a persistent, auditable argument graph. The graph has one node type: a proposition. Every proposition has five slots:

Ground, backing, claim, and rebuttal are viewpoints, not node types. The same proposition can be evidence for one conclusion, a conclusion in its own right, and a rebuttal somewhere else.

Structural checks are deterministic and automatic. They return non-blocking warnings for incomplete evidence, missing attachments, changed dependencies, and similar conditions. They do not rewrite qualifiers or prevent the agent from recording a judgment. An explicit review call can ask a separate LLM for a semantic second opinion about source faithfulness and inference validity. Findings are advisory; they remain pending until a later review replaces them or they are dismissed with a reason.

After checking a small fix, rejecting a mistaken objection, or accepting a limitation for the stated use, the primary agent can dismiss with a specific reason. Dismissing every finding in the latest valid review records acceptance of the current input as passed by the agent, without rewriting the reviewer's verdict or changing credibility. Later input or protocol changes make that acceptance stale. Finishing does not require every node to pass or every warning to disappear.

Related MCP server: OntoRamp Decision Intelligence

Documentation

The detailed contracts live in docs/design.md and docs/api.md. Release history is in CHANGELOG.md.

0.6.0 upgrade compatibility: version 0.6.0 replaces the 0.5.0 three-node/compile model with the proposition model described above, introduced in commit 90c7acb. Old .toulmin/argument.db files remain read-only historical archives; current runs use .toulmin/graph.db and do not mechanically migrate old verdicts. The 0.5.0 terminology remains in the changelog only as release history.

Setup with Claude Code

Install Bun (>= 1.0.0), Node.js, and a Chrome/Chromium browser, then:

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

# Optional: enable explicit third-party LLM review
cp review.json.example review.json
# Edit review.json and fill in apiKey; baseUrl is optional.

The plugin launchers run bun install --frozen-lockfile. The browser MCP uses the pinned chrome-devtools-mcp dependency and starts isolated browser sessions on demand.

Register and install the plugin:

claude plugin marketplace add $(pwd)
cd your-project
claude plugin install warranted@warranted --scope local

On launch, toulmin-researcher becomes the primary agent. Two stdio MCP servers start automatically:

• toulmin stores the current graph at <project>/.toulmin/graph.db and exposes the 11 graph tools.

• browser provides process-isolated Chrome sessions for browser-assisted research.

Review is never triggered merely by creating or editing a proposition. It runs only when the agent deliberately calls review, and only when review.json supplies a usable apiKey.

Review attempts have independent timeoutMs (default 600000, 10 minutes) and effort (default low), rather than inheriting the main agent's effort or sharing a node-wide budget. Three consecutive incomplete reviews within 30 minutes produce an advisory, not a lockout; a completed review with findings is not an execution failure. Identical completed or in-flight requests may be reused within the server process; refresh: true requests a new review. PDF page-range coverage needs Poppler's pdfinfo and the SDK's PDF reading support (pdftoppm for page rendering). Missing metadata or incomplete page coverage never counts as a completed read.

Audit is compact by default: input/attachment hashes, attempt outcome, elapsed time, and SDK-reported model/usage/cost when available (otherwise null). Set debug: true for diagnosis to additionally retain the actual prompt, SDK-visible event stream and hash-deduplicated immutable attachment bytes under the audit directory's debug/ subdirectory. Credentials are redacted; unreturned internal reasoning is not observable. Debug must be enabled before the attempt and can use substantial disk space. Normal mode does not guarantee exact-input replay. auditDir: null disables both modes. See review configuration and audit.

Hitting install or version issues? See known-working versions.

Tool surface

Writes validate content, referenced ids, and attachment existence. Structural warnings and review findings remain visible on reads; they advise rather than gate writes.

Visualizer

bun run viz

Open http://localhost:3456. The visualizer reads .toulmin/graph.db, colors propositions by qualifier, shows warning/finding badges, and can switch to another project's graph.db.

The UserPromptSubmit hook injects the current visualizer selection into later Claude prompts when the visualizer is running on its default port.

Agents

Skills

Development

There is no separate build artifact: Bun executes the TypeScript sources directly, while TypeScript is configured for strict, no-emit checking.

bun test
bun ./node_modules/typescript/bin/tsc --noEmit
bun run agent-eval             # dry-run; add --live only when model cost is intended