Apply changes back
contextzip packages your project out to an AI. apply-zip brings the answer back in — whatever shape the ZIP comes back in, and without overwriting work you've done since.
How it works
Drop the AI's ZIP in .contextzip/inbox/ (or pass its path) and run contextzip apply-zip — from any folder of the project. Nothing is written until every file has been matched and compared.
~/projects/my-app
$ contextzip apply-zip
✓ Resolved · .contextzip/inbox/fix.zip
✓ Compared with snapshot #14 (k3f9a2) · named in the reply's CONTEXTZIP.md
Paths in the zip were remapped: my-app-fixed/… → …
✓ Classified 6 files · 1 modified, 1 merged, 1 new, 1 unchanged
! 1 conflict, 1 partial — needs your call
What now?
S apply the 3 safe changes, leave them for later
R review them in your browser, side by side
E resolve them in VS Code
A apply everything — the AI's version wins
Q quit without writing
Where each file goes
AI tools return ZIPs in every shape. The same change can come back exactly as sent, wrapped in an extra folder, relative to a subfolder (src/… for frontend/src/…), flattened to bare file names, or with Windows separators. contextzip matches each file to your project by the longest stretch of its path that agrees, and applies the layout it learns to brand-new files too — so src/lib/rate-limit.ts lands next to its siblings in frontend/src/lib/.
A name that fits several files (three different page.tsx) is settled by comparing contents. If it's still unclear, the file is marked ambiguous and you choose where it goes — it's never written on a guess. __MACOSX/, .DS_Store and an echoed prompt.txt are ignored.
How files are classified
Every ZIP contextzip makes is kept as a numbered snapshot — a copy of exactly what you sent, never uploaded. apply-zip uses the snapshot the reply names in its CONTEXTZIP.md, or else the one that best matches the reply's contents, then compares three versions of each file: what you sent, what's on disk now, and what came back. Select one:
contextzip apply-zipPaths in the zip were remapped: my-app-fixed/… → …
✓ Classified 6 files · 1 modified, 1 merged, 1 new, 1 unchanged
! 1 conflict, 1 partial — needs your call
api/main.py
Conflict
You and the AI changed the same lines, differently.
Files are only ever removed with your explicit OK. A file missing from the returned ZIP is left alone.
| Status | Meaning | By default |
|---|---|---|
| new | The file doesn't exist yet | written |
| modified | Only the AI changed it | written |
| merged | You both changed it, in different places — three-way merged | written |
| unchanged | Already matches, including fixes you already applied | skipped |
| conflict | You both changed the same lines | your call |
| partial | The AI returned a cut-down file (// ... rest unchanged) | your call |
| drifted | You changed it and it can't be merged (binary, or the ZIP you sent is gone) | your call |
| deleted | You deleted it after zipping | your call |
| untracked | Exists here but wasn't in the ZIP you sent | your call |
| ambiguous | Can't tell which file it belongs to | your call |
| moved | The AI moved or renamed it — declared in CONTEXTZIP.md, or near-identical content | new path written, old file kept |
| delete-requested | The AI asked to delete it in CONTEXTZIP.md | needs its own yes |
Line endings never count
A file the AI returned with LF endings where yours uses CRLF is unchanged, not modified. Everything apply-zip writes keeps your file's line endings and BOM, so a one-line fix is a one-line diff in git.Deciding on the rest
When something needs your call, choose how to look at it:
In your browser
contextzip apply-zip --review
A local page with every file side by side, word-level highlights, and conflicts you can resolve by editing the merged text right there.
In your editor
contextzip apply-zip --editor
Conflicts open in VS Code's three-way merge editor — yours, the AI's and the original. Also Cursor, Windsurf and VSCodium, or set CONTEXTZIP_EDITOR.
Safe changes only
contextzip apply-zip --safe-only
Apply new, modified and merged files; leave the rest. The ZIP stays in the inbox until everything's settled.
Everything
contextzip apply-zip --yes
Apply it all without asking. Where you and the AI disagree, the AI's version wins.
In CI or any run without a terminal to ask, apply-zip writes nothing when a decision is needed — pass --safe-only or --yes to say what you want.
Snapshots & CONTEXTZIP.md
Every package is kept locally as a numbered snapshot: a copy of exactly what you sent. So a reply can be merged against the right original even after you've packaged again — and every ZIP carries a short CONTEXTZIP.md naming its snapshot and telling the AI how to reply: complete files, the same paths, secrets left as [REDACTED], and moves or deletions listed.
~/projects/my-app
$ contextzip snapshots
✓ 3 snapshots · kept while among the newest 10 or younger than 14 days
#14 k3f9a2 codebase 44 files 2 minutes ago pending
#13 p8x2mq changes 6 files 3 hours ago applied
#12 z4c7tw prompt 4 files 1 day ago applied
When the reply echoes CONTEXTZIP.md, apply-zip uses that exact snapshot. If it doesn't, the snapshot that best matches the reply's contents is used. Pin one with --snapshot 14, or turn the file off with "zip_guide": false.
Safety rules
Files are only removed with your OK
A moved file's old copy, or a file the AI asked to delete, is removed only when you say yes — never by--yes alone, and never if you've changed it since the snapshot. A file missing from the reply is left alone.- Secret files that were redacted on the way out are merged against the redacted copy, so your real values stay and a
[REDACTED]placeholder is never written over them. - A ZIP entry that points outside the project (an absolute path, a drive letter,
..) refuses the whole ZIP. - Nothing is ever written into
.git/or.contextzip/. - The applied ZIP is archived to
.contextzip/inbox/applied/rather than deleted. If anything was left undecided, it stays in the inbox so you can run apply-zip again.
Options
| Option | What it does |
|---|---|
| [ZIP] | Path to the returned ZIP. Optional — without it, contextzip looks in .contextzip/inbox/ |
| --snapshot ID | The snapshot this reply answers (usually found automatically) |
| --remove-moved | Remove the old copy of files the AI moved, if you haven't changed them |
| --allow-delete | Delete files the AI asked to delete, if you haven't changed them |
| -n, --dry-run | Show what would change; write nothing |
| -v, --verbose | List every file and what will happen to it |
| --review | Decide in a local browser page |
| --editor | Resolve in VS Code (or Cursor, Windsurf, VSCodium) |
| --safe-only | Apply only the safe changes |
| -y, --yes | Apply everything; the AI's version wins. Never removes files |