Every AI session I had started with the same silent ritual.
Open the project. Figure out which files are actually relevant. Remember to skip node_modules. And __pycache__. And .venv. And the lock files. Zip everything manually. Find the zip. Upload it. Then type out what I was actually trying to do, context the AI had no way of knowing.
It was maybe 5 minutes. Not a crisis. But it happened every single session, and at some point I stopped accepting it as normal.
So I built contextzip.
{% embed https://youtu.be/mHq1JH0ZJuY %}
What it does
contextzip is a CLI tool that packages exactly the right parts of your codebase into a ZIP, ready to drop into Claude, ChatGPT, or any other AI tool.
Install it once:
pip install contextzip
Then from any project:
cd your-project
contextzip
That's it. It detects your stack automatically : Next.js, Django, FastAPI, Rust, Go, Ruby, and more, applies the right exclusion rules for each, respects your .gitignore, and drops a clean ZIP into .contextzip/ at your project root. Your file manager opens with the archive already selected.
The part I'm most excited about
contextzip --prompt "Change toast color on failed login"
Describe your task in plain English. contextzip builds a lightweight file map of your project and asks Gemini to return only the files relevant to that specific task. Usually 2 to 5 files. Not your entire codebase.
The ZIP also includes a prompt.txt with your task description, so when you drop it into an AI tool, the context is already there. No retyping, no re-explaining.
This is the feature that changed how I personally work with AI tools day to day.
First-time setup: --prompt requires a free Gemini API key from Google AI Studio, no credit card needed. contextzip walks you through it on first use.
Other things it does
--git-changes
Only package files that git considers modified, staged, or untracked. Perfect for incremental debugging sessions and PR reviews where you don't need the whole project, just what changed.
contextzip --git-changes
watch mode
This one is underrated. Wrap your dev server with contextzip watch and it buffers the output in the background, watching for errors. The moment one appears, a prompt shows up beneath it:
╭─ contextzip · error detected ─────────────────────╮
│ Press [D] to package debug context [S] to skip │
╰───────────────────────────────────────────────────╯
Press D. A debug-ready ZIP lands in .contextzip/ with the error, the stack trace, and the relevant source files already inside. Your server keeps running, no restart needed.
contextzip watch -- npm run dev
contextzip watch -- python manage.py runserver
Smart exclusions by framework
contextzip stacks exclusion rules based on what it detects:
| Stack | Excluded automatically |
|---|
| Node.js / Next.js | node_modules/, .next/, dist/, lock files, *.min.js |
| Python / Django / FastAPI | __pycache__/, .venv/, *.pyc, migrations/, lock files |
| Rust | target/, Cargo.lock |
| Go | vendor/, go.sum, bin/ |
A monorepo with both package.json and pyproject.toml gets both rule sets applied automatically.
Honest limitations
--prompt requires a free Gemini API keywatch doesn't use PTY emulation, so color passthrough on Windows is limited- AI file selection is capped at 10 files by design, the goal is tight context, not comprehensive coverage
Try it
pip install contextzip
GitHub: github.com/akadeepesh/contextzip
MIT licensed, open source.
If you've been living with this friction and didn't realize it was fixable, now you know. And if you try it, I'd genuinely love to hear how it fits into your workflow.
