ContextZIP

Prepare a local project for ChatGPT web without rewriting its files.

ContextZIP is a lightweight Codex skill that copies the project files you choose into a flat, drag-and-drop upload folder. The copied file contents stay byte-for-byte identical to the originals. ContextZIP does not summarize, concatenate, compress, or send files to an API.

Why

Local coding agents are convenient for editing a repository, while ChatGPT web can be convenient for longer design discussions, debugging, research, and review. Moving the relevant project context between those environments is usually manual and error-prone.

ContextZIP turns this:

my-project/
├── README.md
├── src/
│   └── retrieval/
│       └── router.py
├── tests/
│   └── test_router.py
└── papers/
    └── bright.pdf

into this:

my-project/.contextzip/upload/
├── README.md
├── src__retrieval__router.py
├── tests__test_router.py
└── papers__bright.pdf

The files can then be selected together and dragged into a ChatGPT conversation or project.

Directory separators become __. Extensionless files such as Dockerfile receive a .txt suffix for web upload compatibility. Only the output filename changes; the file bytes do not.

Core principles

• Original contents only - copied files are verified byte-for-byte.
• No wrapper tokens - no XML, Markdown fences, generated summaries, or concatenation.
• Local only - no API key, hosted service, or automatic upload.
• Deterministic - selection uses paths, Git metadata, ignore rules, and explicit options rather than an LLM reading every file.
• Safe by default - common secrets, generated folders, symlinks, and oversized files are blocked or skipped.

ContextZIP reduces packaging overhead. It does not compress the original text tokens inside a file.

Install as a Codex skill

Clone the repository into your Codex skills directory:

git clone https://github.com/junjunjunbong/ContextZIP.git ~/.codex/skills/contextzip

Restart Codex if the skill is not discovered immediately.

Use

In Codex:

$contextzip

Useful variations:

$contextzip Prepare all eligible files in this project for ChatGPT web.
$contextzip Prepare only my current Git changes and the root context files.
$contextzip Dry-run first and do not open Finder.

The skill creates:

<project>/.contextzip/
├── upload/          # drag these files into ChatGPT
└── manifest.json    # local mapping and integrity record; not uploaded by default

Direct script use

The script uses only the Python standard library and requires Python 3.10 or later.

Preview all eligible files:

python3 scripts/pack.py --root /path/to/project --mode all --dry-run

Create a pack:

python3 scripts/pack.py \
  --root /path/to/project \
  --mode all \
  --max-files 40 \
  --open

Create a smaller pack from current Git changes plus root context files:

python3 scripts/pack.py \
  --root /path/to/project \
  --mode current \
  --max-files 40 \
  --open

Use --help for all options.

Selection behavior

When the project is a Git repository, ContextZIP uses Git to collect tracked files and unignored untracked files. This respects .gitignore without implementing a second ignore parser.

--mode all selects every eligible file.

--mode current selects files changed relative to HEAD, untracked files, and a small set of root context files such as README.md, AGENTS.md, pyproject.toml, and package.json.

Common generated directories are excluded, including:

.git, .contextzip, node_modules, .venv, venv, __pycache__,
dist, build, target, .next, coverage, and common tool caches

Common sensitive paths are blocked, including .env*, private keys, credential files, and service-account secrets. This is a path-based guardrail, not a full content secret scanner. Review the output before uploading it.

Supported files

The default allowlist covers common source code, configuration, text, research, office, notebook, and PDF formats. Use repeated --include patterns to include additional paths explicitly, and repeated --exclude patterns to remove paths.

Examples:

python3 scripts/pack.py --root . --include 'notes/**' --include '*.log'
python3 scripts/pack.py --root . --exclude 'outputs/**' --exclude '**/fixtures/**'

Explicit includes do not override the sensitive-file blocklist.

What ContextZIP intentionally does not do

• It does not summarize or rewrite files.
• It does not concatenate a repository into one generated document.
• It does not semantically rank files with an LLM.
• It does not upload anything to ChatGPT automatically.
• It does not claim to reduce the token count of the original file contents.

Development

Run the tests with:

python3 -m unittest discover -s tests -v