Your Codebase Is Too Big for an AI. Here's How to Give It Only What Matters

akadeepesh — Wed, 27 May 2026 06:10:00 +0000

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.

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 key
watch 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.