contextzip

Send your codebase to any AI chat. Get the changes back.

One command zips the right files for Claude or ChatGPT. Another writes the AI's reply into your project, without losing your own edits.

Try it in your browser  ·  Docs  ·  CLI reference  ·  Changelog

pip install contextzip      # or: npm i -g @contextzip/cli  ·  brew install akadeepesh/tap/contextzip
cz                          # zip the right files and put the ZIP on your clipboard
cz apply                # write the AI's reply back into your project

Why

Every AI coding session in a web chat starts the same way: hunt down the relevant files, leave out node_modules by hand, zip, upload. Then the slow part: copy the AI's edits back file by file, into the right folders, and hope you didn't overwrite something you changed in the meantime.

contextzip does both directions.

Related MCP server: viberevert

How it compares

Other tools turn a repository into one text file for an AI to read. contextzip sends the real files, and its main job is the way back.

If you only want an AI to read a repository, any of them works, and a single text file pastes into more places than a ZIP does. repomix can also compress code down to its signatures, which contextzip doesn't do yet. If you want the AI's edits back in your code, that is what contextzip is for.

The other columns come from each project's own documentation as of October 2026. Corrections are welcome.

Installation

pip install contextzip                    # Python 3.9+   (also: pipx install, uv tool install)
npm install -g @contextzip/cli            # no Python needed, any OS
brew install akadeepesh/tap/contextzip    # macOS, Linux

Every method installs two commands that do the same thing: contextzip and the shorter cz. To update later, run contextzip update.

Tab completion: cz completions --install sets it up for your shell (bash, zsh, fish or PowerShell), for both names. Open a new terminal and cz ap<Tab> completes to cz apply. cz doctor checks the install if something doesn't work.

# Windows (Scoop)
scoop bucket add contextzip https://github.com/akadeepesh/scoop-bucket
scoop install contextzip

# Try it once, nothing stays installed
npx @contextzip/cli
uvx contextzip
pipx run contextzip

• Direct download: grab an archive from the latest release, unpack it, and put the contextzip folder on your PATH. Builds exist for Windows x64, macOS (Apple Silicon and Intel) and Linux x64/arm64 (glibc 2.35 or newer).

• VS Code: install contextzip from the Marketplace, or run code --install-extension contextzip.contextzip. It bundles the CLI.

• AI agents: pip install "contextzip[mcp]" and register contextzip mcp as an MCP server (Python 3.10+).

• No install: contextzipcli.com.

pip installed contextzip, but put the cz command in a folder your terminal doesn't search. This is common with Python from the Microsoft Store on Windows, and with pip install --user on macOS and Linux. Python itself always works, so let contextzip fix PATH for you:

python -m contextzip setup-path     # macOS / Linux: python3 -m contextzip setup-path

On Windows this adds the folder to your user PATH (no admin needed). On macOS and Linux it adds one line to your shell's startup file. Open a new terminal and cz works. Until then, python -m contextzip does everything cz does. If you installed with pipx, run pipx ensurepath; with uv, uv tool update-shell.

Quick start

cd ~/projects/my-app
cz

No flags needed. contextzip detects your framework, leaves out the noise, writes codebase.zip and copies it to your clipboard:

contextzip · my-app   Next.js + FastAPI (backend/)

  44 files   186 KB → 63 KB zip   46,210 tokens

  src/app/           18,200  ████████████░░░░░░░░  39%
  src/components/    12,100  ████████░░░░░░░░░░░░  26%
  backend/api/        9,800  ██████░░░░░░░░░░░░░░  21%
  3 more folders      6,110  ████░░░░░░░░░░░░░░░░  14%

  Fits      Claude ≈23%  ·  ChatGPT 36%  ·  Gemini ≈5%
  Left out  36,176 files: node_modules/ (35,120), .next/ (904), 3 secret files

✓ On your clipboard. Paste it into Claude or ChatGPT.   snapshot #14
  When the AI replies, run: cz apply

Piped or in CI, and with --plain, the same run prints one plain line per step instead. Paste the ZIP into your AI tool, ask for what you want, and when it sends files back:

cz apply

The commands you'll use most:

cz --dry-run --verbose              # preview every included and excluded file, write nothing
cz --git-changes                    # only what you've changed
cz pick                             # choose files in a tree, then Enter packages them
cz include src/ app/                # only these folders
cz exclude tests/ '*.snap'          # everything except these
cz include src/ .env                # .env too, with its values redacted
cz --prompt "fix the login redirect bug"    # let AI pick the relevant files
cz github.com/user/repo             # a GitHub, GitLab or Bitbucket repo, without cloning it
cz --here                           # only the folder you're in (monorepos)
cz stacks                           # the languages and frameworks it recognises

Applying AI changes back

cz apply              # picks up a ZIP from .contextzip/inbox/
cz apply fix.zip      # or point at one directly
cz apply --dry-run    # preview without writing anything

AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. apply matches each file to its real place in your project anyway.

Every ZIP contextzip makes is kept as a local snapshot (never uploaded). When a reply comes back, three versions of each file are compared: what you sent, what's on disk now, and what came back.

When something needs a decision you choose: apply the safe changes now, review side by side in your browser (--review), resolve in VS Code's merge editor (--editor), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and files are only removed with your explicit OK.

Each ZIP also carries a short CONTEXTZIP.md telling the AI how to reply so the answer applies cleanly: complete files, same paths, moves and deletions listed.

Secrets

Secret files are excluded from every project, whatever its stack: .env and .env.*, *.pem, *.key, keystores, SSH private keys, .npmrc, .netrc, cloud credential files, kubeconfigs and Terraform state.

When the AI needs to see which settings exist, include the file on purpose. Keys and comments are kept; values are not:

# .env on disk                          # .env in the ZIP
DATABASE_URL=postgres://u:pw@db/app     DATABASE_URL=[REDACTED]
export API_KEY="sk-live-…"  # prod      export API_KEY="[REDACTED]"  # prod

Spring Boot's application.properties and application.yml are always redacted the same way, because they are config the AI needs and routinely hold live passwords:

# application.properties on disk                       # in the ZIP
spring.datasource.url=jdbc:postgresql://app:pw@db/app   spring.datasource.url=jdbc:postgresql://app:[REDACTED]@db/app
spring.datasource.password=hunter2                      spring.datasource.password=[REDACTED]
jwt.secret=${JWT_SECRET:dev-secret}                     jwt.secret=${JWT_SECRET:[REDACTED]}

When the file comes back, apply keeps your real values. Set limits.redact_secrets: true to also mask API keys, tokens and private-key blocks hardcoded in ordinary files. Before sharing a sensitive project, cz --dry-run --verbose shows exactly what will go in.

Stacks

contextzip recognises a stack from marker files (package.json, pyproject.toml, pom.xml, *.csproj, composer.json, pubspec.yaml, Cargo.toml, go.mod) and the dependencies they list. It looks a couple of levels deep and reads workspace files, so a monorepo with a React frontend and a Spring Boot backend gets both rule sets. A folder of scripts with no project file is recognised by its file types.

cz stacks lists all 62, and cz stacks laravel shows everything one leaves out. Missing yours? Request it, or add it: one table entry and one test case.

More ways to use it

In your browser

contextzipcli.com runs the same code as the CLI, in the page.

• Drop a folder and it's packaged locally. Your files never leave your machine.

• Paste a repo link to package a public repository. Shortcut: put contextzipcli.com/ in front of a repo URL, as in contextzipcli.com/github.com/user/repo.

• Apply the AI's reply to your folder (Chrome and Edge): pick the folder and the ZIP, review the plan, and the safe changes are written for you.

A repository, without cloning it

cz github.com/pallets/click
cz https://github.com/pallets/click/tree/main/src     # one branch, one folder
cz gh:you/private-repo --ref dev
cz gitlab.com/group/project                           # or gl:group/project
cz bitbucket.org/team/repo                            # or bb:team/repo

contextzip downloads one commit through the host's API and packages it like any other project. Private repos use GITHUB_TOKEN (or your gh login), GITLAB_TOKEN or BITBUCKET_TOKEN; a token is only ever sent to its own host. For a GitHub repo, cz apply reply.zip --pr commits the AI's changes and opens a pull request, forking first if you can't push.

VS Code extension

contextzip for VS Code bundles the CLI, so it works without Python. Package the project, a selection, your git changes or a GitHub repo from the Explorer's right-click menu. When an AI's ZIP lands in your Downloads, the extension offers to apply it: every file's status shows in the AI Changes view, safe changes apply in one step, and conflicts open in the three-way merge editor.

MCP server for AI agents

pip install "contextzip[mcp]"      # Python 3.10+

{"mcpServers": {"contextzip": {"command": "contextzip", "args": ["mcp"]}}}

An agent can then package a project or a repository, preview and apply a reply, list snapshots and open a pull request. See CLI.md for every tool.

Let AI pick the files

cz --prompt "add rate limiting to the login endpoint"

Describe the task and Gemini picks only the files that matter; the ZIP also gets a prompt.txt describing the task. It needs a free Gemini API key, which contextzip walks you through the first time. Only file paths and sizes plus your prompt are sent, never file contents. If Gemini is rate-limited, a local keyword-based selector takes over.

Choose files by hand

cz pick

contextzip pick · my-app                    44 of 312 files · 186 KB · 46,210 tokens
Fits  Claude ≈23% · ChatGPT 36% · Gemini ≈5%
──────────────────────────────────────────────────────────────────────────────────────
 ▾  [x] src/                                  38 files                    41,300
    ▸  [x] app/                               12 files                    18,200
    ▸  [-] components/                        9 of 14 files               12,100
       [x] main.tsx                                                          420
 ▸  [ ] docs/                                 left out
    [ ] big-export.json                       large                       2.1 MB

A full-screen tree in the terminal: tick files and folders with the space bar (or the mouse), filter with /, and watch the token total and the model fit change as you go. Enter packages exactly what's ticked; w saves it as the project's default. Ticking a folder never drags in what the rules or .gitignore leave out (node_modules/, .env); tick such a file directly to bring it in, and secret files are still redacted. cz include and cz exclude with nothing after them open it too.

Or set include/exclude in a browser tab:

cz config --ui

A local browser tab where you tick what goes in the ZIP. It shows how big each folder is, points out what is probably not code, and saves your choices to .contextzip/config.json. The server binds to 127.0.0.1 only, needs a one-time session token and shuts itself down when you're done.

Package the moment something breaks

cz watch -- npm run dev

contextzip runs your command and watches its output. When a stack trace appears (Python, Node.js and Java/Kotlin errors are recognised), press D to get a ZIP with the error, a ready-made prompt and the source files named in the trace.

Command reference

Every command supports -h. For every flag of every subcommand, see CLI.md or the online reference.

Configuration

Both config files are optional. Per-project settings live in .contextzip/config.json; edit it by hand or with cz config --ui.

{
  "always_include": ["docs/architecture.md"],  // force-include, even if a rule or .gitignore excludes it
  "always_exclude": ["*.snap", "fixtures/"],   // a standing --exclude on every run
  "workspace_location": "git-root",            // "git-root" | "cwd" | "/some/path"
  "ai": {
    "enabled": true,
    "max_files": 10,                           // cap on files the AI may select
    "prompt_template": "We use pytest, not unittest."  // prepended to every prompt.txt
  },
  "limits": {
    "max_file_size_mb": 1,                     // threshold for "large file" warnings
    "redact_secrets": false                    // also mask secret-looking values in ordinary files
  },
  "snapshots": { "keep": 10, "max_age_days": 14 },  // history apply merges against
  "zip_guide": true,                           // add CONTEXTZIP.md to every ZIP
  "tokens": {
    "max": 150000,                             // a token budget for every run, like --max-tokens
    "windows": { "claude": 500000 },           // your own context window per --for name
    "show_fit": true                           // print the "Fits" line
  }
}

.contextzip/ is git-ignored by default. To share these settings with your team, commit the file explicitly: git add -f .contextzip/config.json. Your Gemini API key and personal defaults live outside the project (~/.config/contextzip/ or %APPDATA%\contextzip\), so they're never committed. The full guide is at contextzipcli.com/docs/configuration.

Which rule wins

When they disagree, the more specific source wins:

1. The command you typed. exclude / --exclude always leaves a file out. include / --include scopes the run, and a file or folder you name is included even if it's a .env, is in .gitignore, or is excluded by the config.

2. The project config: always_include, then always_exclude.

3. Your .gitignore. A !pattern there brings back a file the built-in rules would drop, such as !.env.example.

4. The built-in rules for the detected stack.

Including a folder is a scope, not an override: cz include src/ still leaves out src/.env and whatever .gitignore ignores inside src/. Name the file itself to bring it in. A secret file that ends up in the ZIP, by any of these routes, has its values redacted.

These apply to every project, whatever its stack, and in --git-changes mode too:

• Secrets & credentials: .env, .env.*, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, *.ppk, SSH private keys (id_rsa, id_ed25519, …), .npmrc, .netrc, .pypirc, .pgpass, Docker auth config, .aws/credentials, service-account and *credentials*.json files, kubeconfigs

• Infrastructure state: *.tfstate, .terraform/

• Version control & editors: .git/, .svn/, .hg/, .vscode/, .idea/, swap files, .DS_Store

• Logs, caches & temp files: *.log, logs/, .cache/, tmp/, *.tmp, *.bak

• Binaries & media: executables, shared libraries, images, video, audio, fonts and archives

• Project boilerplate: CHANGELOG, LICENSE, CONTRIBUTING, SECURITY.md, CODE_OF_CONDUCT.md, GitHub issue/PR templates

To bring one back, name it with cz include .env, list it under always_include, tick it in cz config --ui, or un-ignore it in .gitignore (!.env.example).

contextzip keeps everything in a .contextzip/ folder at your git root (change this with cz config --set-workspace):

.contextzip/
├── output/
│   ├── codebase/      codebase.zip + manifest + report   (cz)
│   ├── git-changes/   changes.zip + manifest + report    (--git-changes)
│   ├── prompt/        vibe.zip + manifest + report       (--prompt)
│   └── watch/         debug-context.zip                  (cz watch)
├── snapshots/         numbered copies of what you sent   (cz snapshots)
├── inbox/             drop AI-returned ZIPs here for apply
└── config.json        project config (optional)

Old outputs are cleaned up automatically: output/ keeps the latest ZIP per mode, and snapshots/ keeps the newest 10 or anything under 14 days old, never one a reply in the inbox is waiting on.

Python API

contextzip is also a library. The functions behave like the CLI but return plain Python objects and raise exceptions instead of printing.

from contextzip import get_files, get_git_changes, create_zip, apply_zip, fetch_remote

collection = get_files(include=["src/"], exclude=["*.log"])   # filtered like the CLI
pkg = create_zip(get_git_changes(), output="/tmp/changes.zip")
print(f"Packed {pkg.file_count} files → {pkg.zip_path}")

repo = fetch_remote("github.com/pallets/click")               # a repository, without cloning it
pkg = create_zip(get_files(repo.project_dir), output=repo.zip_path)

All exceptions inherit from ContextzipError. Full signatures are in the API reference.

Privacy & security

• Local by default. Packaging, apply, watch and the config UI never make network requests.

• Network use is opt-in and limited to three features: --prompt sends file paths, sizes and your prompt to the Gemini API, never file contents. Packaging a remote repo downloads it from that host, and apply --pr opens a pull request on GitHub. cz update asks PyPI for the latest version number.

• No telemetry. Nothing is collected or phoned home.

• Secrets are excluded or redacted. See Secrets.

Found a vulnerability? Please follow SECURITY.md and report it privately.

Platform support

If the clipboard can't be used, contextzip opens the output folder with the ZIP selected and tells you why.

Contributing

Contributions are welcome, especially new languages and frameworks: one entry in contextzip/stacks.py, a PATTERNS list and one test case. CONTRIBUTING.md walks through it. Not up for writing code? Request a feature or request your language; both become GitHub issues ranked by 👍.

git clone https://github.com/akadeepesh/contextzip
cd contextzip
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e . pytest
python -m pytest

If contextzip saves you time, a ⭐ helps other people find it.

License

MIT © Deepesh