Context Crumb

Use when an agent needs to read, inspect, summarize, or load large local prose-heavy files cheaply before sending them into LLM context. Best for Markdown docs, notes, meeting transcripts, issue threads, logs with narrative text, research dumps, and other natural-language files where exact wording is less important than preserving useful context.

Purpose

Use ContextCrumb as a cheap first pass before reading large local text files into an LLM context window. It compresses by deleting lower-value words and punctuation while keeping the remaining text in original order.

ContextCrumb is for orientation and triage. Treat compressed output as shortened context, not authoritative source text.

When To Use

Use it before reading large natural-language files:

• Documentation and Markdown
• Notes and research dumps
• Meeting transcripts
• Issue threads and long discussions
• Logs with lots of prose
• Long comments or narrative text

When Not To Use

Do not rely on compressed output for exact syntax or exact wording:

• Source code
• Config files
• Diffs and patches
• JSON, YAML, TOML, XML, or schemas
• Commands that may need to be copied exactly
• Legal, compliance, policy, or contract text

For these files, read the raw source. If a file is too large, use ContextCrumb only to find likely relevant sections, then open the raw file around those sections before editing, quoting, or copying anything.

Default Workflow

If contextcrumb is already installed, use golden mode by default:

contextcrumb load <file>

If the CLI is not installed and this is a one-off read, run it from PyPI:

uvx --from contextcrumb contextcrumb load <file>

If repeated local use is expected, install it once:

python -m pip install contextcrumb

Then use:

contextcrumb load <file>

Golden mode chooses an adaptive cutoff for each file and is the preferred default because it is conservative. If the output is still too large, use a fixed keep ratio only after checking the tradeoff:

contextcrumb load <file> --target-keep-ratio 0.75
contextcrumb load <file> --target-keep-ratio 0.5

Avoid aggressive ratios for first-pass reading unless the user explicitly asks for heavy compression.

Validation

Check compression savings without dumping the full output:

contextcrumb inspect <file>

Check what was removed before trusting a compressed result:

contextcrumb diff <file>

Use JSON only when another tool needs stats:

contextcrumb load <file> --json

Read the text field as compressed context. Use stats.token_keep_ratio, stats.word_keep, and stats.model_windows to decide whether to retry with a different setting.

Practical Rules

• Use contextcrumb load <file> as the default.
• Use uvx --from contextcrumb contextcrumb load <file> for no-install one-off use.
• Use installed CLI for repeated use.
• Use inspect and diff before trusting compressed text for important work.
• Never edit code, copy commands, or quote exact wording based only on compressed output.