# Context Packer - The Webpack for AI Context
[](https://badge.fury.io/py/context-packer)
[](https://pypi.org/project/context-packer/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/MarkShawn2020/context-packer/stargazers)
> 🎯 **One file, full context** - Package your entire project into a single markdown file optimized for LLMs and documentation.
## 🌟 Why Context Packer?
In the age of AI-powered development, we face a critical challenge: **Large Language Models need complete project context**, but sharing multiple files is cumbersome and inefficient.
Just as **webpack** revolutionized JavaScript bundling and **esbuild** transformed build speeds, **Context Packer** transforms how we share code with AI models and documentation systems.
### The Problem
- 📁 **LLMs work best with single-file contexts** - No need to manage multiple uploads
- 🔄 **Modern documentation systems** (like Next.js) support single-file downloads for offline viewing
- 🤖 **AI code reviews** require complete project understanding in one shot
- 📚 **Knowledge sharing** becomes complex with scattered files
### The Solution
Context Packer intelligently bundles your entire project into a **single, AI-optimized markdown file** - complete with structure visualization, smart filtering, and symlink support for complex project organization.
## ✨ Key Features
- **🔗 Advanced Symlink Support**: Organize complex projects with symbolic links - perfect for selective file inclusion
- **🎯 AI-Optimized Output**: Formatted specifically for LLM consumption with clear structure and syntax highlighting
- **📊 Smart Filtering**: Automatically excludes build artifacts, dependencies, and binary files
- **🌳 Visual Project Tree**: Instant understanding of project structure with status indicators
- **⚡ Lightning Fast**: Efficient processing even for large codebases
- **🔧 Highly Configurable**: Fine-tune output with extensive options
## 🚀 Quick Start
### Installation
```bash
# Using pip
pip install context-packer
# Using uv (10-100x faster)
uv pip install context-packer
# Using pipx (isolated environment)
pipx install context-packer
```
### Basic Usage
```bash
# Pack current directory
ctxpack .
# Pack specific project
ctxpack /path/to/project -o project_context.md
# Pack with custom settings
ctxpack . --max-size 20 --ignore "*.test.js" "docs/*"
```
## 🎨 Advanced: The Symlink Workflow
Context Packer's **symlink support** enables a powerful workflow for complex projects where you need fine-grained control over what gets packed.
### Scenario: Selective Project Packing
Instead of using complex ignore patterns, create a "packing directory" with symlinks to exactly what you need:
```bash
# Create a packing directory
mkdir my-project-pack
cd my-project-pack
# Symlink specific files and directories
ln -s ../src/core core
ln -s ../src/utils/helpers.js helpers.js
ln -s ../config config
ln -s ../package.json package.json
ln -s ../README.md README.md
# Pack only what you've selected
ctxpack . -o ../my-project-context.md
```
### Real-World Example: Multi-Module Project
```bash
# You have a monorepo with multiple packages
project/
├── packages/
│ ├── frontend/ # React app
│ ├── backend/ # Node.js API
│ ├── shared/ # Shared utilities
│ └── mobile/ # React Native app
# Create a context for AI review of web platform only
mkdir web-platform-context
cd web-platform-context
# Link only web-related packages
ln -s ../packages/frontend frontend
ln -s ../packages/backend backend
ln -s ../packages/shared shared
ln -s ../docker-compose.yml docker-compose.yml
ln -s ../.env.example .env.example
# Generate context
ctxpack . -o web-platform.md --follow-symlinks
```
This approach gives you **surgical precision** in creating contexts for different purposes:
- 🎯 **Code Review Context**: Only the files changed in a PR
- 🏗️ **Architecture Context**: High-level structure without implementation details
- 🐛 **Debug Context**: Specific module with its dependencies
- 📖 **Documentation Context**: README files and examples only
## 📋 Output Format
Context Packer generates a structured markdown file with:
### 1. Project Structure Visualization
```
MyProject
├── src/
│ ├── index.js ✅ # High-priority file
│ ├── utils/ 🔗📁 # Symlinked directory
│ │ └── helper.js ☑️ # Included file
│ └── tests/ ⏭️ # Ignored directory
├── package.json ✅ # Configuration file
└── README.md ✅ # Documentation
```
### 2. Status Indicators
- ✅ High-priority files (configs, README)
- ☑️ Source code files
- 🔗 Symbolic links
- 🔗📁 Symlinked directories
- ⚠️ Circular reference detected
- 📊 Large files (truncated)
- ⏭️ Ignored files
### 3. Complete File Contents
Each file is presented with:
- Relative path
- Syntax highlighting
- Smart truncation for large files
- Clear section separators
## 🎯 Perfect For
### 🤖 AI Development
```bash
# Prepare context for AI analysis
ctxpack . -o for_claude.md --max-size 30
# Get AI to review your architecture
ctxpack src/ -o architecture_review.md --max-depth 2
```
### 📚 Documentation
```bash
# Create offline documentation bundle
ctxpack docs/ -o documentation.md --ignore "*.png" "*.jpg"
```
### 🔍 Code Review
```bash
# Package PR changes for review
ctxpack . -o pr_context.md --ignore "node_modules" "*.test.*"
```
### 🎓 Learning & Teaching
```bash
# Create educational material
ctxpack examples/ -o tutorial_code.md --max-files 20
```
## 🛠️ Command Line Options
| Option | Description | Default |
|--------|-------------|---------|
| `project_path` | Directory to pack | Required |
| `-o, --output` | Output file path | `{project}_context_{timestamp}.md` |
| `--ignore` | Additional ignore patterns | None |
| `--max-size` | Maximum total size (MB) | 10 |
| `--max-files` | Maximum number of files | 100 |
| `-L, --max-depth` | Maximum directory depth | Unlimited |
| `--follow-symlinks` | Follow symbolic links | Yes |
| `--no-follow-symlinks` | Don't follow symbolic links | No |
| `-v, --verbose` | Show detailed progress | No |
## ⚡ Performance Tips
1. **Large Codebases**: Use `--verbose` to monitor progress
2. **Selective Packing**: Use symlinks for precise control
3. **Size Management**: Adjust `--max-size` based on LLM limits
4. **Speed Optimization**: Use `--max-depth` to limit traversal
## 🔒 Security & Best Practices
- **Automatic Exclusions**: `.env`, `.git`, `node_modules` are ignored by default
- **Gitignore Respect**: Honors your `.gitignore` patterns
- **Size Limits**: Prevents accidental huge outputs
- **Review Before Sharing**: Always check output before sending to third parties
## 🧑💻 Development
### Setting up with UV (Recommended)
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and setup
git clone https://github.com/MarkShawn2020/context-packer.git
cd context-packer
# Install in development mode
uv pip install -e .
uv pip install -r requirements-dev.txt
# Run tests
uv run pytest
```
### Quick Commands
```bash
make test # Run tests
make lint # Check code quality
make format # Format code
make build # Build package
make publish # Publish to PyPI
```
## 📦 Publishing
With PyPI token configured:
```bash
# One-command publish (with version bump)
make release VERSION=patch # or minor, major
# Or manual steps
python bump_version.py patch
git commit -am "Bump version"
git tag v1.2.3
git push --tags
make publish
```
## 🌍 Ecosystem
Context Packer is part of the modern AI development workflow:
- **Use with Claude, GPT-4, Gemini** for code analysis
- **Integrate with CI/CD** for automatic documentation
- **Combine with AI editors** like Cursor, Windsurf
- **Works with documentation systems** like Docusaurus, Next.js
## 🤝 Contributing
We welcome contributions! Context Packer is designed to be the definitive solution for project context packaging.
### Ideas for Contribution
- 🎨 GUI interface (planned)
- 🔌 Plugin system for custom processors
- 🌐 Web service API
- 📊 Context analytics
- 🔄 Incremental packing
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
Created by [MarkShawn2020](https://github.com/MarkShawn2020) to solve the real-world challenge of sharing complete project context with AI models. Inspired by the elegance of webpack and the speed of esbuild, Context Packer brings the same innovation to AI-assisted development.
---
<div align="center">
**🚀 Transform how you share code with AI**
[Documentation](https://github.com/MarkShawn2020/context-packer#readme) •
[Issues](https://github.com/MarkShawn2020/context-packer/issues) •
[PyPI](https://pypi.org/project/context-packer/) •
[Releases](https://github.com/MarkShawn2020/context-packer/releases)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "context-packer",
"maintainer": "MarkShawn2020",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, chatgpt, claude, code-review, context, documentation, gemini, llm, markdown, packaging, project, symlinks",
"author": "MarkShawn2020",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/83/fc/e9e76048a38ff00b584519893e4cfa5b1d71df2ed484ec2f909c2b8fc10e/context_packer-1.1.5.tar.gz",
"platform": null,
"description": "# Context Packer - The Webpack for AI Context\n\n[](https://badge.fury.io/py/context-packer)\n[](https://pypi.org/project/context-packer/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/MarkShawn2020/context-packer/stargazers)\n\n> \ud83c\udfaf **One file, full context** - Package your entire project into a single markdown file optimized for LLMs and documentation.\n\n## \ud83c\udf1f Why Context Packer?\n\nIn the age of AI-powered development, we face a critical challenge: **Large Language Models need complete project context**, but sharing multiple files is cumbersome and inefficient. \n\nJust as **webpack** revolutionized JavaScript bundling and **esbuild** transformed build speeds, **Context Packer** transforms how we share code with AI models and documentation systems.\n\n### The Problem\n- \ud83d\udcc1 **LLMs work best with single-file contexts** - No need to manage multiple uploads\n- \ud83d\udd04 **Modern documentation systems** (like Next.js) support single-file downloads for offline viewing\n- \ud83e\udd16 **AI code reviews** require complete project understanding in one shot\n- \ud83d\udcda **Knowledge sharing** becomes complex with scattered files\n\n### The Solution\nContext Packer intelligently bundles your entire project into a **single, AI-optimized markdown file** - complete with structure visualization, smart filtering, and symlink support for complex project organization.\n\n## \u2728 Key Features\n\n- **\ud83d\udd17 Advanced Symlink Support**: Organize complex projects with symbolic links - perfect for selective file inclusion\n- **\ud83c\udfaf AI-Optimized Output**: Formatted specifically for LLM consumption with clear structure and syntax highlighting\n- **\ud83d\udcca Smart Filtering**: Automatically excludes build artifacts, dependencies, and binary files\n- **\ud83c\udf33 Visual Project Tree**: Instant understanding of project structure with status indicators\n- **\u26a1 Lightning Fast**: Efficient processing even for large codebases\n- **\ud83d\udd27 Highly Configurable**: Fine-tune output with extensive options\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Using pip\npip install context-packer\n\n# Using uv (10-100x faster)\nuv pip install context-packer\n\n# Using pipx (isolated environment)\npipx install context-packer\n```\n\n### Basic Usage\n\n```bash\n# Pack current directory\nctxpack .\n\n# Pack specific project\nctxpack /path/to/project -o project_context.md\n\n# Pack with custom settings\nctxpack . --max-size 20 --ignore \"*.test.js\" \"docs/*\"\n```\n\n## \ud83c\udfa8 Advanced: The Symlink Workflow\n\nContext Packer's **symlink support** enables a powerful workflow for complex projects where you need fine-grained control over what gets packed.\n\n### Scenario: Selective Project Packing\n\nInstead of using complex ignore patterns, create a \"packing directory\" with symlinks to exactly what you need:\n\n```bash\n# Create a packing directory\nmkdir my-project-pack\ncd my-project-pack\n\n# Symlink specific files and directories\nln -s ../src/core core\nln -s ../src/utils/helpers.js helpers.js\nln -s ../config config\nln -s ../package.json package.json\nln -s ../README.md README.md\n\n# Pack only what you've selected\nctxpack . -o ../my-project-context.md\n```\n\n### Real-World Example: Multi-Module Project\n\n```bash\n# You have a monorepo with multiple packages\nproject/\n\u251c\u2500\u2500 packages/\n\u2502 \u251c\u2500\u2500 frontend/ # React app\n\u2502 \u251c\u2500\u2500 backend/ # Node.js API \n\u2502 \u251c\u2500\u2500 shared/ # Shared utilities\n\u2502 \u2514\u2500\u2500 mobile/ # React Native app\n\n# Create a context for AI review of web platform only\nmkdir web-platform-context\ncd web-platform-context\n\n# Link only web-related packages\nln -s ../packages/frontend frontend\nln -s ../packages/backend backend \nln -s ../packages/shared shared\nln -s ../docker-compose.yml docker-compose.yml\nln -s ../.env.example .env.example\n\n# Generate context\nctxpack . -o web-platform.md --follow-symlinks\n```\n\nThis approach gives you **surgical precision** in creating contexts for different purposes:\n- \ud83c\udfaf **Code Review Context**: Only the files changed in a PR\n- \ud83c\udfd7\ufe0f **Architecture Context**: High-level structure without implementation details \n- \ud83d\udc1b **Debug Context**: Specific module with its dependencies\n- \ud83d\udcd6 **Documentation Context**: README files and examples only\n\n## \ud83d\udccb Output Format\n\nContext Packer generates a structured markdown file with:\n\n### 1. Project Structure Visualization\n```\nMyProject\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 index.js \u2705 # High-priority file\n\u2502 \u251c\u2500\u2500 utils/ \ud83d\udd17\ud83d\udcc1 # Symlinked directory\n\u2502 \u2502 \u2514\u2500\u2500 helper.js \u2611\ufe0f # Included file\n\u2502 \u2514\u2500\u2500 tests/ \u23ed\ufe0f # Ignored directory\n\u251c\u2500\u2500 package.json \u2705 # Configuration file\n\u2514\u2500\u2500 README.md \u2705 # Documentation\n```\n\n### 2. Status Indicators\n- \u2705 High-priority files (configs, README)\n- \u2611\ufe0f Source code files\n- \ud83d\udd17 Symbolic links\n- \ud83d\udd17\ud83d\udcc1 Symlinked directories \n- \u26a0\ufe0f Circular reference detected\n- \ud83d\udcca Large files (truncated)\n- \u23ed\ufe0f Ignored files\n\n### 3. Complete File Contents\nEach file is presented with:\n- Relative path\n- Syntax highlighting\n- Smart truncation for large files\n- Clear section separators\n\n## \ud83c\udfaf Perfect For\n\n### \ud83e\udd16 AI Development\n```bash\n# Prepare context for AI analysis\nctxpack . -o for_claude.md --max-size 30\n\n# Get AI to review your architecture\nctxpack src/ -o architecture_review.md --max-depth 2\n```\n\n### \ud83d\udcda Documentation\n```bash\n# Create offline documentation bundle\nctxpack docs/ -o documentation.md --ignore \"*.png\" \"*.jpg\"\n```\n\n### \ud83d\udd0d Code Review\n```bash\n# Package PR changes for review\nctxpack . -o pr_context.md --ignore \"node_modules\" \"*.test.*\"\n```\n\n### \ud83c\udf93 Learning & Teaching\n```bash\n# Create educational material\nctxpack examples/ -o tutorial_code.md --max-files 20\n```\n\n## \ud83d\udee0\ufe0f Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `project_path` | Directory to pack | Required |\n| `-o, --output` | Output file path | `{project}_context_{timestamp}.md` |\n| `--ignore` | Additional ignore patterns | None |\n| `--max-size` | Maximum total size (MB) | 10 |\n| `--max-files` | Maximum number of files | 100 |\n| `-L, --max-depth` | Maximum directory depth | Unlimited |\n| `--follow-symlinks` | Follow symbolic links | Yes |\n| `--no-follow-symlinks` | Don't follow symbolic links | No |\n| `-v, --verbose` | Show detailed progress | No |\n\n## \u26a1 Performance Tips\n\n1. **Large Codebases**: Use `--verbose` to monitor progress\n2. **Selective Packing**: Use symlinks for precise control\n3. **Size Management**: Adjust `--max-size` based on LLM limits\n4. **Speed Optimization**: Use `--max-depth` to limit traversal\n\n## \ud83d\udd12 Security & Best Practices\n\n- **Automatic Exclusions**: `.env`, `.git`, `node_modules` are ignored by default\n- **Gitignore Respect**: Honors your `.gitignore` patterns\n- **Size Limits**: Prevents accidental huge outputs\n- **Review Before Sharing**: Always check output before sending to third parties\n\n## \ud83e\uddd1\u200d\ud83d\udcbb Development\n\n### Setting up with UV (Recommended)\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and setup\ngit clone https://github.com/MarkShawn2020/context-packer.git\ncd context-packer\n\n# Install in development mode\nuv pip install -e .\nuv pip install -r requirements-dev.txt\n\n# Run tests\nuv run pytest\n```\n\n### Quick Commands\n```bash\nmake test # Run tests\nmake lint # Check code quality\nmake format # Format code\nmake build # Build package\nmake publish # Publish to PyPI\n```\n\n## \ud83d\udce6 Publishing\n\nWith PyPI token configured:\n\n```bash\n# One-command publish (with version bump)\nmake release VERSION=patch # or minor, major\n\n# Or manual steps\npython bump_version.py patch\ngit commit -am \"Bump version\"\ngit tag v1.2.3\ngit push --tags\nmake publish\n```\n\n## \ud83c\udf0d Ecosystem\n\nContext Packer is part of the modern AI development workflow:\n\n- **Use with Claude, GPT-4, Gemini** for code analysis\n- **Integrate with CI/CD** for automatic documentation\n- **Combine with AI editors** like Cursor, Windsurf\n- **Works with documentation systems** like Docusaurus, Next.js\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Context Packer is designed to be the definitive solution for project context packaging.\n\n### Ideas for Contribution\n- \ud83c\udfa8 GUI interface (planned)\n- \ud83d\udd0c Plugin system for custom processors\n- \ud83c\udf10 Web service API\n- \ud83d\udcca Context analytics\n- \ud83d\udd04 Incremental packing\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\nCreated by [MarkShawn2020](https://github.com/MarkShawn2020) to solve the real-world challenge of sharing complete project context with AI models. Inspired by the elegance of webpack and the speed of esbuild, Context Packer brings the same innovation to AI-assisted development.\n\n---\n\n<div align=\"center\">\n\n**\ud83d\ude80 Transform how you share code with AI**\n\n[Documentation](https://github.com/MarkShawn2020/context-packer#readme) \u2022 \n[Issues](https://github.com/MarkShawn2020/context-packer/issues) \u2022 \n[PyPI](https://pypi.org/project/context-packer/) \u2022 \n[Releases](https://github.com/MarkShawn2020/context-packer/releases)\n\n</div>",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligently package project directories into a single markdown file for AI analysis",
"version": "1.1.5",
"project_urls": {
"Changelog": "https://github.com/MarkShawn2020/context-packer/releases",
"Documentation": "https://github.com/MarkShawn2020/context-packer#readme",
"Homepage": "https://github.com/MarkShawn2020/context-packer",
"Issues": "https://github.com/MarkShawn2020/context-packer/issues",
"Repository": "https://github.com/MarkShawn2020/context-packer.git"
},
"split_keywords": [
"ai",
" chatgpt",
" claude",
" code-review",
" context",
" documentation",
" gemini",
" llm",
" markdown",
" packaging",
" project",
" symlinks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "49deafc97e8958445ea994724d97545766d635b943f4c5e891be5a5b2f03df23",
"md5": "3792425037b6ad3007855a92e03ca201",
"sha256": "8fa08eb713e5f79affe30122b9560813ecf8d71a2dc7cb3e94ae17c7c97d8da8"
},
"downloads": -1,
"filename": "context_packer-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3792425037b6ad3007855a92e03ca201",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12933,
"upload_time": "2025-08-25T02:24:23",
"upload_time_iso_8601": "2025-08-25T02:24:23.596587Z",
"url": "https://files.pythonhosted.org/packages/49/de/afc97e8958445ea994724d97545766d635b943f4c5e891be5a5b2f03df23/context_packer-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "83fce9e76048a38ff00b584519893e4cfa5b1d71df2ed484ec2f909c2b8fc10e",
"md5": "4d37d285d3c337c699d864aec1434085",
"sha256": "0537d89f4df375b370fd4b593c02152632bb4b6683474ee48dbd7652d6e6ca61"
},
"downloads": -1,
"filename": "context_packer-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "4d37d285d3c337c699d864aec1434085",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12911,
"upload_time": "2025-08-25T02:24:24",
"upload_time_iso_8601": "2025-08-25T02:24:24.875357Z",
"url": "https://files.pythonhosted.org/packages/83/fc/e9e76048a38ff00b584519893e4cfa5b1d71df2ed484ec2f909c2b8fc10e/context_packer-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 02:24:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MarkShawn2020",
"github_project": "context-packer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "context-packer"
}
JSON
