Zipflow

Zipflow is an interactive terminal application for safely reviewing and applying source-code updates delivered as ZIP archives.

It inspects an archive before touching the project, shows the planned file changes, handles conflicts, creates recoverable backups, runs project checks, and can optionally commit or deploy the result.

Install

Zipflow requires Node.js 20 or newer on macOS or Linux.

npm install --global zipflow

Then run it from a project directory:

cd /path/to/project
zipflow

Quick start

On the first run, Zipflow:

1. Detects the project and immediate subprojects.
2. Suggests tests, checks, and deployment commands.
3. Lets you review the workflow before saving it.

For each update:

1. Enter or drag the ZIP path into the terminal.
2. Review the archive root, warnings, changed files, conflicts, and diff.
3. Apply the update as a recoverable transaction.
4. Run the configured checks.
5. Optionally create a Git commit and run deployment.
6. Keep the result or roll it back from history.

Archive → Review → Apply → Checks → Finish

Main features

• Overlay updates and full-project snapshots, with warnings when a supposed snapshot looks like a partial patch.
• Archive validation and project-path confinement.
• File-level conflict review and diff inspection.
• Automatic restoration when application fails partway through.
• Stored backups and guarded rollback.
• Node.js, Python, CMake/C++, Go, SwiftPM, and Xcode detection.
• Multi-project workspaces with commands executed from their configured subdirectories.
• Custom checks and deployment commands using web/ :: npm test syntax.
• Optional local LLM integration through native Ollama, native LM Studio, a configurable OpenAI-compatible /v1 server, or Codex app-server RPC with a managed default endpoint and an explicit external-server toggle.
• Optional persistent LLM token statistics with exact provider usage when available, estimated fallback accounting, provider/model breakdowns, and an explicit reset action.
• Historical replay and autopilot simulation expose the exact model prompts with P, use a lazy virtualized prompt viewer with Terlio syntax/diff rendering, and show per-run input/output token usage even when persistent statistics are disabled.
• Archive suitability review distinguishes partial archives from archives belonging to another project and recommends cancellation instead of snapshot reinterpretation for project mismatches.
• Manual, Guarded autopilot, and Full autopilot decision modes.
• Run history, performance analytics, reports, stored patches, and ZIP export.
• Configurable startup update checks, manual version checks, and one-step global npm updates.
• System-locale interface selection by default, complete English and Russian catalogs, expanded core German, French, Italian, and Spanish translations, and custom JSON language packs.

Useful controls

↑ / ↓       move through choices
Shift+K/J   reorder checks during workflow setup (reliable in macOS Terminal)
Shift+↑/↓   reorder checks when the terminal reports Shift-modified arrows
Space       toggle or select
Enter       open or confirm
Esc         go back; from the archive prompt, open the project menu
Tab         complete paths or switch Settings panes
Shift+Tab   return to the parent directory during path completion
/           search the active list
?           open contextual help or structured statistics
Ctrl+B      open global settings
Ctrl+T      toggle native terminal text selection
Ctrl+C      cancel an active operation; exit while idle

Press Esc from the archive prompt to open project actions such as Change workflow, Run history, Run tests, Run deployment, Create ZIP, and Exit.

When a newer globally installed npm version is available, Zipflow offers to install it at startup and then restart the application.

Documentation

Start with the documentation index.

• Getting started
• Archive workflows
• Safety, conflicts, and rollback
• Project detection and checks
• Multi-project workspaces
• Local LLM integration
• Decision modes and autopilot
• Settings, history, and storage
• Automatic updates
• Interface and controls
• Interface localization

Development

npm install
npm run verify
npm run release:check

See Development and publishing for local linking, verification, package inspection, versioning, and npm publication.

License

MIT