Packaging & detection.
What contextzip includes and excludes by default, how it figures out your stack, and the guardrails that keep a ZIP from ever containing something it shouldn't.
Smart framework detection
contextzip identifies your stack by looking for marker files — package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile — and applies the matching exclusion rules automatically. Detection isn't limited to the project root: a shallow, bounded scan (two levels deep by default, skipping node_modules/, .venv/, .git/, and other directories it would never need to look inside) checks subdirectories too, so a monorepo like frontend/ + backend/ gets every ecosystem it contains detected correctly. Detection is additive — a repo with both package.json and pyproject.toml gets both rule sets applied at once.
~/projects/my-app
$ contextzip
Detected: Next.js (frontend/) + FastAPI (backend/)
Neither marker file sits at the top level — found via subdirectory scan
| Stack | Additional exclusions |
|---|---|
| Node.js / Next.js | node_modules/, .next/, .nuxt/, dist/, build/, out/, .turbo/, .vercel/, coverage/, lock files, *.min.js, *.d.ts |
| Python / Django / FastAPI | __pycache__/, .venv/, *.pyc, .pytest_cache/, .mypy_cache/, migrations/, staticfiles/, media/, lock files |
| Rust | target/, Cargo.lock, *.rlib |
| Go | vendor/, go.sum, bin/, *.test |
| Ruby / Rails | vendor/bundle/, .bundle/, Gemfile.lock, pkg/, public/assets/, storage/, coverage/, *.gem |
The scan depth (default 2 levels) is configurable per project — see project configuration.
What gets excluded, always
On top of framework-specific rules, a universal baseline applies to every project regardless of stack — version control internals, editor and OS clutter, logs and caches, and anything that looks like a credential. This baseline can't be re-included; it's the one layer that isn't negotiable.
| Category | Examples |
|---|---|
| Version control & editors | .git/, .svn/, .hg/, .vscode/, .idea/, *.swp |
| OS artifacts | .DS_Store, Thumbs.db, desktop.ini |
| Logs, caches & temp | *.log, logs/, .cache/, tmp/, *.tmp, *.bak, *.orig |
| Env files | .env, .env.* |
| Common binaries & media | *.exe, *.dll, *.so, *.png, *.jpg, *.gif, *.svg, *.mp4, *.zip, *.tar, *.gz |
| Repo boilerplate | CHANGELOG.md, CONTRIBUTING.md, LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, .github/ISSUE_TEMPLATE/ |
| contextzip itself | .contextzip/ — its own working folder |
Secrets & credentials — excluded regardless of framework
A stray credential file lying around a project should never end up in an archive that gets pasted into an AI tool. These patterns apply on top of everything above and can't be re-included with --include.
| Category | Examples |
|---|---|
| SSH private keys | id_rsa, id_dsa, id_ecdsa, id_ed25519 (the .pub counterparts are kept) |
| Keystores & certs | *.p12, *.pfx, *.pkcs12, *.jks, *.keystore, *.ppk, *.key |
| CLI / package manager creds | .npmrc, .netrc, .pypirc, .pgpass, .dockercfg, docker config.json |
| Cloud provider credentials | .aws/credentials, .aws/config, *serviceaccount*.json, *credentials*.json, kubeconfig |
| Infra-as-code state | *.tfstate, *.tfstate.*, .terraform/ — Terraform state routinely holds plaintext secrets |
Want contextzip to go further and scrub secret-shaped values inside otherwise-included files? See redact_secrets in the project config.
Respects .gitignore
Your existing ignore patterns are honoured automatically — contextzip layers its own exclusion rules on top rather than replacing yours.
Need to see exactly what got excluded and why? Add --verbose to any run, or turn the rules off entirely with --no-gitignore.
Git-aware packaging
--git-changes packages only what git reports as modified, staged, or untracked — built for incremental debugging sessions and PR review, where the full project is noise and the diff is the point. Requires the project to be inside a git repository.
~/projects/my-app
$ contextzip --git-changes
6 modified · 2 staged · 1 untracked
Wrote .contextzip/output/codebase.zip — 9 files, 118 KB
Available as a library too — see the Python API reference.
Warnings & edge cases
contextzip flags large and binary files before you waste an upload on something an AI tool can't read — the threshold defaults to 1 MB and is adjustable per project. Dangling symlinks, unreadable files, and paths outside the project tree are caught and reported — never silently dropped, so the archive always matches what you expect it to contain.
~/projects/my-app
$ contextzip --dry-run --verbose
assets/hero.png — 2.3 MB — excluded, binary + size warning
config/local.json — symlink target missing — reported, skipped
Want the AI to pick the files for you?
See how --prompt scopes a ZIP down to just the 2–5 files a task actually touches.