Getting started
contextzip turns “find the right files, skip node_modules, zip it, find the zip, upload it” into one command. Here's how to go from install to pasted in about a minute.
Install
contextzip needs Python 3.9 or newer and works on Windows, macOS and Linux. Installing with pipx or uv keeps it isolated from your projects.
You get two commands that do exactly the same thing: contextzip and the shorter cz.
Your first run
From your project root, run it with no flags:
~/projects/my-app
$ contextzip
✓ Detected Next.js + Node.js · high confidence
✓ Scanned 36,220 files & Packed 44 files · 44 included (186 KB), 36,176 excluded, 186 KB → 63 KB, ↓66% smaller
✓ Saved to · .contextzip/output/codebase/codebase.zip · snapshot #1 (k3f9a2)
Full report: .contextzip/output/codebase/codebase.report.txt
✓ Ready to paste
That's real output from running contextzip on this website's own repository: 36,220 files on disk, 44 that actually matter. contextzip detected the stack, left out dependencies, build output, lockfiles, binaries and secrets, and wrote a report next to the ZIP listing exactly what went in and what didn't.
On the very first run in a project, contextzip may offer to open the visual config UI so you can fine-tune what's included. It only asks once, and never in scripts or CI.
Preview before you package
Add--dry-run --verbose to see every included and excluded file without writing anything.Paste it anywhere
When it finishes, the ZIP is on your clipboard as a real file — the same as copying it in your file manager. Click into Claude, ChatGPT, Gemini or any upload box and paste.
| Platform | How the file reaches your clipboard |
|---|---|
| Windows | Set natively (CF_HDROP) and read back to confirm, with PowerShell as a second attempt. |
| macOS | Through Finder, exactly like pressing ⌘C on the file. |
| Linux | A built-in X11 clipboard owner — nothing to install, works under XWayland — or wl-copy / xclip if present. |
If the clipboard can't be used (an SSH session, say), contextzip opens the folder with the ZIP selected and tells you why. Use --no-clipboard to skip this step, or -o path.zip to write the ZIP somewhere specific.
Everyday commands
Staying up to date
contextzip update checks PyPI and upgrades in place. It works out whether you installed with pip, pipx or uv and upgrades the same interpreter that's running — never a different pip that happens to be first on your PATH.
~/projects/my-app
$ contextzip update --check
Update available: 0.4.5 → 0.4.6
Run contextzip update to install it.