Skip to main content
Glama
README.md
# driftcheck

[![PyPI](https://img.shields.io/pypi/v/driftcheck-mcp)](https://pypi.org/project/driftcheck-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/driftcheck-mcp)](https://pypi.org/project/driftcheck-mcp/)
[![CI](https://github.com/sauravmodi03/driftcheck-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sauravmodi03/driftcheck-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

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

![driftcheck catching two stale facts in a CLAUDE.md](docs/demo.gif)

`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`, 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.

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