ZipPy

ZipPy builds clean archive packs for code review and LLM context.

Note

This is a passion project of mine and I use it daily to prepare context for my own development workflows.

What it does

• Scans a target folder
• Keeps high-signal files
• Builds context chunks
• Writes size-limited zip archives with metadata

Modes

• auto: tries decompilation/analyzers for binaries, then merges text output
• auto-all: full-auto pack of all packable non-visual files (bypasses ignore rules and disables heuristics; hard excludes still apply)
• context: merges readable files into context chunks
• direct: archives original files directly (merges .pyc context unless --pure is used)

Profiles

• llm_min (default): token-minimal review pack (intent chunks, binary stubs, lockfile exclusion, compact git summary)
• llm_forensic: richer metadata profile (for reproducibility/audits)

Defaults

• Runtime output goes to an OS user cache dir:
  • Windows: %LOCALAPPDATA%\\ZipPy\\archives\\<target>\\<run_id>\\
  • Linux: $XDG_CACHE_HOME/zippy/archives/<target>/<run_id>/ (or ~/.cache/zippy/...)
  • macOS: ~/Library/Caches/zippy/archives/<target>/<run_id>/
• Temporary files go to the matching cache tmp/ directory.
• Hard excludes always apply (.git, __pycache__, .cache, .ruff_cache, .pytest_cache, node_modules, *.egg-info, build folders, etc.)
• Smart filtering applies .gitignore plus ZipPy-specific .zipignore rules (.zippyignore is still supported for compatibility); using --all bypasses ignore rules for both profiles (hard excludes still apply)
• llm_min excludes LICENSE/NOTICE text bodies by default
• If the source folder is the repo root, ZipPy prefers git-tracked files.
• New: If no files are tracked, it automatically falls back to all files.
• Binary evidence defaults:
  • llm_min: summary
  • llm_forensic: decompiled
• Test payload defaults:
  • llm_min: sample (plus TEST_INDEX.md)
  • llm_forensic: all

Install

1. Clone the repo
2. Use Python 3.9+

git clone https://github.com/FelixCAxO/ZipPy.git
cd ZipPy
python --version

Run

Windows:

• Use scripts/run_zippy.bat (drag and drop a folder, or enter a path)

Linux/macOS:

chmod +x scripts/run_zippy.sh
./scripts/run_zippy.sh /path/to/target

CLI:

pip install -e .[auto]
zippy /path/to/target --mode auto --max-size 100 --output ./my_packs

Advanced:

zippy /path/to/target --mode auto --smart
zippy /path/to/target --mode auto-all
zippy /path/to/target --json
zippy /path/to/target --mode direct --pure
zippy /path/to/target --mode context --profile llm_forensic
zippy /path/to/target --mode direct --profile llm_forensic --all --no-heuristic-filter

Without installation (from repo root):

PYTHONPATH=src python -m zippy /path/to/target --mode context

Flags:

• --output <dir>: specify where to save archives and reports
• --size <MB>: max ZIP archive size in MB
• --max-size <MB>: max uncompressed context budget in MB (for generated context chunks)
• --json: prints a machine-readable summary JSON to stdout
• --pure: (direct mode) skip .pyc decompilation/merging
• --smart: smart filtering mode (default)
• --all: force scanner include-all mode (bypasses ignore rules); hard excludes and profile-level pruning still apply
• --heuristic-filter: enable heuristic noise filtering (default)
• --no-heuristic-filter: disable heuristic noise filtering
• --include-untracked: include untracked files under src/, tests/, docs/, scripts/ (default)
• --tracked-only: strict tracked-only mode (plus minimal allowlist)
• --follow-symlinks: follow symlinked directories/files during scan
• --no-follow-symlinks: do not follow symlinks (default)
• --no-wait: do not wait for user input (useful for automation)
• --profile <llm_min|llm_forensic>: choose token-minimal or forensic metadata profile
• --binary-evidence <none|summary|strings|extracted_only|text_extracted|decompiled|disasm>: recovered binary evidence level (profile default when omitted)
• --tests-policy <none|sample|all>: test payload policy (profile default when omitted)
• --allow-incomplete-pack: allow output when internal import closure remains incomplete

auto-all behavior:

• bypasses ignore rules
• disables heuristics automatically
• defaults test payload selection to all
• keeps hard excludes for images/visual media, caches, builds, and tool/runtime noise
• keeps non-visual artifacts such as PDFs in the end product via recovered text evidence when possible

Ignore files:

• .gitignore keeps standard Git semantics
• .zipignore uses Git-style pattern syntax for ZipPy packing rules
• .zippyignore remains supported as a backward-compatible alias

Output layout

Context/auto run folder:

• 00_ROUTER.txt
• FILES.txt
• PACK_STATS.txt
• TEST_INDEX.md (when tests policy is not all)
• DEPENDENCIES_SUMMARY.txt (when package.json exists)
• LLM_README.md
• ENTRYPOINTS.md
• ARCHITECTURE_MAP.md
• MANIFEST.jsonl (llm_forensic)
• GIT_SUMMARY.txt (llm_min) or GIT_METADATA.md (llm_forensic)

Direct run folder:

• one or more direct_project_*.zip archives
• GIT_SUMMARY.txt (llm_min) or GIT_METADATA.md (llm_forensic)
• report.txt, report.json
• SET_INDEX.md (llm_forensic)

Zip-level index:

• INDEX_THIS_ZIP.json in every archive

Run-level full index:

• SET_INDEX.md in auto and direct runs (llm_forensic)

LLM chunk format:

• Compact framing: @@ FILE <path> ... @@ END
• Lockfiles are excluded in llm_min (kept in llm_forensic)
• Binary/media files are emitted as @@ BINARY stubs in sources/90_BINARY_STUBS.txt

Tests

python -m pytest -q

Project layout

ZipPy/
|-- src/
|-- tests/
|-- scripts/
|-- docs/
|-- README.md
|-- pyproject.toml
|-- .gitignore
|-- .zipignore
|-- .pre-commit-config.yaml
|-- LICENSE
|-- NOTICE
|-- LEGAL.md
`-- CONTRIBUTING.md

More docs

• Artifact Support Matrix: docs/support_matrix.md
• Architecture: docs/architecture.md
• Output contract: docs/output_contract.md
• Contributing: CONTRIBUTING.md
• Legal use: LEGAL.md

License

Apache License 2.0 (LICENSE)