contextzip/README.md

contextzip

Package exactly the right parts of your codebase and paste it into any AI tool — in one command.

pip install contextzip

---

Why contextzip

Every 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.

---

Features

• 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-changes to 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 --prompt and 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

---

Installation

Requires Python 3.9+

pip install contextzip

With pipx (recommended for CLI tools — keeps it isolated):

pipx install contextzip

Verify:

contextzip --version

---

Quick start

Navigate to any project and run:

cd ~/projects/my-app
contextzip

contextzip will:

1. Detect your framework (e.g. Next.js + Node.js)
2. Apply the appropriate exclusion rules
3. Create a compressed ZIP in .contextzip/ at your project root
4. Open your file manager with the ZIP selected and ready to copy

---

Usage

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.

---

Examples

# 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.zip

---

AI-powered file selection

The --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.ts

The 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 setup

---

What gets excluded

contextzip 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.

---

Contributing

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.

---

License

MIT — see LICENSE for details.