Skip to content
Back to search

driftcheck-mcp

Verify the claims in agent-context docs (CLAUDE.md, runbooks) against the live system. CLI + read-only MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sauravmodi03--driftcheck-mcp/badge.svg)](/listings/sauravmodi03--driftcheck-mcp)

HTML

<a href="/listings/sauravmodi03--driftcheck-mcp"><img src="/api/listings/sauravmodi03--driftcheck-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uvx driftcheck CLAUDE.md # run without installing uv tool install driftcheck # or install the CLI uv tool install "driftcheck[mcp]" # CLI + MCP server

(From a checkout: `uv run driftcheck CLAUDE.md`.)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 122 lines
  1. # driftcheck
  2. **Your agent's context files rot. driftcheck tells you which facts are no longer true.**
  3. `CLAUDE.md`, runbooks and memory notes say things like "the app listens on
  4. :3000", "restarts use `foo.service`", "the code lives in repo X". When those
  5. go stale, an agent acts on them with full confidence. `driftcheck` extracts
  6. the checkable claims from markdown and verifies each one against the live
  7. system. It is deterministic: no LLM is involved in checking.
  8. - Zero runtime dependencies (stdlib only); the MCP server is an optional extra.
  9. - Read-only: it never changes files, services or repos.
  10. - Exit code 1 on drift, so it drops into CI or a systemd timer.
  11. ## Install
  12. uvx driftcheck CLAUDE.md # run without installing
  13. uv tool install driftcheck # or install the CLI
  14. uv tool install "driftcheck[mcp]" # CLI + MCP server
  15. (From a checkout: `uv run driftcheck CLAUDE.md`.)
  16. ## Usage
  17. driftcheck CLAUDE.md # report drift only
  18. driftcheck CLAUDE.md --all # also list ok / unverifiable / skipped
  19. driftcheck docs/ ~/notes/ # directories: every *.md inside
  20. driftcheck CLAUDE.md --json # machine-readable
  21. driftcheck CLAUDE.md --scope mac # also check claims tagged scope=mac
  22. ## What it checks
  23. | Claim in the doc | How it is verified |
  24. |---|---|
  25. | `` `~/bin/tool` ``, `` `/etc/foo.conf` `` | the path exists |
  26. | `http://127.0.0.1:3000`, `localhost:2222` | something accepts connections |
  27. | `foo.service`, `bar.timer` | systemd unit exists and is healthy (failed units and inactive timers are drift) |
  28. | `forge:owner/repo`, repo URLs on your Forgejo | the repo exists via the Forgejo API |
  29. Each result is one of `ok`, `drift`, `unverifiable` (could not be checked
  30. reliably, e.g. Forgejo unreachable) or `skipped` (out of scope).
  31. ## Claims that are true somewhere else
  32. A doc often describes several machines. Tag claims that only hold elsewhere
  33. so they do not raise false alarms:
  34. tunnel 127.0.0.1:12222 <!-- driftcheck: scope=mac --> # checked only with --scope mac
  35. <!-- driftcheck: ignore --> # alone on a line: skips the next line
  36. Scoped claims are `skipped` unless the scope is active (`--scope X` or
  37. `$DRIFTCHECK_SCOPE`).
  38. ## Run it on a schedule
  39. `driftcheck timer` generates a systemd user timer. The schedule, targets and
  40. scope are all arguments. It prints the units by default (a dry run):
  41. driftcheck timer CLAUDE.md notes/ # daily 04:10, print only
  42. driftcheck timer CLAUDE.md --at 07:30 --install # daily at 07:30, write + enable
  43. driftcheck timer CLAUDE.md --calendar "Mon..Fri 08:00" --scope pod --install
  44. driftcheck timer docs/ --name docs-check --calendar hourly --install # several schedules: use --name
  45. driftcheck timer --name docs-check --remove # disable and delete
  46. `--calendar` takes any systemd `OnCalendar` expression. Other options:
  47. `--exec` (command that runs driftcheck, default the one on `PATH`),
  48. `--no-persistent` (skip runs missed while the machine was off),
  49. `--unit-dir`, and `--no-enable` (write files only). To change a schedule, run the
  50. command again with new arguments. Drift makes the run fail, so it shows up in
  51. `systemctl --user --failed` and `journalctl --user -u <name>.service`.
  52. ## Demo
  53. `examples/stale-runbook.md` is a runbook that has rotted (reproducible on any Linux machine):
  54. ```
  55. $ driftcheck examples/stale-runbook.md --all
  56. DRIFT examples/stale-runbook.md:3 path /tmp/driftcheck-demo/build.sh - /tmp/driftcheck-demo/build.sh does not exist
  57. DRIFT examples/stale-runbook.md:4 port 127.0.0.1:9 - nothing listening (Connection refused)
  58. DRIFT examples/stale-runbook.md:5 unit old-worker.service - no such systemd unit (user or system)
  59. DRIFT examples/stale-runbook.md:6 path /tmp/driftcheck-demo-config.yaml - /tmp/driftcheck-demo-config.yaml does not exist
  60. OK examples/stale-runbook.md:7 path /etc/hostname - exists
  61. 5 claims: 1 ok, 4 drift, 0 unverifiable, 0 skipped
  62. ```
  63. ## MCP server
  64. Lets an agent check its own context before acting. One read-only tool:
  65. `check_docs(paths, include_ok=false, scope=null)`.
  66. claude mcp add --scope user driftcheck -- uvx --from "driftcheck[mcp]" driftcheck-mcp
  67. ## Forgejo configuration
  68. Repo claims use `$FORGEJO_URL` (default `http://127.0.0.1:3000`). The token is
  69. read from `$FORGEJO_TOKEN` or `~/.config/forgejo-token.env`, sent only to that
  70. URL and never printed. Without a token, private repos report as not found.
  71. ## Design decisions
  72. - **Deterministic over clever.** Checks are plain probes (stat, connect,
  73. `systemctl`, one API call). An LLM can read the report; it should not
  74. produce it.
  75. - **Never cry wolf.** A tool that raises false alarms gets ignored. Anything
  76. it cannot judge reliably is `unverifiable`, not `drift`. A path like
  77. `/user/tokens/verify` (an API route, no such top-level directory) is
  78. `unverifiable`; a missing file under a real directory is `drift`.
  79. - **Scope is explicit.** Claims that are true on another machine are tagged,
  80. not guessed at.
  81. ## Limitations
  82. 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
  83. holds X, Y, Z" is not parsed. Only the claim forms in the table above are
  84. extracted.
  85. ## Development
  86. uv run python -m unittest discover -s tests
  87. MIT licensed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.