---
type: plan
title: "CLAUDE.md budget linter plugin — concept (deterministic hook + exception config + maintenance agent)"
summary: "Future cc-os plugin concept for keeping CLAUDE.md (and eventually whole AI projects) within deterministic token/size budgets — a hook-driven linter that stays silent in range, escalates to a maintenance agent when out of range, and records user-agreed exceptions in a per-project config so allowed growth stays bounded."
tags:
  - type/plan
  - tool/claude-code
  - domain/context-engineering
  - project/cc-os
scope: global
last_updated: 2026-07-10
date: 2026-07-08
related:
  - "[[claude-code-system-prompt-customization-surface]]"
  - "[[planka-backlog-routing-discoverability-gap]]"
---

# 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)

1. **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.
2. **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.
3. **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.
4. **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).
5. **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.