Pack codebases, directories, and Git diffs into token-budgeted, LLM-ready context.
Website Β· MCP Spec Β· GitHub Action Β· FastPress Labs
ContextPack is a 100% free, zero-runtime-dependency CLI, Node.js library, and Model Context Protocol (MCP) server that turns any codebase, subdirectory, or Git diff into clean, token-budgeted context for Claude, GPT, DeepSeek, and coding agents.
It formats context in Anthropic-standard XML (<documents><document>), Markdown, or llms-full.txt, includes an ASCII/Unicode directory tree, integrates staged/unstaged Git diffs, and respects token budgets so your prompts never overflow.
- β‘ Zero runtime dependencies: Pure Node.js standard library (
node:fs,node:path,node:child_process,node:crypto). Fast startup, zero supply-chain risk. - π― Token-Budget Aware: Specify
--max-tokens 32k(or64k,128k). ContextPack prioritizes key files and warns if files had to be omitted. - π€ First-Class MCP Server: Native stdio MCP server (
contextpack-mcp) ready for Claude Code, OpenCode, Cursor, and Zed with tools forpack_codebase,get_tree,pack_diff, andestimate_tokens. - π Smart Filtering: Automatically respects
.gitignore, skips binary files, and ignores build artifacts (node_modules,dist, lockfiles). - π Git Diff Integration: Pack only changed files, staged files, or append full git diffs with line-level context.
- π οΈ Composite GitHub Action: Pack repos in CI/CD pipelines and export token counts and packed artifacts for LLM review steps.
# Pack current directory into Anthropic XML format
npx -p github:fastpresspages/contextpack contextpack .
# Pack into Markdown with a 32,000 token budget
npx -p github:fastpresspages/contextpack contextpack src/ -f markdown -t 32k -o context.md
# Pack only Git diff & modified files against main
npx -p github:fastpresspages/contextpack contextpack . --git-diff --diff-target main -o diff-context.xml
# Just generate an ASCII directory tree with file sizes
npx -p github:fastpresspages/contextpack contextpack . --tree-only
# Generate an llms-full.txt file for your documentation site
npx -p github:fastpresspages/contextpack contextpack . --llms-txt -o site/llms-full.txtAdd ContextPack to your Claude Desktop, OpenCode, or Cursor MCP configuration:
{
"mcpServers": {
"contextpack": {
"command": "npx",
"args": ["-y", "-p", "github:fastpresspages/contextpack", "contextpack-mcp"]
}
}
}Available MCP tools:
pack_codebase: Pack directory or files into token-capped XML, Markdown, or llms.txt.get_tree: Return visual directory structure with token estimates and file counts.pack_diff: Pack staged or unstaged Git diffs with changed file contents.estimate_tokens: Fast token count approximation for any text or local file.
Strict prompt structure modeled on Anthropic best practices:
<documents>
<directory_tree>
βββ src/
β βββ index.js (1.2 KB)
β βββ pack.js (8.4 KB)
βββ package.json (820 B)
</directory_tree>
<document index="1">
<source>src/index.js</source>
<document_content>
1: export * from './pack.js';
...
</document_content>
</document>
</documents>Clean, human-readable markdown with language code blocks:
# Codebase Context
## Directory Tree
\`\`\`
...
\`\`\`
## Codebase Contents
### `src/index.js`
\`\`\`javascript
1: export * from './pack.js';
...
\`\`\`Structured context designed for /llms-full.txt endpoints following the llms.txt convention.
Usage: contextpack [target_dir_or_file] [options]
Options:
-o, --out <path> Write output to file instead of stdout
-f, --format <format> Output format: xml, markdown, llms, json (default: xml)
-t, --max-tokens <tokens> Token budget ceiling (e.g. 16k, 32k, 128k, 200000)
-g, --git-diff Include Git diff in output
--staged Include only staged changes in Git diff
--diff-target <ref> Git ref to diff against (e.g. main, HEAD~1)
--tree-only Output only the visual directory tree
--tokens-only Calculate and print token estimation only
--llms-txt Shortcut for --format llms
--include <pattern> Comma-separated glob-style patterns to include
--exclude <pattern> Comma-separated glob-style patterns to exclude
--max-depth <n> Maximum directory traversal depth (default: 8)
--max-file-size <kb> Max file size in KB to include (default: 500)
--no-tree Omit the directory tree from context
--no-line-numbers Omit 1-based line numbers in file content
--summary Print packing summary to stderr
-v, --version Show ContextPack version
-h, --help Show help information
Use fastpresspages/contextpack in your GitHub Workflows to prepare context for automated AI PR reviews, changelog generation, or docs updates:
- name: Pack Repository Context
uses: fastpresspages/contextpack@main
id: pack
with:
path: '.'
format: 'xml'
max-tokens: '64k'
with-tree: 'true'
git-diff: 'true'
out: 'context.xml'
- name: Inspect Packing Stats
run: |
echo "Packed ${{ steps.pack.outputs.files }} files"
echo "Total tokens: ${{ steps.pack.outputs.tokens }}"
echo "Omitted files: ${{ steps.pack.outputs.omitted }}"ContextPack can be imported directly in ESM or Node 18+:
import { pack, countTokens, buildTree } from 'contextpack';
const result = await pack({
path: './src',
format: 'xml',
maxTokens: 32000,
includeTree: true,
includeGitDiff: false
});
console.log(`Packed ${result.totalFiles} files (${result.tokens} tokens)`);
console.log(result.output);ContextPack includes a comprehensive native test suite using node:test:
# Run unit & integration tests
node --test test/*.test.js
# Test CLI directly
node bin/contextpack.js . --tokens-onlyApache-2.0. Maintained by FastPress Labs. Free forever, no telemetry, no paid APIs.