ctx-budget

Every agent has a context budget, yet almost nobody measures it. An instruction file ships with every request. A skill body only appears when the skill loads. MCP tool definitions are a silent permanent tax—wire up four servers with fifty tools and you have bought a cost on every turn whether or not the model ever calls one. Mix all three into one number and you cannot tell what is expensive, where to intervene, or whether your Chinese text is being under-reported by a factor of two and a half.

ctx-budget splits context into two tiers: the catalog (name, capped description, trigger conditions—paid on every request) and the body (the text after frontmatter—paid only on load). It reads instruction files, skills, memory, and MCP tool dumps from the filesystem, attributes each to the correct tier, and counts characters in three buckets—ASCII, CJK, and other non-ASCII—applying a separate ratio to each while printing the raw counts so you can recompute with a real tokenizer. Duplicated blocks are reported at the tier where they actually cost money: two always-on copies waste tokens on every request; two on-demand copies cost only when both are loaded. The result is an exit code you can gate in CI—zero for within budget, three for over budget, five for something was found but not measured so no claim can be made.

Built for teams running DSH or similar agent frameworks who want a CI gate on context spend; developers writing Chinese skills or prompts who are tired of English-prose token estimates; and anyone who has stopped pasting files into a token counter one at a time with no baseline to compare against. It does not tell you what to cut—it ranks, attributes, and prints the raw numbers. The judgment about which instructions earn their tokens is yours.