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:

Slot	Meaning
content	the statement being judged
evidence	attached files and references to other propositions
warrant	why that evidence supports the content, inline or promoted to its own proposition
rebuttals	propositions that attack the content or warrant
qualifier	one credibility scale: refuted → unestablished → possibly → probably → certainly

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.

Documentation

Doc	What it covers
The Argument Graph	propositions, five slots, qualifiers, warnings, findings, and the 11-tool surface
Reproducing a Paper	rebuild a paper's evidential chain using independently produced evidence
Writing a Paper	write LaTeX whose \cite{prop_N} citations trace to propositions and attached papers
Research Framework	how the primary agent, specialists, graph, and object-layer work divide responsibility

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

Group	Tools
Write	create_propositions, update_proposition, set_qualifier, promote_warrant, delete_proposition
Read	get_argument, find_propositions, get_stats, get_history
Opinion	review, dismiss

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.

Action	Effect
Click a node	select it
Double-click a node	open its detail panel
Shift + click	add to or remove from the selection
Drag in box mode	select several nodes
Drag in pan mode	move the canvas
Scroll	zoom
Click empty space	clear the selection

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

Agents

Agent	Role
toulmin-researcher	primary agent; controls the graph, coordinates research, and makes qualifier judgments
toulmin-explorer	fast read-only graph lookup and navigation
code-experimenter	bounded implementation, reproduction, and experiment execution
code-optimizer	makes full-scope experiments feasible without changing their semantics
discrepancy-auditor	audits one mismatch or claimed blocker before graph consequences are accepted
rigor-auditor	completion-level audit of whether the overall research is exhausted and worth reporting
literature-scout	performs one bounded browser-assisted literature search move and writes a durable search artifact
paper-reader	reads specified papers against one inquiry question and writes evidence notes
literature-extractor	records paper findings as propositions with source attachments; does not judge qualifiers

Skills

Skill	Trigger	Role
literature-survey	/literature-survey	iterative, question-driven critical literature review
paper-reproduce	/paper-reproduce	independent reproduction and graph-based judgment of a paper's claims
literature-writing	/literature-writing	literature-backed LaTeX writing with \cite{prop_N} citations
cite-review	/cite-review	checks citation content and strength against propositions and qualifiers
overleaf-setup	/overleaf-setup	one-time Overleaf sync and proposition-citation enforcement
browser	/browser	safe operation of an isolated Chrome session through the browser MCP
paper-download-browser	/paper-download-browser	authorized browser-assisted paper download when direct HTTP is insufficient

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