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.)
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, 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 tests
MIT licensed.
Metadata
Release files for driftcheck-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| driftcheck_mcp-0.1.0.tar.gz | 77.6 kB | With provenance | Details for driftcheck_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| driftcheck_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for driftcheck_mcp-0.1.0-py3-none-any.whl |
Total release size: 90.6 kB
Release files / driftcheck_mcp-0.1.0.tar.gz
| Download URL | driftcheck_mcp-0.1.0.tar.gz |
|---|---|
| Size | 77.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e2aba601ad4f401ca5f4119e6bf0c8a4fd2476741741678a39f755012b081e5d
|
|
BLAKE2b-256 checksum How to use checksums |
fd904e7968a3bf063854b7cb211e6fc9a51aabe7ef0eb7e6772dab16515de21f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / driftcheck_mcp-0.1.0-py3-none-any.whl
| Download URL | driftcheck_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a12361c64427735289da7c82745f51d701ec6bf90da65970ad86ca8d02fa9ab
|
|
BLAKE2b-256 checksum How to use checksums |
8778dc9d0b4ecf610ab472914392359f2d8e8df85f3484af41e58d82559e7f8d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for driftcheck-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for driftcheck_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.