The problem
You set up Claude for your project months ago. A CLAUDE.md describing the
architecture. A few skills. Some agents. Then the project kept moving — files
got renamed, the deploy flow changed, you swapped Redux for Zustand, a directory
moved.
Your Claude artifacts didn't move with it.
Now Claude confidently follows a skill that points at a file that no longer
exists, or a CLAUDE.md that describes an architecture you abandoned. Stale
context produces wrong work — quietly, every session.
ClaudeDrift is a Claude Code plugin that audits all of those artifacts against
your actual codebase, shows you exactly where they've drifted, and offers to fix
them. Run it on demand.
Three kinds of drift it catches
| |
|---|
| 🔗 Reference drift | A path, command, or script an artifact names no longer exists. |
| 🧠 Context drift | The description of your architecture, workflow, tech stack, or conventions no longer matches the code — even when every file path still resolves ("we use Redux" → you're on Zustand). |
| 🧭 Legacy narration | The artifact is accurate, but carries superseded-history framing a steering doc shouldn't — "Use Laravel Sail (previously Herd)", "X replaced Y", "Updated <date>: previously…". It should state today's reality, not the migration path that led there. |
Most tools can only do the first. The second and third are where the real damage
hides — context that's subtly wrong, or live instructions buried under migration
backstory Claude re-reads every session.
Reasoning, not regex
ClaudeDrift doesn't scan your docs with a pile of pattern-matching rules. It uses
Claude's own reasoning, via subagents, to read each artifact alongside the code
it describes and judge whether it's still true.
That distinction matters. A regex can't tell:
- a real path from an illustrative example (
e.g. \src/Foo.tsx`, a fenced sample, a your-component` placeholder);
- a missing file from one relative to a sub-package, crate, or dependency
(
hashql-mir/src/..., "files to modify in eufy-security-client");
- a broken reference from a path the doc creates as output or documents as
already removed;
- a path from prose where a slash means "and" (
prover/requestor, CUDA/Metal);
- a renamed command from a generic "best-practices" template that lists ideal
commands a project should have.
This project started as a deterministic scanner. Validated across ~40 real repos,
that scanner needed an endless stream of new rules for each of the cases above —
and still got them wrong at the edges. The reasoning agents got every one right by
understanding the artifact. So the scanner is gone; reasoning is the engine.
What it looks like
The one a regex could never find. In platformplatform/PlatformPlatform
(39 artifacts) an agent told Claude to "create a new tab group via
tabs_context_mcp" — a tool that exists nowhere in the repo (the project's
MCP servers are shadcn/aspire/azure-*, and the agent itself calls this "the
Chrome extension" two lines later). A hallucinated tool name that looks exactly
like a real one. ClaudeDrift cross-referenced .mcp.json, settings, and the rest
of the repo, flagged it, and proposed the one-line fix — while correctly leaving
the genuine Chrome-automation capability alone.
A dangerous one, caught. In a real TypeScript repo (2anki/server) ClaudeDrift
found src/lib/Token.ts referenced in the HARD_BLOCK_PATHS safety list of
three agents/commands — gating real "stop and use a worktree" logic — on a
file that no longer exists. The guard had quietly become a no-op. No grep would
have told you the guard itself was dead.
Context drift, caught. In a C inference engine, a refs/ reference tree was
cited as required reading by CLAUDE.md, every agent, and several commands —
but it's gitignored and absent on disk, so every "read refs/ first" workflow
silently fails. The same audit measured the actual WASM bundle (doc said 192KB,
it's ~295KB) and counted the header (15K LOC → 17.7K). Things no scanner can know.
