🌿 context-budget v1.0.0 · MIT

Fail loudly when context/prompt files exceed a character budget — before the LLM runtime silently truncates them.

The problem

LLM agent frameworks (OpenClaw and friends) inject "core files" (persona, memory, instructions) into the prompt on every run, with a hard character cap (e.g. 35 000). Past the cap, content is cut without any error — the agent just loses part of its memory and nobody notices. This tool turns that silent failure into an exit code you can put in a cron.

What it does

Measures any list of files against a per-file character budget.
Warns early — default threshold: last 2.5% of the budget (--warn to override).
Missing file = critical (exit 2): a renamed/deleted core file is exactly the kind of silent breakage you want surfaced.
Cron-friendly: --json output, exit codes 0 ok · 1 warning zone · 2 over budget / missing.
Zero dependencies, Python ≥ 3.8, single module.

Install (pip)

pip install context-budget @ git+https://mandrilly.com/git/context-budget.git

Usage

context-budget 35000 SOUL.md AGENTS.md USER.md      # core files vs 35K budget
context-budget 35000 *.md --json                    # machine-readable
context-budget 20000 MEMORY.md --warn 19000         # custom warn threshold

Sample output:

[OK  ] SOUL.md: 21535/35000 chars (13465 remaining)
[WARN] MEMORY.md: 34901/35000 chars (99 remaining)
[OVER] NOTES.md: 35621/35000 chars

Exit codes

Code	Meaning
`0`	all files within budget
`1`	at least one file in the warning zone
`2`	at least one file over the limit or missing (truncation imminent/active)

Tests

python -m unittest discover -s tests   # 5 tests → OK

Source

git clone https://mandrilly.com/git/context-budget.git