Configuration.
Three layers, from most personal to most shared: your own machine, your project's committed defaults, and a visual editor for both when you'd rather not hand-write JSON.
Where .contextzip/ lives
By default, .contextzip/ is created at your git root — so running contextzip from a subdirectory of a monorepo (cd frontend && contextzip) still lands the workspace at the repo root instead of scattering folders across every subproject. Outside a git repo, it falls back to the current directory. This can be overridden at three levels, checked in this order:
| Priority | Method | Scope |
|---|---|---|
| 1 | CONTEXTZIP_WORKSPACE_LOCATION env var | One-off, single run |
| 2 | .contextzip/config.json → workspace_location | Team-shared, applies to everyone who clones the repo |
| 3 | contextzip config --set-workspace | Personal, per-machine default |
| — | Built-in default | "git-root" |
~/projects/my-app
$ contextzip config --set-workspace cwd
Personal default set — always use ./.contextzip wherever you run it
$ contextzip config --reset-workspace
Workspace override removed — back to the default resolution order
Personal config
Per-machine settings that never get committed — your Gemini API key, your personal workspace override, and whether you've already been offered (and declined) the visual config UI once.
Linux/macOS: ~/.config/contextzip/config.json (or $XDG_CONFIG_HOME). Windows: %APPDATA%\contextzip\config.json. The file may hold an API key in plaintext, so on every save its permissions are locked to owner-only (0600 on POSIX systems) — other accounts on a shared machine can't read it off disk.
| Command | Effect |
|---|---|
| contextzip config | Show current key status and workspace resolution |
| contextzip config --reset-key | Clear the stored key and re-run setup |
| contextzip config --show-key-path | Print the config file path and exit |
| contextzip config --set-workspace LOCATION | Set a personal workspace default ("git-root", "cwd", or a path) |
| contextzip config --reset-workspace | Clear the personal workspace override |
Project config
Committed to the repo at .contextzip/config.json, so every contributor gets the same defaults automatically — no per-machine setup required. .contextzip/ is git-ignored by default, but this one file is deliberately carved out of that rule so it stays trackable. All keys are optional.
{
"workspace_location": "git-root",
"scan_depth": 2,
"always_include": ["docs/architecture.md"],
"always_exclude": ["*.snap"],
"ai": {
"enabled": true,
"provider": "gemini",
"max_files": 10,
"prompt_template": "We use pytest, not unittest."
},
"limits": {
"max_file_size_mb": 1,
"redact_secrets": false
},
"applied_zip_retention": 1,
"webui": {
"auto_open": true,
"port": null
},
"cleanup": {
"enabled": true,
"keep_recent": 1
}
}| Key | Description |
|---|---|
| workspace_location | Same values as the personal setting — team-shared, wins over it |
| scan_depth | How many levels deep the monorepo ecosystem scan goes (default 2) |
| always_include | Standing negation — force-includes matching files even if an auto-rule or .gitignore would exclude them |
| always_exclude | Standing --exclude patterns applied on every run, gitignore syntax |
| ai.* | AI-selection preferences — see AI file selection |
| limits.max_file_size_mb | Files at or above this size are flagged as large before packaging (still included, just surfaced) |
| limits.redact_secrets | When true, secret-shaped values (API keys, tokens, private-key blocks) found inside otherwise-included text files are replaced with [REDACTED] before zipping — never touches binaries or oversized files |
| applied_zip_retention | How many past apply-zip archives to keep before pruning the oldest (default 1) |
| webui.auto_open | Whether contextzip config --ui opens a browser tab automatically |
| webui.port | Bind the config UI to a fixed port instead of a random free one — useful behind strict local firewall rules |
| cleanup.enabled | If true (default), .contextzip/ is pruned automatically after every successful command — no prompt, nothing to remember |
| cleanup.keep_recent | How many most-recent items are kept per category before the rest are deleted — zip/manifest/report sets per output mode, backups, and archived applied-zips (default 1) |
Brutal by design: cleanup runs automatically, with no confirmation prompt and no separate command — every zip is trivially reproducible by re-running contextzip, so there's little reason to let old ones pile up. Set cleanup.enabled to false to keep everything contextzip has ever generated. Currently hand-edit-only in config.json — not yet exposed in the visual config UI.
Deprecation: a legacy .contextzip.json at the project root is still read as a fallback when .contextzip/config.json doesn't exist, so older projects keep working. contextzip prints a one-time notice suggesting the move.
Visual config UI
contextzip config --ui opens a local browser tab with a live file tree — check or uncheck any file or folder and watch the included/excluded counts and total size update instantly, with one-click suggestions for things like PDFs, design files, or other non-code assets that slipped past the automatic rules. Saving writes straight to .contextzip/config.json. On a brand-new project with no config yet, contextzip offers to open it for you the first time you run the tool interactively.
~/projects/my-app
$ contextzip config --ui
contextzip config UI is running locally
→ http://127.0.0.1:53214/?token=x7f2…
Bound to 127.0.0.1 only — nothing about this project leaves your machine.
Press Ctrl+C here at any time to stop.
- · Binds to 127.0.0.1 only, never 0.0.0.0 — nothing about your project reaches the network.
- · Zero outbound calls of its own — no telemetry, no phone-home. The only network activity is your browser talking to this same-machine server.
- · Every request needs a random, single-use session token (the same approach Jupyter Notebook uses), so another local process or browser tab can't read or reconfigure your project by guessing a port.
- · Shuts itself down on a successful save, after 15 minutes of tab inactivity, or after a 60-minute hard ceiling — so a forgotten run doesn't linger as an open port.
- · The file tree is scanned from disk once at startup; every checkbox toggle re-classifies that same in-memory list, which is what keeps the live preview feeling instant even on larger projects.
Everything editable from the CLI or by hand — always_include, always_exclude, workspace location, scan depth, AI settings, size limits, secret redaction, applied-zip retention, and the UI's own auto-open/port preferences — is editable visually here too, seeded from whatever's already in config.json so re-opening the UI shows what's actually in effect, not a blank slate.