Token Budgets And Reports

Token Budgets And Reports

ContextClean includes exact token counting for OpenAI-compatible o200k_base counts and budget-aware output packing.

Token Budget Options

Use --max-tokens when you know the target size:

ctxclean build.log --max-tokens 8000

Use --fit when you want a model preset:

ctxclean repo . --fit gpt-4.1
ctxclean repo . --fit claude-sonnet
ctxclean repo . --fit gemini-pro

Truncation Behavior

When output must be shortened, ContextClean tries to truncate at readable boundaries:

• paragraphs
• lines
• code block boundaries
• section boundaries where possible

The output includes an explanation footer when truncation is applied.

Example:

[Context Truncated: Removed 14203 tokens to fit 8000-token budget]

Reports

Reports explain why a context payload is noisy.

ctxclean report build.log --max-tokens 8000
ctxclean report ./project --format json

Report output includes:

• input tokens
• output tokens
• tokens saved
• compression ratio
• biggest noise sources
• recommended command
• removed section summary
• warnings

JSON Automation

Use --format json for dashboards, CI jobs, or tests.

Useful fields include:

• metrics.input_tokens
• metrics.output_tokens
• metrics.tokens_saved
• metrics.compression_ratio
• metrics.reduction_percent
• budget
• truncation
• removed_sections
• noise_sources
• warnings

Practical Advice

• Use report before changing cleaning mode.
• Use json when building automated checks.
• Keep benchmark claims tied to measured fixture output.
• Do not promise token savings from unmeasured data.