pi-mac-session-native-compression

A Pi extension for transparent native compression of Pi session .jsonl files on macOS.

It uses Applesauce with ZLIB compression while keeping the original session path, filename, and .jsonl format.

Pi can continue to read and resume compressed sessions normally; no decompression step or wrapper command is required.

Requirements

• macOS with a filesystem supporting native file compression (normally APFS)
• Pi >= 0.84.4
• The applesauce executable available on PATH

brew install applesauce

Install & Uninstall

pi install npm:pi-mac-session-native-compression

pi uninstall npm:pi-mac-session-native-compression

Behavior

• Silently does nothing on non-macOS platforms.
• Ordinary startup only loads JSON and retries unfinished or erroneous records; completed historical files are not inspected and directories are not traversed.
• Starting or switching into a session registers it as unfinished without reading its content or checking its fingerprint, so an interrupted run can recover next startup.
• Shutdown or switching out processes only the outgoing session and saves its final state.
• Weekly maintenance runs at startup when due: discovers untracked files and removes missing JSON entries, without opening or rechecking completed files. Missing or corrupt JSON triggers initial discovery.
• The active session is excluded from retries and discovery processing; only its path is resolved to safely handle aliases.
• Applesauce settings: ZLIB, level 5, minimum compression ratio 0.95, and verification.
• Leaves files uncompressed when native compression would not reduce physical storage.
• Records status in ~/.pi/agent/pi-mac-session-native-compression.json.
• Saves pending checkpoints before file mutation, then immediately saves settled results or errors. It never deletes session files.

The JSON inventory is trusted: external edits to completed historical files are not detected automatically. Untracked files are discovered during weekly maintenance, not every startup. Applesauce is only invoked when there is file processing to perform; shutdown also records its version.

Development

pnpm test
pnpm bench:startup
pnpm bench:startup --real-tool

The startup benchmark uses isolated synthetic sessions and moves its fixtures to Trash afterward. See PERF.md for measurements, workload limitations, and optional timing budgets.