Package exactly the right parts of your codebase and paste it into any AI tool — in one command.
pip install contextzipEvery AI session starts the same way: hunt down the relevant files, manually skip node_modules, build artifacts, and lock files, zip them, find the zip, upload it. Then do it all again next session.
contextzip eliminates that entirely. Run it from your project root — it detects your stack, applies smart exclusions, produces a lean ZIP, and opens your file manager with the archive already selected. One Ctrl+C and you're done.
- Smart framework detection — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
- Respects
.gitignore— your existing ignore patterns are honoured automatically - Git-aware packaging — use
--git-changesto package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions - AI-powered file selection — describe your task in plain English with
--promptand Gemini selects the minimum relevant files automatically, no manual hunting required - Persistent workspace — all generated ZIPs land in
.contextzip/at your project root, discoverable, reusable, and git-ignored automatically - Warns before it's a problem — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
- Handles edge cases — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
- Full CLI control —
--include,--exclude,--dry-run,--output, all composable
Requires Python 3.9+
pip install contextzipWith pipx (recommended for CLI tools — keeps it isolated):
pipx install contextzipVerify:
contextzip --versionNavigate to any project and run:
cd ~/projects/my-app
contextzipcontextzip will:
- Detect your framework (e.g.
Next.js + Node.js) - Apply the appropriate exclusion rules
- Create a compressed ZIP in
.contextzip/at your project root - Open your file manager with the ZIP selected and ready to copy
contextzip [OPTIONS]
| Option | Description |
|---|---|
-p, --prompt TEXT |
Describe your task in plain English — Gemini selects only the relevant files |
-i, --include PATH |
Only include files under this path (repeatable) |
-e, --exclude PATTERN |
Add exclusion patterns in gitignore syntax (repeatable) |
--git-changes |
Only include files reported by git as modified, staged, or untracked |
-n, --dry-run |
Preview what would be included without creating a ZIP |
-o, --output FILE |
Write ZIP to a custom path |
-v, --verbose |
Show every included and excluded file with sizes |
--no-clipboard |
Skip the clipboard / folder-open step |
--no-gitignore |
Ignore the project's .gitignore |
Subcommands: exclude, include, config — run contextzip --help for full details.
# Preview what would be packaged
contextzip --dry-run --verbose
# Package only specific directories
contextzip --include src --include app
# Exclude additional patterns
contextzip --exclude "*.log" --exclude "tests/"
# Package only git-modified files
contextzip --git-changes
# Let AI pick only the files relevant to your task
contextzip --prompt "Change toast color on failed login"
# Preview AI file selection without creating a ZIP
contextzip --prompt "Refactor auth middleware" --dry-run
# Save to a custom path
contextzip --output ~/Desktop/project-context.zipThe --prompt flag lets you describe a task in plain English. contextzip scans your project, builds a lightweight file map, and asks Gemini to return the minimum set of files needed for that task — typically 2–5, never more than 10. The result is a tightly scoped ZIP with only what you'd actually open to make the change.
contextzip --prompt "Change toast color on failed login"
# → components/ui/toast.tsx, app/login/page.tsx, lib/auth.tsThe ZIP also includes a prompt.txt describing the task, so when you drop it into Claude, ChatGPT, or any other AI tool, it immediately understands what you're trying to do.
First-time setup: --prompt requires a free Gemini API key from Google AI Studio — no credit card needed. On first use, contextzip guides you through obtaining and saving one. You can also skip the setup entirely with an environment variable:
export GEMINI_API_KEY=AIza...Manage your key at any time:
contextzip config # show current key status
contextzip config --reset-key # clear and re-run setupcontextzip stacks exclusion rules based on your detected stack, on top of your .gitignore.
Always excluded: .git/, .env files, logs, caches, editor config (.vscode/, .idea/), OS files (.DS_Store, Thumbs.db), and common binary formats.
By framework:
| Stack | Additional exclusions |
|---|---|
| Node.js / Next.js | node_modules/, .next/, dist/, build/, lock files, *.min.js, *.d.ts |
| Python / Django / FastAPI | __pycache__/, .venv/, *.pyc, migrations/, .pytest_cache/, lock files |
| Rust | target/, Cargo.lock, *.rlib |
| Go | vendor/, go.sum, bin/ |
Detection is additive — a monorepo with both package.json and pyproject.toml gets both rule sets applied.
Contributions are welcome — especially new framework rule sets, edge case fixes, and platform-specific clipboard improvements.
See CONTRIBUTING.md for local setup, how to add a new framework, and PR guidelines. Please open an issue before starting a large PR so we can align on the approach first.
MIT — see LICENSE for details.