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/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

.contextzip/output/ splits by run mode — a codebase/, git-changes/, and prompt/ subfolder for the plain, --git-changes, and --prompt runs respectively — so it's never ambiguous which zip came from which command. After every successful run, old zip/manifest/report sets, backups, and archived applied-zips are pruned automatically down to the most recent one — see cleanup in the project config to change how much is kept.

.contextzip/

.contextzip/
  config.json                    # team-shared preferences (committed)
  output/
    codebase/
      codebase.zip                # plain `contextzip`
      codebase.manifest.json      # local-only — used by apply-zip, never uploaded
    git-changes/
      changes.zip                 # `contextzip --git-changes`
    prompt/
      vibe.zip                    # `contextzip --prompt "..."`
  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