AI-powered file selection.
Describe what you're trying to do, and let Gemini pick the handful of files that actually matter — instead of hand-picking them or shipping the whole project.
How it works
Add --prompt and describe your task in plain English. contextzip scans the project, builds a lightweight file map (paths and sizes, not full contents), and asks Gemini to return the minimum set of files needed for that task — typically 2 to 5, never more than 10. The resulting ZIP is a tightly scoped archive with only what you'd actually open to make the change.
~/projects/my-app
$ contextzip --prompt "Change toast color on failed login"
Asking Gemini for the minimum relevant files…
→ components/ui/toast.tsx, app/login/page.tsx, lib/auth.ts
Wrote .contextzip/output/codebase.zip — 3 files, 4.2 KB, includes prompt.txt
The ZIP always includes a prompt.txt describing the task, so when you drop the archive into Claude, ChatGPT, or any other AI tool, it immediately understands what you're trying to do — no need to retype the request.
First-time setup
--prompt needs a key from Google AI Studio. contextzip walks you through obtaining and saving one the first time you use it, or you can skip setup entirely with an environment variable. A key is only accepted if it looks like a real Gemini key (starts with AIza) — a malformed or placeholder value is caught before it turns into a confusing API error.
Saved keys live in your OS user-config directory (e.g. ~/.config/contextzip/config.json on Linux/macOS, %APPDATA%\contextzip\config.json on Windows) and that file's permissions are locked down to your user only (0600) on every save.
contextzip configcontextzip config --reset-keycontextzip config --show-key-pathPreviewing a selection
Combine --prompt with --dry-run to see exactly which files Gemini would select, without creating a ZIP or spending an upload on a selection you haven't reviewed yet.
~/projects/my-app
$ contextzip --prompt "Refactor auth middleware" --dry-run
Would select 4 files:
middleware/auth.ts, lib/session.ts, lib/jwt.ts, types/auth.d.ts
No ZIP written — preview only
Project-level AI settings
A team can pin AI-selection behaviour in the committed project config, so every contributor gets the same defaults without re-typing flags.
| Key | Description |
|---|---|
| ai.enabled | If false, --prompt is refused with a clear message instead of silently ignored |
| ai.provider | Reserved for future providers — only "gemini" is currently supported |
| ai.max_files | Caps how many files the AI selector may return (default 10) |
| ai.prompt_template | Prepended to every generated prompt.txt — house conventions the AI tool should always see, e.g. "We use pytest, not unittest." |
See the full schema, including how this fits alongside always_include and workspace settings, in project configuration.
Ready to close the loop?
Once the AI tool hands changes back, apply-zip writes them into your project safely.