CLAUDE.md budget linter plugin — concept

Routing decided 2026-07-10: this belongs inside the os-doc-hygiene plugin, not a standalone plugin — managing CLAUDE.md is doc-hygiene's responsibility. Injected session-context prompts (os-context) count toward the effective CLAUDE.md instruction budget and should be noted when doc-hygiene runs.

Status: idea only, deliberately out of scope as of 2026-07-08. Revisit after the system-prompt-profiles work (cc-os/docs/plans/system-prompt-profiles-assessment.md). Source discussion: cc-os session 2026-07-08; maintenance philosophy drawn from ~/servers/proxmox-hermes/docs/claude-md-maintenance.md.

Problem

CLAUDE.md degrades silently: bloat, stale facts, and instruction overload collapse rule adherence (community guidance: ~100 lines of instruction; adherence degrades uniformly past ~150–200 instructions). Measured example: cc-os CLAUDE.md reached ~11k tokens — ~10x a sane budget — by accreting an implementation-status changelog.
Pruning is currently manual and memory-dependent ("review it monthly") — exactly the kind of discipline that erodes. Nothing enforces a ceiling, and one "just this once" exception becomes unbounded growth because the exception is never quantified.
The same failure mode applies project-wide: docs that outgrow progressive disclosure, copies instead of pointers, files nobody re-reads.

Goal

Deterministic, config-driven enforcement of context budgets — zero AI tokens on the happy path — with a human-in-the-loop escalation only when a budget is exceeded. Exceptions are explicit, quantified, and re-checked, so agreed growth stays bounded instead of becoming the new normal.

How it works (mid-level)

Hook → linter. A SessionStart (or periodic) hook runs a deterministic linter over CLAUDE.md. In range → no output, no action, 100% deterministic, no model call.
Per-project dot-config (JSON for easy slurping, e.g. .claude-md-lint.json or a key in an existing .cc-os/config): default budget (e.g. 1k tokens), cadence (check_every_days), and an exceptions block — each exception records the agreed limit, the specific reason, and who/when agreed (e.g. "allowed 1.2k because X, agreed 2026-07-08"). The linter checks against the effective limit, so an exception raises the ceiling without removing it.
Out of range → maintenance agent. Only then does an AI step run: it assesses the file (stale sections, changelog accretion, copies-vs-pointers, @-import opportunities) and proposes suggestions to the user.
User resolves: accept the pruning suggestions, push back, or codify a new quantified exception in the config. Never auto-edit CLAUDE.md — automated writes are the known failure mode (noise accumulation, contradictory rules, safety-rule drift).
Cadence control: config decides whether the hook checks every session or every N days (stamp in a gitignored state dir, same pattern as os-doc-hygiene's .dochygiene/).

Possible extension: whole-project checks

The same skeleton (deterministic scan → config budgets → agent escalation) generalizes to weekly project hygiene: file-size ceilings, progressive-disclosure usage (pointers vs inlined copies), stale-doc detection, dead @-imports.

Build-time considerations

Overlap with os-doc-hygiene is significant — it already does deterministic SessionStart reminders, per-project gitignored state, AI-assisted classification, and git-safe cleanup for stale/bloated docs. First design question at build time: is this a new os-* plugin or a CLAUDE.md-specific check + budget-config feature inside os-doc-hygiene (and/or an os-status check for "CLAUDE.md over budget")?
Read cc-os-plugin-skill-naming-convention.md before naming anything.
Token measurement should be deterministic and cheap (chars/4 heuristic or a local tokenizer — pick one and freeze it; the budget is a contract, so the measure can't drift).
Eval approach exists: same deterministic-first checker + ladder playbook as the other os-* plugins.

4.8 KiB Raw Blame History Unescape Escape