cram

Pack your codebase into an LLM context bundle — interactively, within a token budget, keeping the files that matter.

The problem

You want to hand your repo to Claude, GPT, or Gemini — but the whole thing blows past the context window. So you copy‑paste a few files, forget the important one, and paste half a node_modules by accident.

cram fixes that. Point it at a directory and it shows your repo as a live token map. Give it a budget — say 100k tokens — and it auto‑fits the most important files into that budget, then hands you a clean bundle for your model. Tweak the selection by hand in the TUI, or run it headless in CI.

# No install, no npm account, no API key — run it straight from the repo:
npx github:pjw81226/cram

That's it. (Prefer npm? Once it's published this shortens to npx cram-cli.)

Why cram

• 🎛️ Interactive TUI — browse your repo as a tree with a live token bar per file and a budget gauge up top. Toggle files with space and watch the gauge react.
• 🎯 Budget auto‑fit — --budget 100k (or a model preset) and cram greedily packs the highest‑value files until the budget is full. It never goes over.
• 🧠 Smart ranking — cram keeps the files that matter. Source over tests, entry points over fixtures, recently‑touched over stale, README + manifest always anchored. Not just "biggest first."
• 🔌 Local & instant — tokenization runs locally (OpenAI o200k/cl100k). No API key, no upload, works offline. One npx and you're in.
• 📤 Three formats — Markdown, Claude‑optimized XML, or plain text — each with a file tree and token summary header.
• 🧵 Headless mode — pipe it, write a file, or copy to clipboard. Perfect for scripts and CI.

Quick start

Run it with no install, straight from the repo:

npx github:pjw81226/cram

Or install the cram command once and call it anywhere:

git clone https://github.com/pjw81226/cram && cd cram
npm install && npm link          # builds + puts `cram` on your PATH

cram                                   # interactive TUI
cram . --budget 100k -o context.md     # auto-fit to 100k tokens
cram src --model claude --copy         # pack src/ for Claude → clipboard

Once it's published to npm, install shortens to npm i -g cram-cli (the command stays cram), or a one‑off npx cram-cli.

The interactive TUI

Run cram in a terminal with no output flags and you get the packer:

| Key | Action | |-----|--------| | ↑/↓ (or j/k) | Move the cursor | | space | Toggle a file (or a whole folder) in/out | | →/← | Expand / collapse a folder | | a | Auto‑fit — re‑select the best files for the current budget | | n | Clear the selection | | [ / ] | Decrease / increase the budget | | m | Cycle the target model (updates budget + encoding) | | f | Cycle the output format | | / | Fuzzy‑filter files by path | | c | Copy the bundle to the clipboard | | w | Write the bundle to a file | | q | Quit |

The gauge turns green → yellow → red as you approach and exceed the budget. Manual selections are yours to keep; a re‑fits automatically.

Headless / CLI

When stdout isn't a TTY (piped), or you pass -o/-c/--stdout, cram runs headless: scan → rank → fit → emit.

cram [dir] [options]

| Option | Description | |--------|-------------| | -m, --model <id> | Target model preset (default gpt-4o). See --list-models. | | -b, --budget <n> | Token budget, e.g. 100k, 1.5m (default: the model's context window). | | -f, --format <fmt> | markdown (default), xml, or plain. | | -o, --output <file> | Write the bundle to a file. | | -c, --copy | Copy the bundle to the clipboard. | | --stdout | Force the bundle to stdout. | | --focus <text> | Bias ranking toward a task, e.g. --focus "auth flow". | | --ignore <glob> | Extra ignore glob (repeatable). | | --all | Include files normally ignored by default. | | --no-gitignore | Don't honor .gitignore. | | -i, --interactive | Force the TUI. | | --list-models | List model presets and exit. |

# Fit to a GPT-4o context window, pipe into your tool of choice
cram . | pbcopy

# Focus the selection on a feature area
cram . --budget 80k --focus "payment webhooks" -o context.md

# Claude-optimized XML, everything under 150k tokens
cram . --model claude --budget 150k --format xml -o context.xml

Stats print to stderr, so stdout stays clean for piping.

How ranking works

When the whole repo won't fit, cram decides what to keep with a deterministic importance score per file:

• Path signals — src/, lib/, entry points (index, main, cli) score high; test/, fixtures/, examples/, vendor/, generated and dist/ files score low.
• Anchors — README and the primary manifest (package.json, pyproject.toml, go.mod, Cargo.toml) are floored high so context always has an anchor.
• Recency — recently modified files (by git/mtime) get a boost.
• Shape — shallower paths and real code beat deep, generated, or data files.
• Focus — --focus "…" boosts files whose path/content match your task.

Then the selector fills your budget first‑fit by importance: it takes the most important files that fit and skips (without stopping at) any single file too large for the remaining room. The result is guaranteed to stay within budget.

Models & token counting

cram --list-models shows the presets (GPT‑4o, o1, GPT‑4, Claude, Gemini, …). Each maps to an encoding, a default context window, and a rough input price for the cost estimate.

A note on Claude & Gemini. Anthropic and Google don't publish a local tokenizer, so cram approximates their counts with OpenAI's o200k_base and flags the model as ~approx. It's close, but treat those numbers as estimates. OpenAI models are exact.

Budget vs. bundle. The budget applies to your source content tokens — the code cram selects. The output wrapper (headers, file tree, code fences) adds a small, predictable overhead on top. Leave a little headroom if you're near a hard limit.

Comparison

repomix and gitingest are excellent tools. cram's angle is the interactive, budget‑first workflow — see and shape exactly what goes in.

| | cram | repomix | gitingest | |--|:--:|:--:|:--:| | Interactive TUI | ✅ | — | — | | Live token gauge | ✅ | — | — | | Budget auto‑fit | ✅ | — | — | | Importance ranking | ✅ | — | — | | Output formats | md · xml · plain | md · xml · plain | txt | | Headless / CI | ✅ | ✅ | ✅ | | Clipboard | ✅ | ✅ | — | | Remote repo URLs | — | ✅ | ✅ | | Runs with | npx (Node) | npx (Node) | pipx (Python) |

How it works

scanner → tokenizer → ranker → selector → formatter
  fs        o200k/      score     budget     md/xml/
 walk       cl100k    per file    knapsack   plain

Each stage is a small, pure, independently‑tested module. The TUI and the headless CLI are two front‑ends over the same pipeline.

Contributing

Issues and PRs welcome — model prices/windows drift, ignore rules can always be smarter, and more output formats are easy to add.

git clone https://github.com/pjw81226/cram
cd cram
npm install
npm test        # 96 tests across the pipeline
npm run build   # bundle to dist/cli.js
node dist/cli.js .   # dogfood it on itself

Regenerate the demo GIF with vhs: vhs demo.tape.

License

MIT