Unwritten

Catch the files you — or your AI agent — forgot to change. Unwritten learns

from your git history which files usually change together and warns when one is

missing from your edit: "you changed `OrderService.cs` but not

`OrderServiceTests.cs`, and they change together 94% of the time." It calls

these missing companions *holes*, and every warning comes with its confidence

score and real example commits as proof.

1 possible hole(s):

  src/Orders/OrderServiceTests.cs
    expected because you changed src/Orders/OrderService.cs
    confidence 0.826 (90 co-changes in 100 changes)
    e.g. 3f2a1c9 Add surcharge handling to freight calculation

FAIL: at least one hole at confidence >= 0.70.

It runs as an MCP server so AI coding agents (Claude Code, Copilot) can check

their own edits mid-session, and as a CLI for pre-commit hooks.

One `dotnet tool execute`, an index in `.unwritten/`, no server, no subscription,

no tokens.

Works on any language. File-level rules only need git history, so hole

detection works the same on Python, TypeScript, Go, or mixed repos. C# repos

additionally get method-level rules and cosmetic-edit filtering; JSON files get

key-level noise filtering. Running the tool requires the

.NET SDK (10+), but the repos it

analyzes can be anything.

Quick start

From your repo's root:

1. Warm up the index (optional — every command builds it on first use and keeps it current by itself; this just makes the first query fast).

dotnet tool execute Unwritten --yes -- reindex

2. Register as an MCP server (Claude Code):

claude mcp add unwritten -- dotnet tool execute Unwritten --yes -- mcp

3. (Recommended if using Claude Code) Make the check deterministic — a git pre-commit hook and a Claude Code Stop hook that feeds failing holes back to the agent before a commit is made:

dotnet tool execute Unwritten --yes -- install-hook --git --claude-code

That's it — your agent can now call `check_holes` after editing, and the hooks

catch the cases where it forgets to.

Explanatory video

https://github.com/user-attachments/assets/4ae7a22d-c611-458f-8c48-08f87eca1d29

See it in action

`stats` shows what the tool has learned — here, one file pair coupled strongly

enough (confidence ≥ 0.7) to block a commit if one side is missing:

After editing one file of that pair, `check` warns that its companion is

missing and spells out the three ways to resolve it — update the companion,

commit anyway, or mute the rule:

With the pre-commit hook installed, the same check runs automatically on every

commit and blocks it while the companion is still missing:

Documentation

Everything else lives in **docs/README.md**:

• Background & the research behind it
• Why these thresholds (tested on real data)
• Use: MCP server, CLI, hooks, muting false rules
• Configuration reference
• How it works
• What it does NOT do (yet)

License

MIT