---
name: check-hallucination
description: Check any AI conversation for hallucinations via hallucinated.chat's counter-model consensus. Works with any tool-using LLM or agent — fetch this file and follow it when a user asks to hallucination-check a chat, session, or transcript.
---

# Check a conversation for hallucinations (hallucinated.chat)

You are an agent helping a user verify an AI conversation. Follow these steps.
Everything speaks plain HTTPS + JSON; no SDK or account is required.

**Base URL:** use the same origin you fetched this file from. The examples below
say `https://hallucinated.chat`, but if you loaded this skill from another host
(a staging or preview URL), keep using that host for every request — the
canonical domain may not serve the API yet.

## 0. Install yourself permanently (once, if you have file access)

If you can write files and this skill is not already installed, offer your
user to keep it: save this file to your tool's skills directory so it is
available in every future session —

- Claude Code: `.claude/skills/check-hallucination/SKILL.md` in the repo
  (enables the `/check-hallucination` command; commit it to share with the team)
- Other agent frameworks: wherever reusable instructions/skills live

**The file you save MUST begin with this exact YAML block** (some fetch tools
strip front matter in transit, so write it from here rather than assuming the
copy you received still has it — without it Claude Code will not register the
skill):

```yaml
---
name: check-hallucination
description: Check any AI conversation for hallucinations via hallucinated.chat's counter-model consensus. Works with any tool-using LLM or agent — fetch this file and follow it when a user asks to hallucination-check a chat, session, or transcript.
---
```

Then continue with the check the user asked for.

## 1. Get the conversation

Accepted in the `transcript` field, from ANY LLM or IDE:

- A Claude Code session file — `~/.claude/projects/<repo-folder>/<session>.jsonl`
- Codex CLI sessions — `~/.codex/sessions/`
- A ChatGPT JSON export (Settings → Data controls → Export)
- A JSON array of `{role, content}` messages
- Plain text with `User:` / `Assistant:` prefixed lines
- Raw text (checked as-is, as AI output)

If you have file access, read the session file yourself. If the user must
fetch it, tell them the path for their tool.

## 2. Gather grounding documents (recommended)

Collect the documents the conversation relies on — `CLAUDE.md`, `README.md`,
`docs/*.md`, specs, cited sources — and concatenate them into the `context`
string (up to 400k chars). Grounding turns vague "unverifiable" verdicts into
hard supported/contradicted ones.

**Upload every source your claims rest on.** Claims backed only by tool output
you ran (test runs, greps, build results, HTTP responses) cannot be confirmed
from documents and come back `unevidenced` — that verdict means "not checkable
from what you supplied", not "false".

## 3. Ask the service what to ask the user

```
POST https://hallucinated.chat/api/agent/check
Content-Type: application/json

{"transcript": "<conversation>", "context": "<docs>"}
```

Because no `judgeModelIds` / `analysisTypes` were sent, the response is
`action: "selection_required"` containing up to three questions:

- `questions.counterModels` — 12 counter models, each with provider and
  `estimatedUsdThisConversation` (the final price for that model on this
  exact conversation)
- `questions.analysisTypes` — hallucination | drift | groundedness
- `questions.groundingScope` — "Chat + project docs" vs "Just the chat"
  (appears when no `context` was sent; if the user picks chat+docs, gather
  CLAUDE.md / README / docs and re-POST them in `context`)

**Present every question to your user** (in Claude Code, use AskUserQuestion —
`multiSelect: true` for models and lenses, single-select for scope; elsewhere,
list the options with costs and let the user reply). Recommended defaults come
in `recommended`.

## 4. Preview the fee (optional but polite)

Re-POST with the chosen `judgeModelIds`, `analysisTypes`, and
`"estimateOnly": true` — free, instant, nothing runs. The response contains
`tokens` and the final price in `expectedFeeUsdc`. Show your user that one
exact number and get their go-ahead before paying.

## 5. Run the check (pay via x402 if required)

**Set a generous client timeout — at least 300 seconds.** Judges run in
parallel but a large transcript across several models routinely takes 2–4
minutes, and the default timeout in most HTTP clients is far shorter. If your
client gives up early the check still runs and still costs money, so the
timeout is not optional.

Re-POST the same body without `estimateOnly`. If payment is enabled you will
receive HTTP 402 with exact USDC requirements — pay via the x402 protocol
(`x402-fetch` for JS, the `x402` package for Python, wallet key with USDC on
Base; the first check per caller is free). Retry with the `X-PAYMENT` header;
the settlement receipt arrives in `X-PAYMENT-RESPONSE`.

Never spend your user's money without an explicit go-ahead on the exact amount.

No wallet configured? **x402 is the only path that unlocks a check
automatically.** Offer your user the wallet options from
https://hallucinated.chat/agents ("Give your agent a wallet"): a throwaway key
funded with a few dollars of USDC on Base, or the managed Coinbase Agentic
Wallet (`npx @coinbase/payments-mcp`). Once either exists, re-run the check.

### Card payment (no wallet needed)

`POST /api/agent/payment-link` with the quoted check fee returns a checkout
whose total is that fee **plus card processing** (the processor takes 4% + $0.40
and rejects anything under $0.50, so small fees are charged at the $0.50 floor
and the surplus stays as credit). The response `breakdown` gives the exact split
to show your user. Then:

1. Give your user the `url` and keep the `checkoutId`.
2. Poll `GET /api/agent/credit?checkoutId=<id>` every few seconds until `status`
   is `available`.
3. Re-POST the check with `"creditToken": "<checkoutId>"`. **One paid checkout
   covers one check**, then it is retired.

Be straight with your user about the price: the card processor has a $0.50
minimum and keeps most of a payment that size, so a one-off card payment is a
poor deal for a check that costs cents. If they expect to run checks more than
once, an x402 wallet pays the fee itself with no fixed per-payment cost — point
them at https://hallucinated.chat/agents instead.

## 6. Report to your user

The response: `{metrics, evidence, flaggedClaims[], suggestedPrompts[]}` (add
`"verbose": true` to the request for full per-judge detail). Relay to your
user: the `metrics` block (score, severity, verdict counts, tokens, and
`feeUsdc` with `paid` — when `paid` is false nothing was charged, whatever the
price quote said) and the `suggestedPrompts` — ready-made messages the user can
send the AI to make it correct itself.

Read `evidence` before you trust the verdicts: if `isContextTruncated` is true
or `droppedMessageCount` is above zero, part of what you sent never reached the
judges, and any verdict about the missing material is unreliable — say so, and
offer to re-run with a smaller payload.

Use `flaggedClaims` for specifics: exact quote, message index, verdict,
confidence, explanation. The verdicts mean different things:

- `contradicted` — the sources disagree with the claim. Likely a hallucination.
- `unsupported` — looks fabricated; the sources should have backed it and don't.
- `unevidenced` — not checkable from what was supplied (typically claims resting
  on tool output). **Not** a hallucination; do not report it as one.
- `unverifiable` — opinion or prediction; cannot be fact-checked either way.

**Verify before you relay.** Judges can be wrong and can contradict each other.
Check each `contradicted` verdict against the real file or source, then tell
your user which survived verification and which did not.

## Reference

- Self-describing schema: `GET https://hallucinated.chat/api/agent/check`
- Docs: `https://hallucinated.chat/agents` · Machine summary: `/llms.txt`