Skip to main content
Glama

ContextPack πŸ“¦

Pack codebases, directories, and Git diffs into token-budgeted, LLM-ready context.

CI License: Apache-2.0 Runtime Dependencies: 0 Node >= 18.17 MCP Server

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.

Why ContextPack?

  • ⚑ 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 (or 64k, 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 for pack_codebase, get_tree, pack_diff, and estimate_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.


Related MCP server: redcon

Quick Start

1. Run via npx (no install required)

# 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.txt

2. Connect to AI Agents via MCP

Add 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.


Output Formats

1. XML (--format xml / default)

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>

2. Markdown (--format markdown)

Clean, human-readable markdown with language code blocks:

# Codebase Context

## Directory Tree
\`\`\`
...
\`\`\`

## Codebase Contents

### `src/index.js`
\`\`\`javascript
1: export * from './pack.js';
...
\`\`\`

3. LLMS Full Text (--format llms / --llms-txt)

Structured context designed for /llms-full.txt endpoints following the llms.txt convention.


CLI Options

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

GitHub Action

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 }}"

Node.js Programmatic API

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);

Verification & Testing

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-only

License

Apache-2.0. Maintained by FastPress Labs. Free forever, no telemetry, no paid APIs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides LLM-optimized tools for advanced code analysis, repository complexity evaluation, and call graph generation. It enables users to visualize directory structures, detect code patterns, and build semantic context with significant token savings.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Deterministic repository context packing for AI coding agents: selects, compresses, and budgets only the files a task needs. Measured 83% fewer input tokens at the same task coverage, fully local, no LLM in the loop.
      9
      24 PyPI
      9
      Functional Source , Version 1.1, MIT Future
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to pack entire repositories into XML, Markdown, JSON, or plain text, with token-reducing compression, content analysis, pattern search, remote GitHub repository support, and built-in security scanning.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Deterministic, local-first context optimization for AI coding agents. Automatically compresses raw development session data (messages, tool logs, error stack traces, and git diffs) into a compact, task-specific context window. Operates 100% locally with zero external LLM dependencies, ensuring your source code never leaves your machine.
      6
      103 npm
      MIT