Configuration
Nothing needs configuring to get started. When you do want control, there are two optional files: one for the project, one for you.
Project config
Per-project settings live in .contextzip/config.json at your git root. Edit it by hand, or let contextzip config --ui write it for you. Every key is optional — hover one to see what it does:
{"always_include": ["docs/architecture.md"],"always_exclude": ["*.snap", "fixtures/"],"workspace_location": "git-root","scan_depth": 2,"ai": {"enabled": true,"max_files": 10,"prompt_template": "We use pytest, not unittest."},"limits": {"max_file_size_mb": 1,"redact_secrets": false},"applied_zip_retention": 1,"cleanup": { "enabled": true, "keep_recent": 1 },"snapshots": { "keep": 10, "max_age_days": 14 },"zip_guide": true,"webui": { "auto_open": true, "port": null }}
Hover or tab through a key
always_include
Patterns that are always included, even if a built-in rule or .gitignore would leave them out. Secret files brought back this way (like .env) have their values redacted.
default []
Every key is optional. Edit by hand or with contextzip config --ui.
Sharing it with your team
.contextzip/ is fully gitignored by default — contextzip never assumes what belongs in your repo. To share these settings, commit the file explicitly: git add -f .contextzip/config.json.A legacy .contextzip.json at the project root is still read when the new file doesn't exist, with a notice suggesting the move.
Personal config
Your Gemini key and personal defaults live outside every project, so they're never committed. The file is restricted to your user (0600) on every save.
| OS | Location |
|---|---|
| Linux / macOS | ~/.config/contextzip/config.json |
| (custom) | $XDG_CONFIG_HOME/contextzip/config.json |
| Windows | %APPDATA%\contextzip\config.json |
| Command | What it does |
|---|---|
| contextzip config | Show the current setup: key status, workspace location |
| contextzip config --reset-key | Clear the stored Gemini key and run setup again |
| contextzip config --show-key-path | Print where this file lives |
| contextzip config --set-workspace LOC | Your default for where .contextzip/ lives |
| contextzip config --reset-workspace | Clear that default |
| contextzip config --ui | Open the visual config UI |
Workspace location
.contextzip/ lives at the project root: the outermost git repository above you, or — outside git — the folder that already has a workspace. Running contextzip from a monorepo subfolder never scatters a second one. contextzip config shows which root was picked and why, and CONTEXTZIP_ROOT pins it. For a monorepo with no git at the top, contextzip asks once whether to use the shared parent folder and remembers the answer. Where inside the project the workspace goes can be overridden — the first match wins:
| # | Where | Scope |
|---|---|---|
| 1 | CONTEXTZIP_WORKSPACE_LOCATION=cwd | One run (environment variable) |
| 2 | "workspace_location" in .contextzip/config.json | The project |
| 3 | contextzip config --set-workspace cwd | You, on this machine |
| — | Built-in default | git-root |
Accepted values: git-root, cwd, or a path such as ~/zips.
Visual config UI
contextzip config --ui opens a local browser tab with your project's file tree. Tick or untick any file or folder and watch the included count and total size update instantly, with one-click suggestions for things like PDFs and large files. The Advanced tab also covers size limits, secret redaction and whether every ZIP carries a CONTEXTZIP.md. Saving writes .contextzip/config.json.
~/projects/my-app
$ contextzip config --ui
✓ Config UI running · http://127.0.0.1:53214/?token=…
Bound to 127.0.0.1 only · Ctrl+C to stop
- Binds to 127.0.0.1 only and makes no outbound requests of its own.
- Every request needs a random session token, so another local process can't reconfigure your project by guessing the port.
- Shuts itself down after you save, after 15 minutes without activity, or after an hour regardless.
webui.portpins a fixed port;webui.auto_open: falseprints the URL instead of opening a tab.
Automatic cleanup
After every successful command, .contextzip/ is pruned to the most recent item in each category — ZIP, manifest and report sets per mode, applied ZIPs, and apply reports. No prompt, nothing to remember: any ZIP can be rebuilt by running contextzip again.
Change it with cleanup.keep_recent, or turn it off with cleanup.enabled: false. These are hand-edit only for now — not in the config UI yet.
Snapshots in .contextzip/snapshots/ follow their own rule: each is kept while it's among the newest snapshots.keep (10), younger than snapshots.max_age_days (14), or still awaited by a reply in the inbox.