CLI

The contextcrumb command is the direct interface for shells, editor tasks, hooks, and agent tools.

Use load when a tool needs compressed context. Use compress when you are experimenting with inline text or stdin. Use batch when you want compressed files on disk.

Load A File For Context

Use load when the next step is an LLM or agent context window:

contextcrumb load path/to/notes.md

It prints compressed text only, so another command or model prompt can consume it directly.

Useful options:

contextcrumb load notes.md --target-keep-ratio 0.5
contextcrumb load notes.md --json
contextcrumb load notes.md --json --return-tokens
contextcrumb load notes.md --receipt
contextcrumb load notes.md --no-stats

--receipt keeps compressed text on stdout and writes a compact receipt to stderr:

ContextCrumb receipt: notes.md tokens 12,400->4,100, saved 8,300 (66.9%), keep_ratio=0.331, mode=threshold, raw-read-before-exact-use=false

With --json --receipt, the receipt is included as a top-level JSON field.

File Safety

ContextCrumb uses compression.content_mode = "auto" by default. Prose files are compressed normally. Supported code files use code-aware compression: source code is preserved exactly, and only comments/docstrings are compressed.

Initial code-aware languages are Python, JavaScript, TypeScript, JSX, TSX, Go, and Rust. Other syntax-sensitive file types are refused by default, including diffs, JSON/YAML/TOML/XML, lockfiles, shell scripts, SQL, .env files, and common package manifests where exact structure matters.

For exploratory compression only, override the guard:

contextcrumb load script.py --force

When --force is used, read the raw source before editing, quoting, copying commands, or relying on exact structure.

Override file handling for one command:

contextcrumb load script.py --content-mode code-comments
contextcrumb load notes.md --content-mode prose
contextcrumb load config.json --content-mode raw

Set persistent defaults:

contextcrumb config show
contextcrumb config set compression.content_mode code-comments
contextcrumb config set code.comment_target_keep_ratio 0.55
contextcrumb config unset compression.content_mode

Compress Inline Text Or Stdin

Compress inline text:

contextcrumb compress --text "A long prose-heavy paragraph about project decisions and constraints."

Compress a file through the general command:

contextcrumb compress notes.md

Pipe stdin on macOS or Linux:

cat notes.md | contextcrumb compress

On Windows PowerShell, the equivalent is:

Get-Content notes.md | contextcrumb compress

Inspect

Use inspect to see compression stats:

contextcrumb inspect notes.md

Example fields:

• Mode
• Backend
• Model windows
• Chars
• Words
• Tokens
• Threshold when using threshold mode

Diff

Use diff to build trust or tune settings:

contextcrumb diff notes.md

Deleted tokens are wrapped with [- and -].

Batch

Compress many files into another directory:

contextcrumb batch docs --glob "*.md" --out compressed-docs

The output directory mirrors the input directory structure.

Use --json when automation needs a summary of every output file:

contextcrumb batch docs --glob "*.md" --out compressed-docs --json

Stats

ContextCrumb writes a local stats ledger by default. View it:

contextcrumb stats
contextcrumb stats --json
contextcrumb stats --since 7d
contextcrumb stats --share

Disable stats for a command:

contextcrumb load notes.md --no-stats

Disable stats globally:

CONTEXTCRUMB_STATS=0 contextcrumb load notes.md

On Windows PowerShell:

$env:CONTEXTCRUMB_STATS = "0"
contextcrumb load notes.md