This is a free, open-source tool built by a solo founder. If it saves you time or tokens, please:
Every star & sponsor helps a solo founder keep building free tools for everyone. 🙏
Stop copy-pasting files one-by-one into ChatGPT/Claude/Cursor. Stop dumping your entire codebase and wasting tokens. contextpack analyzes your dependency graph, scores each file by relevance, and packages only what matters — so your AI gets exactly the context it needs. Nothing more, nothing less.
84% of developers say AI doesn't have enough context. So what do you do?
- Copy-paste files one-by-one into ChatGPT/Claude/Cursor → takes 20 minutes, you miss files
- Use repopack which dumps every single file → wastes 70%+ of your token budget on irrelevant code
- Describe your codebase from memory → AI hallucinates APIs, invents imports, gives wrong advice
The result? AI gives you mediocre answers. You waste precious tokens. You go back to debugging alone.
| Pain Point | You | With repopack | With contextpack |
|---|---|---|---|
| ⏱ Time to prepare context | 10-20 min | 2 sec | 2 sec |
| 🎯 Relevant files included | ❌ You guess | ❌ All files (bloated) | ✅ Only what matters |
| 💰 Tokens wasted | 0% (you give nothing) | 70%+ | <10% |
| 🧠 AI answer quality | Poor (no context) | Poor (too much noise) | Great (signal only) |
| 📊 Dependency awareness | Manual | None | Automatic graph |
# Scan current directory → AI-ready context in 2 seconds
contextpack .
# Claude-optimized XML output
contextpack . --format xml
# Preview what will be included
contextpack . --dry-run
# Stay within token budget
contextpack . --max-tokens 4000
# Auto-regenerate on file changes
contextpack . --watch➜ contextpack . --dry-run
✔ Scanned 15 files, found 50 dependencies
src/scanner/index.ts (typescript, 3466 bytes)
src/analyzers/base.ts (typescript, 276 bytes)
src/utils/filesystem.ts (typescript, 3073 bytes)
src/cli.ts (typescript, 4175 bytes)
...
Total: 15 files | ~7838 tokens | 50 dependencies
| Feature | contextpack | repopack |
|---|---|---|
| 🧠 Dependency graph | ✅ PageRank centrality | ❌ None |
| 📊 Relevance scoring | ✅ 6-factor scoring (0-100) | ❌ No scoring |
| 💰 Token budget | ✅ Soft limit + intelligent selection | ❌ Hard limit only |
| 🐍 Python support | ✅ Full import analysis | ❌ Parser only |
| 👁 Watch mode | ✅ File watcher | ❌ Not available |
| 📊 Stats command | ✅ Deep repo insights | ❌ Not available |
| 📝 XML format | ✅ Claude-optimized | ❌ Not available |
| 🌳 Directory tree | ✅ Interactive tree | ❌ Not available |
| ⚡ CLI speed | ✅ Sub-second | ✅ Sub-second |
| 🔓 License | ✅ MIT | ✅ MIT |
Bottom line: repopack is great for dumb file concatenation. contextpack is smart — it understands your code structure, ranks files by importance, and gives your AI exactly what it needs.
| Feature | Description |
|---|---|
| 🧠 Intelligent Context Selection | Dependency graph analysis with PageRank centrality — not dumb concatenation |
| 💰 Token Optimized | Stays within your budget (default 8K, configurable). Files ranked by relevance score |
| 📝 Format Your Way | Plain text (ChatGPT), XML (Claude), JSON (programmatic), Directory tree |
| 🔒 Git-Aware | Respects .gitignore, skips binaries, filters node_modules |
| 🔍 Dependency Analysis | JS/TS imports + exports + require, Python imports, generic references |
| 👁 Watch Mode | Auto-regenerate on file changes |
| 👀 Dry Run | Preview what will be included before generating context |
| 📊 Stats | Get repository insights — files, tokens, languages, structure |
# Install globally
npm install -g contextpack
# Scan current directory → AI-ready context
contextpack .
# Save output for pasting into ChatGPT/Claude
contextpack . > context.txt
# See what would be included
contextpack . --dry-runcontextpack . --format plain # Plain text — ChatGPT optimal (default)
contextpack . --format xml # XML tagged — Claude optimal
contextpack . --format json # JSON — programmatic use
contextpack . --format directory # Directory tree onlycontextpack . --files src/main.ts,src/utils.ts # Only specific files
contextpack . --exclude "*.test.ts,*.spec.ts" # Exclude patterns
contextpack . --max-tokens 4000 # Token budget (default: 8000)
contextpack . --max-size 500000 # Max file size in bytes
contextpack . --depth 2 # Dependency depth (default: 3)contextpack . --dry-run # Preview without output
contextpack . --watch # Auto-regenerate on file change
contextpack stats . # Show repository stats
contextpack init # Generate contextpack.json config
contextpack --version # Show versioncontextpack traverses your directory, applying three filters:
| Filter | What it skips |
|---|---|
| .gitignore | Respects your existing git rules |
| Binary detection | Images, videos, archives, compiled files |
| Size limits | Files larger than 1MB (configurable) |
Every file is analyzed for its dependencies:
graph LR
A[main.ts] --> B[helper.ts]
A --> C[lib/utils.ts]
D[app.py] --> E[config.py]
D --> F[models/user.py]
| Language | What's detected |
|---|---|
| TypeScript/JavaScript | import, require, export * from, dynamic import() |
| Python | import, from ... import, relative imports |
| Generic | File references in strings, configs, templates |
The graph computes PageRank-like centrality to find the most important files in your codebase.
Each file gets a score (0–100) based on:
| Factor | Weight | Why |
|---|---|---|
| 📍 Centrality | 40% | Core files matter more |
| 🚪 Entry point | 20% | Main/index files are critical |
| 🔄 Recent changes | 15% | What you just edited is relevant |
| 🧪 Test penalty | -10% | Tests dilute context |
| 📏 Size penalty | -5% | Huge files waste tokens |
| 🌐 Language match | +5% | Match project's primary language |
Files are selected by score within your token budget. If the highest-scored file alone exceeds the budget, it's still included (better than nothing).
=== File: src/main.ts ===
import { helper } from './helper';
=== File: src/helper.ts ===
export function helper(): string {
return 'hello';
}
--- Summary ---
2 files | 1,234 tokens | 4 dependencies
Best paired with this prompt:
I will provide context from my codebase. Analyze the code and answer
my questions based on this context.
[contextpack output]
<?xml version="1.0" encoding="UTF-8"?>
<contextpack>
<summary>
<files>2</files>
<tokens>1234</tokens>
<dependencies>4</dependencies>
</summary>
<files>
<file path="src/main.ts" tokens="800" language="typescript">
<![CDATA[import { helper } from './helper';]]>
</file>
</files>
</contextpack>Best paired with this prompt:
I will provide a contextpack of my codebase in XML format. Analyze
the code and answer my questions based on this context.
[contextpack output]
Generate a contextpack.json file:
contextpack init{
"exclude": ["*.test.*", "*.spec.*", "dist/", "build/"],
"maxTokens": 8000,
"maxSize": 1048576,
"maxDepth": 3,
"format": "plain"
}# .github/workflows/contextpack.yml
name: Generate AI Context
on: [push]
jobs:
context:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g contextpack
- run: contextpack . --format json > ai-context.json
- uses: actions/upload-artifact@v4
with:
name: ai-context
path: ai-context.json| Use Case | How contextpack Helps |
|---|---|
| Code Review | Package changed files + their dependencies for AI review |
| Bug Fixing | Send relevant context + error logs to ChatGPT/Claude |
| Onboarding | Give new devs a concise codebase overview |
| Documentation | Generate context for AI-powered docs generation |
| Migration | Package specific modules for refactoring assistance |
| PR Description | Auto-generate PR summaries from code context |
- CLI with Commander
- Dependency graph (JS/TS, Python)
- Relevance scoring (6-factor)
- Multiple output formats (plain, XML, JSON, directory)
- Gitignore support
- Watch mode
- Tree-sitter integration (v0.2) — AST-level analysis, not regex
-
.contextpackignore(v0.2) — custom ignore patterns - Interactive file selector (v0.3) — pick files in terminal
- VS Code extension (v0.4) — one-click context generation
- GitHub Actions integration (v0.5) — auto context on PR
- Multi-repo support (v0.6) — monorepo-aware context
- Token-accurate counting (v0.7) — per-model tokenizers
git clone https://github.com/FMATheNomad/contextpack.git
cd contextpack
npm install
npm run build
npm link
contextpack .npm testsrc/
├── cli.ts # CLI entry point (Commander)
├── scanner/ # File scanning & dependency graph
│ ├── index.ts # Main scanner
│ ├── dependency-graph.ts # PageRank centrality
│ ├── relevance.ts # 6-factor scoring
│ └── stats.ts # Repository statistics
├── analyzers/ # Language-specific import analysis
│ ├── base.ts # Analyzer interface
│ ├── imports.ts # JS/TS imports
│ ├── python-imports.ts # Python imports
│ └── generic.ts # Generic file references
├── formatters/ # Output formatters
│ ├── base.ts # Formatter interface
│ ├── plain.ts # Plain text (ChatGPT)
│ ├── xml.ts # XML (Claude)
│ ├── json.ts # JSON (programmatic)
│ └── directory.ts # Directory tree
├── filters/ # File filtering
│ ├── gitignore.ts # .gitignore respect
│ ├── binary.ts # Binary detection
│ └── size.ts # Size limits
└── utils/ # Shared utilities
├── filesystem.ts # File operations
├── logger.ts # Output formatting
├── token-counter.ts # Token estimation
└── config.ts # Config management
PRs are welcome! See CONTRIBUTING.md for guidelines.
- Add a new language analyzer
- Add a new output formatter
- Improve the relevance scoring algorithm
- Report bugs or suggest features
MIT © FMA Software Labs
