Archivist

Archivist logo

Archivist recursively extracts ZIP files, restores timestamps, and removes the metadata left in AppleDouble, Windows, and Synology formats. Explicit image workflows inventory pictures on disk and inside ZIPs, then move or copy approved selections into a flat destination.

🚀 Getting Started

Install with uv, preview your first folder, and safely apply the changes.

Getting Started
🗂️ Usage

Learn how recursive extraction, existing folders, dry runs, and reports work.

Usage
Choose a workflow

Compare extraction and cleanup with picture inventory, move and copy in visual guides, with the options for each stage.

Choose a workflow
⚙️ Configuration

Review every command-line option and its matching environment variable.

Configuration
Read-only MCP

Connect a local client for bounded picture inventory and transfer previews.

Read-only MCP and Copilot integration
🐳 Docker

Run the distroless image as a non-root user with Docker or Compose.

Docker
🩺 Troubleshooting

Understand skipped archives, permissions, reports, and exit codes.

Troubleshooting
🧰 Contributing

Set up a development environment, run tests, and understand the project.

Contributing

What Archivist does

📦 Extracts recursively

ZIPs found inside other ZIPs are processed in the same run, up to ten levels deep.

🧹 Cleans metadata

Remove AppleDouble, .DS_Store, Thumbs.db, desktop.ini, and @eaDir artifacts.

🛡️ Starts safely

Every run is a preview until you explicitly pass --apply.

💣 Checks archives

Free-space and expansion-ratio checks guard against oversized archives and ZIP bombs.

♻️ Supports recovery

Use --send-to-bin to move removed items to the Recycle Bin or Trash.

📝 Reports every action

See extracted, removed, overwritten, and skipped items in the console and log file.

Preview before anything changes

Run Archivist without --apply to inspect every planned extraction and cleanup. When the report looks right, run the same command with --apply.

archivist --parent-folder "C:\photos"
archivist --parent-folder "C:\photos" --apply --send-to-bin

Product planning

The business requirements record the approved business scope, human approval, and measurement waiver. The image workflow specification records the implemented CLI workflow and settled policies; formal product/release sign-off and business measurements remain separate. The future capability specification preserves deferred generic file categories (including STL/3MF), mixed-ZIP policy options, and the independent conversational/AG-UI direction.