akadeepesh
88ce0f9754
Adds Terminal error watcher section covering the full flow, ZIP contents table, Ctrl+C fallback, supported frameworks, and PTY/Windows note. Updates features list and subcommands reference.
8.1 KiB
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-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 - Terminal error watcher — wrap any dev server with
contextzip watchto auto-detect errors and package a ready-to-upload debug context in one keypress - 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:
- 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
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, watch, 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
Terminal error watcher
The watch command wraps your dev server, buffers its output, and packages a debug-ready ZIP the moment you spot an error — no manual file hunting, no copy-pasting stack traces.
contextzip watch -- npm run dev
contextzip watch -- python manage.py runserver
contextzip starts your process normally. You see output exactly as you would without it. In the background, it watches the stream for errors. When one is detected, a prompt appears directly beneath the error output:
╭─ contextzip · error detected ─────────────────────╮
│ Press [D] to package debug context [S] to skip │
╰───────────────────────────────────────────────────╯
Press D and contextzip immediately writes .contextzip/debug-context.zip. Your server keeps running — no restart, no interruption.
What's in the ZIP:
| File | Contents |
|---|---|
prompt.txt |
Auto-generated: detected framework, error type, and task description — ready to paste into any AI tool |
terminal-error.txt |
The cleaned, noise-stripped error block and stack trace |
source-files.zip |
Source files referenced in the stack trace, paths preserved |
On Ctrl+C: If no errors were packaged during the session, contextzip offers one final prompt to capture the full session output — useful when something looked wrong but didn't match a known error pattern.
Supported frameworks: Python, Django, FastAPI, Node.js, Next.js, React. Each has its own error detection patterns and noise filters so the output stays clean across stacks.
Note:
watchworks best with dev servers that don't read stdin interactively (npm run dev,manage.py runserver, etc.). PTY emulation is not used — on Windows, color passthrough may be limited.
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.