driftcheck
Verifies repository claims in markdown docs against a Forgejo instance: repo references like forge:owner/repo and repo URLs are checked for existence via the Forgejo API, using $FORGEJO_URL (default http://127.0.0.1:3000) and a token from $FORGEJO_TOKEN or ~/.config/forgejo-token.env (token sent only to that URL, never printed). Missing repos are reported as drift, while unreachable Forgejo instances yield unverifiable rather than false alarms. Read-only; no repository changes are made.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@driftcheck check CLAUDE.md for drift before I act on it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
driftcheck
Your agent's context files rot. driftcheck tells you which facts are no longer true.

CLAUDE.md, runbooks and memory notes say things like "the app listens on
:3000", "restarts use foo.service", "the code lives in repo X". When those
go stale, an agent acts on them with full confidence. driftcheck extracts
the checkable claims from markdown and verifies each one against the live
system. It is deterministic: no LLM is involved in checking.
The checking engine is stdlib-only; the package adds the MCP SDK for the server.
Read-only: it never changes files, services or repos.
Exit code 1 on drift, so it drops into CI or a systemd timer.
Install
uvx --from driftcheck-mcp driftcheck CLAUDE.md # run once, without installing
uv tool install driftcheck-mcp # installs `driftcheck` and `driftcheck-mcp`(From a checkout: uv run driftcheck CLAUDE.md.)
Related MCP server: claim-verifier
Usage
driftcheck CLAUDE.md # report drift only
driftcheck CLAUDE.md --all # also list ok / unverifiable / skipped
driftcheck docs/ ~/notes/ # directories: every *.md inside
driftcheck CLAUDE.md --json # machine-readable
driftcheck CLAUDE.md --scope mac # also check claims tagged scope=macWhat it checks
Claim in the doc | How it is verified |
| the path exists |
| something accepts connections |
| systemd unit exists and is healthy (failed units and inactive timers are drift) |
| the repo exists via the Forgejo API |
Each result is one of ok, drift, unverifiable (could not be checked
reliably, e.g. Forgejo unreachable) or skipped (out of scope).
Claims that are true somewhere else
A doc often describes several machines. Tag claims that only hold elsewhere so they do not raise false alarms:
tunnel 127.0.0.1:12222 <!-- driftcheck: scope=mac --> # checked only with --scope mac
<!-- driftcheck: ignore --> # alone on a line: skips the next lineScoped claims are skipped unless the scope is active (--scope X or
$DRIFTCHECK_SCOPE).
Run it on a schedule
driftcheck timer generates a systemd user timer. The schedule, targets and
scope are all arguments. It prints the units by default (a dry run):
driftcheck timer CLAUDE.md notes/ # daily 04:10, print only
driftcheck timer CLAUDE.md --at 07:30 --install # daily at 07:30, write + enable
driftcheck timer CLAUDE.md --calendar "Mon..Fri 08:00" --scope pod --install
driftcheck timer docs/ --name docs-check --calendar hourly --install # several schedules: use --name
driftcheck timer --name docs-check --remove # disable and delete--calendar takes any systemd OnCalendar expression. Other options:
--exec (command that runs driftcheck, default the one on PATH),
--no-persistent (skip runs missed while the machine was off),
--unit-dir, and --no-enable (write files only). To change a schedule, run the
command again with new arguments. Drift makes the run fail, so it shows up in
systemctl --user --failed and journalctl --user -u <name>.service.
Demo
examples/stale-runbook.md is a runbook that has rotted (reproducible on any Linux machine):
$ driftcheck examples/stale-runbook.md --all
DRIFT examples/stale-runbook.md:3 path /tmp/driftcheck-demo/build.sh - /tmp/driftcheck-demo/build.sh does not exist
DRIFT examples/stale-runbook.md:4 port 127.0.0.1:9 - nothing listening (Connection refused)
DRIFT examples/stale-runbook.md:5 unit old-worker.service - no such systemd unit (user or system)
DRIFT examples/stale-runbook.md:6 path /tmp/driftcheck-demo-config.yaml - /tmp/driftcheck-demo-config.yaml does not exist
OK examples/stale-runbook.md:7 path /etc/hostname - exists
5 claims: 1 ok, 4 drift, 0 unverifiable, 0 skippedMCP server
Lets an agent check its own context before acting. One read-only tool:
check_docs(paths, include_ok=false, scope=null).
claude mcp add --scope user driftcheck -- uvx driftcheck-mcpForgejo configuration
Repo claims use $FORGEJO_URL (default http://127.0.0.1:3000). The token is
read from $FORGEJO_TOKEN or ~/.config/forgejo-token.env, sent only to that
URL and never printed. Without a token, private repos report as not found.
Design decisions
Deterministic over clever. Checks are plain probes (stat, connect,
systemctl, one API call). An LLM can read the report; it should not produce it.Never cry wolf. A tool that raises false alarms gets ignored. Anything it cannot judge reliably is
unverifiable, notdrift. A path like/user/tokens/verify(an API route, no such top-level directory) isunverifiable; a missing file under a real directory isdrift.Scope is explicit. Claims that are true on another machine are tagged, not guessed at.
Limitations
Repo claims work against Forgejo only (not GitHub or GitLab yet). Branch and flag claims are not checked, and prose such as "the forge also holds X, Y, Z" is not parsed. Only the claim forms in the table above are extracted.
Development
uv run python -m unittest discover -s testsThe demo GIF is generated from real runs in a throwaway sandbox (needs ImageMagick):
python3 scripts/make_demo.py docs/demo.gifMIT licensed.
Available Tools
1 toolcheck_docsA
Check factual claims (file paths, local ports, systemd units, Forgejo repos) in markdown
docs or directories of docs against the live system. Returns drifted claims with file:line and why.
Set include_ok=true to also list claims that verified fine. Claims tagged
<!-- driftcheck: scope=X --> are only checked when scope=X is passed.
Inputs: paths (required), scope, include_ok.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
There is only one tool, so misselection between tools is impossible. Its purpose (verifying factual claims in markdown against the live system) is clearly stated and bounded.
check_docs follows the verb_noun snake_case convention cleanly. With a single tool there is no risk of mixing naming styles.
The server is narrowly scoped to one operation, so a single tool is defensible rather than an oversight. However, a bare 1-tool surface is thin, and the described functionality (scope filtering, include_ok, single file vs directory) hints at variants that could have been separate tools.
The core check operation is fully described, covering paths, ports, systemd units, and Forgejo repos with line-level reporting. Gaps remain: there is no way to discover available scopes or list claims without running a full check, no ignore/configuration operation, and no separate mode for previewing what would be checked.
Maintenance
Related MCP Connectors
Verify before you act: deps-check, x402-preflight, json-repair & url-read for agents.
Verify that packages, images, repos and DOIs an AI recalled exist before an agent uses them.
Live web checks for AI agents: sitemaps, robots.txt, URL status, broken links, feeds, citations.
Local checks for sudo, systemd, sshd, ufw, and secret leaks before an agent applies them.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides AI agents with real-time ground truth about what's actually running on the machine, including live agent sessions, listening TCP ports, loaded daemons, and system stats. It reads directly from the OS via fixed commands, ensuring agents never rely on stale docs or transcripts.575 npm1MIT
- AlicenseAqualityCmaintenanceEnables agents to verify real-world assertions like content being posted or PRs merged by fetching live evidence from URLs and GitHub, returning a verified boolean plus raw evidence.35 npmMIT
- AlicenseBqualityBmaintenanceChecks AI agents' claims against primary evidence, with no model; observes only what you grant.8105 PyPIApache 2.0
- AlicenseAqualityBmaintenanceGives AI agents safe, bounded, non-blocking access to Linux sysadmin inspection tasks, including CPU, RAM and disk healthchecks, memory-safe log tailing with regex filtering, and user-level systemd service and timer auditing. All operations run without sudo or unrestricted root shells, avoiding interactive pager hangs and context window flooding.4132 PyPI1MIT