Skip to main content
Glama

driftcheck

PyPI Python CI License: MIT

Your agent's context files rot. driftcheck tells you which facts are no longer true.

driftcheck catching two stale facts in a CLAUDE.md

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=mac

What it checks

Claim in the doc

How it is verified

`~/bin/tool`, `/etc/foo.conf`

the path exists

http://127.0.0.1:3000, localhost:2222

something accepts connections

foo.service, bar.timer

systemd unit exists and is healthy (failed units and inactive timers are drift)

forge:owner/repo, repo URLs on your Forgejo

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 line

Scoped 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 skipped

MCP 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-mcp

Forgejo 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, not drift. A path like /user/tokens/verify (an API route, no such top-level directory) is unverifiable; a missing file under a real directory is drift.

  • 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 tests

The demo GIF is generated from real runs in a throwaway sandbox (needs ImageMagick):

python3 scripts/make_demo.py docs/demo.gif

MIT licensed.

Available Tools

1 tool
check_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

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    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.

    Naming Consistency5/5

    check_docs follows the verb_noun snake_case convention cleanly. With a single tool there is no risk of mixing naming styles.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      5
      75 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Gives 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.
      4
      132 PyPI
      1
      MIT