fatcheck

Agent instruction files (CLAUDE.md, AGENTS.md, and the rest) only grow. Adding a rule is cheap. Deleting one without knowing why it was there feels unsafe. fatcheck is a weigh-in: count the rules, record the why in a sidecar the agent never loads, and prune only after you pick the cuts.

pip install fatcheck
fatcheck scan

Demo (messy-repo)

Before, on the bundled fixture:

              fatcheck scan
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━┓
┃ file                           ┃ kind   ┃ instr ┃ lines ┃ bytes ┃ ~tok ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━┩
│ .cursor/rules/ts.mdc           │ cursor │     1 │     7 │   121 │   30 │
│ .github/copilot-instructions.md│ copilot│     1 │     1 │    47 │   11 │
│ AGENTS.md                      │ codex  │     4 │     6 │   168 │   42 │
│ CLAUDE.md                      │ claude │     2 │    15 │   171 │   42 │
│ frontend/AGENTS.md             │ codex  │     1 │     1 │    38 │    9 │
│ shim/CLAUDE.md [shim]          │ claude │     0 │     1 │    11 │    2 │
└────────────────────────────────┴────────┴───────┴───────┴───────┴──────┘
total instructions: 9
~136 tokens (bytes/4, estimate)

lint flags uncommented rules and a TypeScript line copied into both CLAUDE.md and AGENTS.md. After notes plus prune --apply:

AGENTS.md — falsified on-call rule gone; TypeScript kept (canonical file):

# Agents

- Use TypeScript for all new application code.
- Run tests before every pull request.
- Prefer small pull requests.

CLAUDE.md — duplicate TypeScript line gone; secrets rule kept:

# Team

Never commit API keys or secrets.

Notes live in .fatcheck.yml, not in the prompt.

Install

Python 3.11+.

pip install fatcheck
# or: pipx install fatcheck
# or: uvx fatcheck scan

From a clone, for development:

pip install -e ".[dev]"

Day-one flow

First lint is a wall of missing. Freeze that, then CI only fails on new uncommented rules.

fatcheck scan
fatcheck init --baseline
fatcheck lint              # new missing / copies (size is a scan warning)
fatcheck lint --strict     # all missing, ignore baseline
fatcheck lint --off missing
fatcheck annotate          # numbered why (writes .fatcheck.yml only)
fatcheck prune             # numbered diffs, nothing written
fatcheck prune --apply     # pick 1,3 or all, then y/N (writes *.bak)
fatcheck prune --apply --only all --yes   # scripts; --yes alone will not apply everything

--json and --path work on scan, lint, and prune. lint --sarif fatcheck.sarif writes SARIF 2.1 for GitHub code scanning. Exit 0 when clean, 1 when there are findings. lint never writes .fatcheck.yml (hash rematch is applied by init / annotate).

Hooks (write-time, fail open)

Copy-paste, not a plugin per vendor. If an agent instruction file changed, remind the maintainer to record why.

Other repos can pin this project as a pre-commit hook:

- repo: https://github.com/shunvel/fatcheck
  rev: v0.2.1
  hooks:
    - id: fatcheck       # copies / noise; does not fail on uncommented rules
    - id: fatcheck-new   # new missing vs .fatcheck-baseline.yml (run init --baseline first)

Optional .fatcheck.toml in the repo root:

canonical = "agents"    # agents | claude | longest
ignore_local = true     # skip CLAUDE.local.md

How to read the output

• ~tok — bytes/4, a rough prompt-size estimate, not a tokenizer.
• missing — no note in .fatcheck.yml (grandfathered per file if listed in .fatcheck-baseline.yml).
• noise — a note that is too vague.
• copied_file — two whole files look like copies. Keep the canonical one (agents by default).
• duplicate — the same rule in two files that are otherwise different.
• size_claude / size_codex — over the published soft limits (200 lines / 32 KB). Shown by scan, not a lint failure.

prune proposes prune_falsified (your note says the rule did not help; if recurrence >= 1, it says “failed N times”) and prune_duplicate. Safety-marked rules are left alone. Deletes match the current instruction text, so a moved line still gets found.

Files it finds

No config required. Among others: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cursor/rules/, GEMINI.md. It skips README.md, .git, node_modules, vendor, site-packages, .venv, generated, third_party, and paths deeper than 8 directories. CLAUDE.local.md is skipped unless ignore_local = false.

Consumer SARIF workflow: examples/github/sarif.yml. Later versions: bump the version, tag v*, and .github/workflows/publish.yml uploads to PyPI.

Where this idea comes from

Kushal Chakrabarti, Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding (arXiv:2608.11095). Public GitHub agent files more than tripled over their life; net adds piled up; old rules almost never came out except in a wipe. The paper’s advice is to write what failed, what you tried, and whether it helped. fatcheck is an independent tool. It is not affiliated with the paper’s author.

Today’s coding tools put the whole instruction file into the prompt. fatcheck keeps notes in .fatcheck.yml so the agent never sees them.

Honest limits

fatcheck cannot recover why a two-year-old rule exists. It does not invent a why. It only deletes lines after prune --apply and a pick you confirm. Leave prune off CI.

Tests

pytest
ruff check src tests

Checklist: tests/TEST_MATRIX.md. Fixture: fixtures/messy-repo.