AI file selection
Describe what you're trying to do and let Gemini pick the handful of files that matter — instead of hand-picking them or shipping the whole project.
How it works
Add --prompt (or -p) with your task. contextzip applies its normal rules first, then asks Gemini which of the remaining files the task needs, and packages only those — plus a prompt.txt describing the task, so the AI tool you paste into knows what you want.
~/projects/my-app
$ contextzip -p "change the toast colour on a failed login" --verbose
✓ Detected Next.js + Node.js · high confidence
✓ Gemini selected 3 files · for "change the toast colour on a failed login"
prompt.txt will be included in the ZIP
· components/ui/toast.tsx 3.4 KB
· app/login/page.tsx 6.1 KB
· lib/auth.ts 4.8 KB
✓ Saved to · .contextzip/output/prompt/vibe.zip
✓ Ready to paste
By default the selection is capped at 10 files (ai.max_files). Any path the model invents that doesn't exist in your project is dropped. The default model is gemini-2.5-flash-lite.
What is sent
File contents never leave your machine
Gemini receives your prompt, the detected stack, and the paths and sizes of files that already passed the exclusion rules. Binary files are left out of that list. Secrets were excluded before the list was built.If Gemini is rate-limited (HTTP 429), contextzip falls back to a local keyword-based selector and says so, so --prompt keeps working. Other errors — a bad key, no network — stop with a clear message instead of guessing.
~/projects/my-app
! Gemini rate limited — used keyword heuristic instead (less precise)
✓ Selected 3 files by keyword match · for "fix the login redirect"
prompt.txt will be included in the ZIP
Setting up a key
--prompt needs a free API key from Google AI Studio — no credit card. The first time you use it, contextzip walks you through getting and saving one. Or set an environment variable and skip setup entirely:
A key is only accepted if it looks like a real Gemini key (it starts with AIza), so a placeholder is caught before it turns into a confusing API error. Saved keys live in your personal config, never in the project, and the file is restricted to your user (0600) on every save.
| Command | What it does |
|---|---|
| contextzip config | Show whether a key is stored or comes from GEMINI_API_KEY |
| contextzip config --reset-key | Clear the stored key and run setup again |
| contextzip config --show-key-path | Print where the config file lives |
Previewing a selection
Combine --prompt with --dry-run to see what Gemini would pick without writing a ZIP. Add --verbose to list the chosen files.
~/projects/my-app
$ contextzip -p "refactor the auth middleware" --dry-run
✓ Scanned 2,752 files · 44 included, 2,708 excluded
✓ Gemini selected 4 files · for "refactor the auth middleware"
prompt.txt will be included in the ZIP
Dry run — no ZIP created. Remove --dry-run to package these files.
Project settings
Pin AI behaviour per project in .contextzip/config.json:
{ "ai": { "enabled": true, "max_files": 10, "prompt_template": "We use pytest, not unittest. Keep changes minimal." }}| Key | What it does |
|---|---|
| ai.enabled | Set to false to refuse --prompt with a clear message — for repos that must never call an external API |
| ai.max_files | The most files a selection may return (default 10) |
| ai.prompt_template | Added to the top of every prompt.txt — house rules the AI tool should always see |