Contextpack — AI skill for Claude Code

contextpack

Compile a repository into a lean, reusable context bundle for AI agents - Claude, GPT, Codex, Cursor, anything that reads a file. It preserves **decisions and constraints**, not just file summaries, and it warns when a proposal violates a locked decision.

npx contextpack .                 # writes CONTEXTPACK.md
npx contextpack . --for all       # + CLAUDE.md, AGENTS.md, .cursor/rules/contextpack.mdc, contextpack.gpt.txt, contextpack.json
npx contextpack . --budget 6k     # target ~6k estimated tokens (low-value sections trimmed first)
npx contextpack check plan.md     # does this plan violate a locked decision? exit 2 if so
git diff | npx contextpack check . -
npx contextpack check . --staged  # pre-commit: check staged changes

Zero dependencies, Node 20+. Nothing leaves your machine.

What goes in the bundle

1. Identity - name, README's first paragraph, branch.
2. Stack - runtime, languages, frameworks (from manifests), entry points, tests, scripts, Docker.
3. Locked decisions - the part agents keep re-litigating. Rendered as rules with rationale, scope, and "do not introduce" lists.
4. Current milestone / open work - unchecked boxes from TODO.md / ROADMAP.md / CURRENT_TASK.md / .agent/*.md, plus TODO/FIXME markers in code.
5. Architecture - directory layout with counts, most-imported local modules (JS/TS/Python import graph), largest files.
6. Recent changes - last commits with touched files, hot files of the last 14 days, uncommitted work.
7. How to work here - conventions derived from the above, including the test command.

Sections have priorities; `--budget` drops complete low-priority sections first. Identity and locked decisions are always retained, even if they exceed the budget. Tokens are estimated as JavaScript string length / 4 (rounded up), not counted with a model tokenizer; export wrappers and structured JSON are outside this budget.

Recording decisions

Any of these are pi