Mole

Everything you need to trust code you didn't write, in the editor you already use — why it's built this way, whether that's still true, and whether an agent's "done" is real. One install. No new tab. No tokens for the checks.

check   release   license: MIT

Works inside tools you already have

Mole reads/writes plain files (markdown decisions, optionally existing ADR/MADR folders), not a proprietary format, so it adds to the tools below instead of replacing them.

Already in your stackWhat Mole adds there
Claude CodeA plugin (/plugin install mole): SessionStart, PreToolUse and Stop hooks put decisions and past fixes in the agent's context automatically.
VS Code (and forks)The original mole-code-map panel — a code map beside the file you're editing — kept as one feature.
Any MCP client — Codex, Cursor, Gemini CLI, Claude Desktopmole-mcp: the same decisions/map/check/recall tools over MCP.
ADR folders / MADR / spec-kitmole check --spec-kit --adr-dir DIR reads existing ADR-style records directly — no migration required.
GitHub Actions / any CImole rules --emit writes rule files a normal CI job or PR check can run with no Mole-specific runner.

Architecture

flowchart LR subgraph repo["Your repo"] dec[".mole/decisions/*.md + existing ADR/MADR"] src["source tree (TypeScript/TSX)"] end subgraph molepkg["mole-code (one npm package)"] cli["mole CLI: check / rules / map / impact"] mcp["mole-mcp (stdio MCP server)"] daemon["background daemon (TS compiler API + SQLite)"] end subgraph surfaces["Surfaces you already use"] cc["Claude Code plugin (hooks)"] vscode["VS Code extension"] agents["Codex / Cursor / Gemini CLI / Claude Desktop"] ci["CI / PR check"] end dec --> cli src --> daemon daemon --> cli cli --> mcp cli -- "--emit" --> ci mcp --> agents cli --> cc daemon --> vscode

No model call anywhere in this diagram — the daemon, CLI, rule checks and MCP tools are all local and deterministic.

The problem, plainly

Teams write decisions in Slack threads, PR comments and people's heads. Agents write code fast and don't know those decisions exist unless someone pastes them in every time. Nobody re-checks an old decision against the code it governs, so it's wrong in production before anyone notices. Mole keeps a small number of team decisions as plain files next to the code, and checks them for free, every time — no LLM call, no dashboard, no separate tool to remember to run.

See it work (30 seconds)

This is a real, unedited run of npx -y mole-code demo against a packed mole-code tarball in a clean install directory (no repo checkout, no network beyond the initial install). Press play, or just read it straight through below.

npx -y mole-code demo

Install

Mole is one npm package (mole-code) underneath every surface below.

Claude Code plugin

/plugin marketplace add raychu23/mole-code-map
/plugin install mole

VS Code / Open VSX

Download the .vsix from the releases page and code --install-extension <file>. Marketplace listings planned.

CLI, any repo

npx mole-code --help

MCP (Codex / Cursor / Gemini CLI / Claude Desktop)

{ "mcpServers": { "mole": { "command": "npx", "args": ["-y", "-p", "mole-code", "mole-mcp"] } } }

Full per-client config snippets are in the repo README.

What it does, by job

Verified numbers, with sources

ClaimNumber
Test selection catches the same regressions as running everything10/10 regressions caught running 1.2% of the suite (163/14,065 tests)
No-model decision-conflict checker vs. an LLM judge28/29 caught vs 29/29; ~half the false alarms (4/60 vs 9/60); ~13× lower estimated inference cost — not a demonstrated accuracy edge, model labels not human-audited
Incremental re-check vs. full re-solve (one ICCMA19 graph)p50 7.17 ms vs 2,081.87 ms, 15/15 matching results — a specific benchmark, not a universal claim

Full citations (file + line) are in the repo README's "Verified numbers" section and the full methodology — including the honest negative result above — is in docs/how-we-measure.md. We also say plainly where Mole has not shown a win: in a pre-registered 72-run agent-task benchmark (dcbench, 8 tasks × 3 setups × 3 runs), Mole's hooks scored 23.6% of decision-compliance points vs 27.6% with a rules file and 31.7% with no context (not significant) — we do not claim a productivity gain anywhere on this site.

Limits