DEV Community

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

Posted on

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

#ai #cli #productivity #showdev

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
Enter fullscreen mode Exit fullscreen mode

Then from any project:

cd your-project
contextzip
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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  │
╰───────────────────────────────────────────────────╯
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)