https://github.com/frizfealer/ground-check
Claude Code plugin for grounded, auditable AI answers: forces machine-checkable citations (file:line, tool calls) and mechanically verifies them to catch LLM hallucinations. Hooks-based, warn-only by default.
https://github.com/frizfealer/ground-check
ai-agents anthropic attribution auditability citations claude claude-code claude-code-plugin fact-checking grounding hallucination hallucination-detection hooks llm provenance verification
Last synced: about 9 hours ago
JSON representation
Claude Code plugin for grounded, auditable AI answers: forces machine-checkable citations (file:line, tool calls) and mechanically verifies them to catch LLM hallucinations. Hooks-based, warn-only by default.
- Host: GitHub
- URL: https://github.com/frizfealer/ground-check
- Owner: frizfealer
- License: mit
- Created: 2026-06-21T00:13:26.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-28T13:32:04.000Z (2 days ago)
- Last Synced: 2026-06-28T15:10:48.678Z (2 days ago)
- Topics: ai-agents, anthropic, attribution, auditability, citations, claude, claude-code, claude-code-plugin, fact-checking, grounding, hallucination, hallucination-detection, hooks, llm, provenance, verification
- Language: Python
- Homepage: https://frizfealer.github.io/
- Size: 171 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GroundCheck
A **Claude Code plugin** that fights LLM hallucination by making answers
**grounded and auditable**: every non-trivial claim must cite a
machine-checkable source, and those citations are mechanically **verified**
against your filesystem. It has two halves:
- **Injection** (`UserPromptSubmit`) — adds a policy telling Claude to mark every
non-trivial claim as VERIFIABLE (with a machine-checkable citation like
`Read(path:line)`, `Bash(cmd)`, `MCP(server.tool)`) or `unverified`.
- **Verifier** (`Stop` **and** `PreToolUse`/`AskUserQuestion`) — mechanically
re-checks the filesystem-checkable citations (`Read`/`Edit`/`Write`/`MultiEdit`)
against the **current** files and against what was actually opened this session.
Fabricated, out-of-range, or never-opened citations are flagged. It runs both
when Claude finishes a turn **and** when Claude pauses to ask you a question
(where `Stop` does not fire), so question-ending answers still get checked.
The tool taxonomy lives once in `scripts/grounding_spec.py`; both halves derive
from it, so coverage cannot drift between the policy and the verifier.
## What problem does this solve?
Large language models confidently cite files, line numbers, and command output
that don't exist — the `app.py:42` that was never opened, the test result that
was never run. If you've wanted to **stop Claude Code from hallucinating
citations**, **verify that AI-generated `file:line` references are real**, or
**audit which claims in an answer are actually grounded in your codebase**, that
is exactly what this plugin enforces:
- **Catch fabricated file:line citations** — every `Read`/`Edit`/`Write`
citation is re-checked against the current file on disk; pointers to missing
files or out-of-range lines are flagged.
- **Catch never-opened references** — a citation to a file the session never
actually read is flagged, even if the file exists.
- **Force a grounded-vs-unverified split** — Claude must label every non-trivial
claim as a machine-checkable citation or an explicit `unverified`, so you can
see at a glance what rests on evidence and what rests on the model's guess.
It is a **provenance and fact-checking layer for AI coding agents**, built on
Claude Code hooks — no API keys, no external services, standard-library Python
only.
## Install
Local (development):
claude --plugin-dir /path/to/ground-check
Or via a marketplace / GitHub repo once published (see Claude Code plugin docs).
## Requirements
- Python 3 on `PATH` (standard library only — no pip installs)
## Behavior & tuning
- **Mostly warn-only.** By default only `CONTENT_MISMATCH` blocks (a backticked
quote that isn't a verbatim slice of the cited line); every other finding just
warns. Tune the blocking set via `BLOCK_CODES` in
`scripts/grounding_engine.py` — `BLOCK_CODES = set()` for pure warn-only, or
add codes like `{"CONTENT_MISMATCH", "FABRICATED"}`.
- When blocking is on, a **loop guard** caps forced retries
(`MAX_FORCED_CONTINUATIONS`, default 3), stops on no-progress, and resets on a
clean turn or after `STATE_RESET_SECONDS`. State persists in
`$CLAUDE_PLUGIN_DATA` (survives plugin updates).
- To change which tools are cited/checked, edit the `TOOLS` table in
`scripts/grounding_spec.py` — policy text, citation regex, and read-tracking
all update together.
## Enable / disable
The plugin ships **on**. Toggle it globally with the `/grounding` slash command:
/grounding on # enable policy injection + verifier
/grounding off # disable both (policy not injected, verifier no-ops)
/grounding toggle # flip the current state
/grounding # show the current state without changing it
The state is a global flag file under your Claude config dir
(`$CLAUDE_CONFIG_DIR` or `~/.claude`), so both halves agree and it persists
across sessions until you change it. Equivalent CLI:
`python3 scripts/grounding_spec.py --set on|off|toggle`.
## Verify / self-check
python3 scripts/grounding_spec.py --check # consistency assertions
python3 scripts/grounding_spec.py --emit-policy # preview the injected policy
## Scope (honest limits)
- Verifies citation **integrity** (pointer real, in range, actually read), not
semantic correctness of the prose.
- Only `Read`/`Edit`/`Write`/`MultiEdit` pointers are auto-checked. A `Bash`
citation is checked by command presence (the cited command really ran this
session; the verifier then supplies the recorded output), and backticked
file-line content is checked against the source — but neither is semantically
judged. `Grep`/`Glob` and other recorded-output/conversation citations are not
auto-checked yet, so the absence of a flag on those is not confirmation.