Documentation · 4 of 6

Apply changes back.

contextzip packages your project out to an AI tool. apply-zip is the other half of the round trip — it brings the AI's response back in, safely.

How it works

Every ZIP contextzip creates gets a sidecar manifest — a hash of every included file — written next to it in .contextzip/output/. Never inside the ZIP itself, so it's never uploaded and never visible to whatever AI tool receives the archive. When that tool hands a ZIP back, drop it in .contextzip/inbox/ (or pass an explicit path) and run apply-zip — it diffs the returned archive against that manifest before writing anything.

~/projects/my-app

$ contextzip apply-zip

Resolved: .contextzip/inbox/fix.zip

Diffing against .contextzip/output/codebase.manifest.json…

2 modified · 1 new · 6 unchanged

Backed up 2 files to .contextzip/backups/2026-08-26_141203/

Applied — 3 files written

How files are classified

Every file in the returned ZIP falls into one of five categories before anything is written. NEW and MODIFIED apply silently — DRIFTED and UNTRACKED are treated as risky and trigger a confirmation prompt, since applying them blindly could clobber work you did locally after the original ZIP was made.

Status	Meaning
NEW	Wasn't part of the original ZIP — no local baseline exists for it
MODIFIED	Was sent, content changed, and the local copy hasn't moved since — a clean, expected edit
UNCHANGED	Identical to what's already on disk — nothing to do
DRIFTED — risky	The local file changed since the ZIP was made (you edited it yourself, or it was deleted) — applying could overwrite your own work
UNTRACKED — risky	Present in the returned ZIP but wasn't part of the original manifest, and already exists locally at that path

If no manifest can be found at all, every pre-existing path is naturally treated as UNTRACKED — contextzip has no baseline to compare against, so it asks rather than assumes.

Backups & safety

Nothing is ever silently deleted

· Only adds and modifies files — deletions are never inferred or performed, even if a file that used to be in the manifest is absent from the returned ZIP.
· Every file that would be overwritten is backed up first, under .contextzip/backups/<timestamp>/.
· Risky changes (DRIFTED, UNTRACKED, or a ZIP whose structure looks wrong) prompt for confirmation before writing — unless --yes is passed.
· prompt.txt, which contextzip itself writes into outgoing ZIPs, is ignored on the way back in even if an AI tool echoes it — it's never treated as a project file to restore.

Workspace layout

Applied ZIPs are archived after a successful run, and old ones are pruned automatically — keep a longer audit trail by raising applied_zip_retention in the project config (default: keep the most recent 1).

.contextzip/

.contextzip/
  config.json               # team-shared preferences (committed)
  output/
    codebase.zip             # what you generate and send out
    codebase.manifest.json   # local-only — used by apply-zip, never uploaded
  inbox/
    fix.zip                  # drop AI-returned zips here
    applied/
      2026-08-26_141203-fix.zip   # archived after a successful apply-zip
  backups/
    2026-08-26_141203/       # pre-overwrite copies, one folder per run

Command options

Option	Description
[ZIP]	Explicit path to apply, overriding auto-detection from the inbox
--manifest PATH	Diff against a specific manifest instead of the most recently created one
-n, --dry-run	Preview what would change without writing anything
-v, --verbose	Show every file and its status, not just the summary
-y, --yes	Skip the confirmation prompt, even for risky changes

~/projects/my-app

$ contextzip apply-zip fix.zip --dry-run --verbose

lib/auth.ts — MODIFIED — would overwrite (backed up first)

app/login/page.tsx — DRIFTED — edited locally since zipping, needs review

Dry run — no files written

Prefer to review changes before applying?

Every option here is also callable from Python — apply_zip() raises typed exceptions instead of exiting.

Python API reference