pi-backup — Pi Backup & Restore Utilities

Complete, cross-platform backup/restore for the Pi coding agent. Backs up everything needed to restore to an equivalent state after a clean reinstall, with an interactive /pi-backup manager and 7-Zip-first archive support.

Installation

Via Pi Package Manager (recommended)

# From npm (when published)
pi install npm:@jamiefutch/pi-backup@latest

# From git
pi install git:github.com/jamiefutch/pi-backup@master

# From local path
pi install /path/to/pi-backup

Manual (add to settings.json)

{
  "packages": ["npm:@jamiefutch/pi-backup"]
}

Then restart Pi or run /reload.

Developer documentation

Repository-specific agent guidance is available in:

• .pi/agents.md — pi-backup project conventions and safety rules
• .pi/agents/pi-development-expert.md — detailed Pi extension, package, SDK, TUI, provider, and resource-development guidance

Scripts

| Script | Purpose | |--------|---------| | backup-pi.sh / backup-pi.ps1 | Creates timestamped backup of all Pi config, skills, extensions, memory | | pi-clean-reinstall.sh / pi-clean-reinstall.ps1 | Nuclear reinstall — wipes ~/.pi, uninstalls/reinstalls Pi (dangerous) | | restore-pi.sh / restore-pi.ps1 | Restores backup after fresh Pi install |

| Platform | Extensions | |----------|------------| | macOS / Linux (bash) | backup-pi.sh, restore-pi.sh, pi-clean-reinstall.sh | | Windows (PowerShell) | backup-pi.ps1, restore-pi.ps1, pi-clean-reinstall.ps1 (requires PowerShell 7 / pwsh) |

Archive format and compression

External backups are compressed automatically:

• If 7zz, 7z, or 7za is available on macOS, Linux, or Windows, Pi Backup uses 7-Zip and creates a .7z archive.
• Otherwise it falls back to native platform tools and creates a .zip archive (zip/unzip on macOS/Linux, Compress-Archive/Expand-Archive on Windows).
• Restoring a .7z archive requires 7-Zip to be installed and available on PATH.
• The TUI uses the same preference for creating, restoring, copying, and viewing manifests.
• Internal backups remain uncompressed directories for fast rollback.

The executable may be named 7zz, 7z, or 7za.

Usage

TUI Extension (after package install)

/pi-backup

Opens the Pi Backup Manager interactive menu:

Pi Backup Manager — 8 backups (1 internal, 7 external)
External dir: ~/pi-backups

 → 📦 Create internal backup  (~/.pi/backups/  — quick rollback)
   💾 Create external backup  (survives reinstall)
   📋 List all backups
   ⚙️  Configure external backup directory
   ❓ Help
   ← Exit

Main Menu Options

| Option | Description | Location | |--------|-------------|----------| | 📦 Create internal backup | Fast uncompressed backup for quick rollback during normal use | ~/.pi/backups/ | | 💾 Create external backup | Compressed archive for disaster recovery — survives clean reinstall | resolved per priority chain | | 📋 List all backups | Browse, restore, copy, delete, or view manifests of all backups | Both locations | | ⚙️ Configure external backup directory | Set or reset the settings.json externalBackupDir value | settings.json | | ❓ Help | Full documentation on backup locations, what's backed up, restore process | — | | ← Exit | Close the backup manager | — |

Backup List View

Backups (8 total)

 → 📁 pi-backup-20260812-112053  │  2026-08-12 11:20:53  │  1.6 MB  │  347 files
   💾 pi-backup-20260812-112019.7z  │  2026-08-12 11:20:19  │  1.6 MB  │  1 files • compressed
   💾 pi-backup-20260812-095402.zip  │  2026-08-12 09:54:02  │  1.6 MB  │  1 files • compressed
   ...
   🔄 Refresh
   ← Back

Columns: Location icon • Name • Timestamp • Size • File count • Compression status

Backup Actions (after selecting a backup)

Backup: pi-backup-20260812-112019.7z

 → 🔄 Restore this backup  (2026-08-12 11:20:19)
   📋 Copy to internal  (~/.pi/backups/)
   📄 View manifest
   🗑️ Delete
   ← Back

| Action | Description | |--------|-------------| | 🔄 Restore | Runs the platform restore script — overwrites all Pi config (requires confirmation) | | 📋 Copy to internal | Copies external backup to ~/.pi/backups/ for quick access (external only) | | 📄 View manifest | Opens MANIFEST.txt in editor (extracts from compressed archives) | | 🗑️ Delete | Permanently removes backup (requires confirmation) |

Backup Location Summary

| Location | Path | Survives Clean Reinstall? | Format | |----------|------|---------------------------|--------| | Internal | ~/.pi/backups/ | ❌ NO (wiped by rm -rf ~/.pi) | Uncompressed dirs | | External | ~/pi-backups/ | ✅ YES | Compressed (.7z/.zip) |

Key point: Always create an external backup before a clean reinstall. Internal backups are for quick rollbacks during normal use only.

Command Line (scripts directly)

1. Backup (before reinstall)

./backup-pi.sh

2. Clean Reinstall

./pi-clean-reinstall.sh

3. Restore a directory, .7z archive, or .zip archive

./restore-pi.sh ~/pi-backups/pi-backup-20260811-143000.7z

4. Reinstall npm deps + verify

cd ~/.pi/agent && npm install  # or bun install
pi --version
/ctx-doctor
/loop-police-status
/scoped-memory-status

Windows (PowerShell)

On Windows, use the .ps1 scripts from PowerShell 7 (pwsh). The backup data directory defaults to ~/pi-backups.

# 1. Backup (before reinstall)
.\backup-pi.ps1

# 2. Clean Reinstall (nuclear - wipes ~/.pi, uninstalls/reinstalls Pi)
.\pi-clean-reinstall.ps1

# 3. Restore
.\restore-pi.ps1 ~\pi-backups\pi-backup-20260811-143000

# 4. Reinstall npm deps + verify
cd ~\.pi\agent; npm install
pi --version
/ctx-doctor

Customize locations in PowerShell with environment variables (same names as the bash scripts):

$env:PI_ROOT='C:\Users\you\.pi'; $env:BACKUP_ROOT='D:\pi-backups'; .\backup-pi.ps1

Note: If the Execution Policy blocks scripts, run once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. With 7-Zip (7zz, 7z, or 7za) on PATH, backups are created as .7z; otherwise PowerShell's built-in Compress-Archive creates .zip files. restore-pi.ps1 prefers 7-Zip when available and uses Expand-Archive for ZIP fallback.

What Gets Backed Up

| Category | Paths | |----------|-------| | Core config | settings.json, auth.json, models.json, trust.json, keybindings.json, pix.json, optimizer.json, lmstudio.json.bak, hermes-memory-config.json, pi.code-workspace | | Extension configs | pi-hermes-memory-cleanup/scoped-memory.json, loop-police.json, pi-rtk/config.json, context-mode/config.json, pi-timeout/config.json, pi-context-viewer/config.json, pix-optimizer/config.json, pi-nvidia-nim/config.json | | Global skills | ~/.pi/agent/skills/ | | Project skills & memory | ~/.pi/agent/projects-memory/<project>/ | | Local extension source | $LOCAL_EXT_ROOT/pi-timeout/, pi-chunk/, pi-hermes-memory-cleanup/, pi-context-docs/ (defaults to ~/projects/) | | npm manifests | package.json, package-lock.json, npm-shrinkwrap.json from ~/.pi/agent/npm/ | | Hermes memory (active) | MEMORY.md, USER.md, failures.md, retired-*.md | | Cleanup backups | Last 5 from ~/.pi/agent/hermes-cleanup/ |

The backup script output:

════════════════════════════════════════════════════════════
  Pi Complete Backup
════════════════════════════════════════════════════════════
Source:      ~/.pi
Destination: ~/pi-backups/pi-backup-20260811-143000
...
Backup complete!
Location: ~/pi-backups/pi-backup-20260811-143000
Size:     12M
Files:    347

What Does NOT Get Backed Up (Regeneratable)

| Excluded | Why | |----------|-----| | ~/.pi/agent/sessions/ | Session history — regenerated | | ~/.pi/agent/context-mode/kb.sqlite | Knowledge base — rebuilt from indexed sources | | ~/.pi/agent/npm/node_modules/ | Dependencies — reinstalled via npm install | | ~/.pi/agent/loop-police-detections.jsonl | Detection logs — regenerated | | ~/.pi/agent/.pi-hermes-locks.sqlite* | Lock files — recreated |

Backup Location

~/pi-backups/
├── pi-backup-20260811-143000/
│   ├── MANIFEST.txt
│   ├── settings.json
│   ├── auth.json
│   ├── models.json
│   ├── skills/
│   ├── projects-memory/
│   ├── local-extensions/
│   ├── npm-manifests/
│   ├── pi-hermes-memory/
│   └── hermes-cleanup/
└── pi-backup-20260811-150000/
    ...

Each backup is self-contained with a MANIFEST.txt listing all files.

External Backup Directory Configuration

The external backup location is resolved in this priority order:

1. BACKUP_ROOT environment variable (highest priority)
2. externalBackupDir key in ~/.pi/agent/settings.json
3. Default: ~/pi-backups/

// ~/.pi/agent/settings.json
{
  "externalBackupDir": "/custom/path/to/backups"
}

In the TUI

Use the ⚙️ Configure external backup directory option in /pi-backup to set or reset the settings.json value:

• 📝 Change directory — prompt to type a path, saved to settings.json
• 🔄 Reset to default — removes the settings.json value, falls back to env var / default

When the prompt appears

The configure prompt only appears when creating an external backup if both of these are true:

• No BACKUP_ROOT env var and no externalBackupDir in settings.json, AND
• The default external directory is empty or missing

If the default directory already contains backups, it is treated as configured and used directly with no prompt. Restore never prompts (it uses the selected backup's direct path).

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | PI_ROOT | ~/.pi | Override Pi root directory | | BACKUP_ROOT | ~/pi-backups | Override backup destination (highest priority for the TUI too) | | LOCAL_EXT_ROOT | ~/projects | Override the directory containing local extension source repositories | | KEEP_UNCOMPRESSED | 0 | Keep the uncompressed staging directory after external backup; the TUI sets this automatically for internal backups | | PKG_MANAGER | bun | Package manager used by the clean-reinstall scripts (bun, npm, etc.) |

# Custom locations
PI_ROOT=/custom/.pi BACKUP_ROOT=/mnt/backups ./backup-pi.sh

Automation (Cron)

# Daily backup at 3 AM
0 3 * * * ./backup-pi.sh >> ~/pi-backup.log 2>&1

# Keep last 30 backups
0 4 * * * find ~/pi-backups -maxdepth 1 -type d -name 'pi-backup-*' -mtime +30 -exec rm -rf {} \;

Troubleshooting

| Issue | Fix | |-------|-----| | "Permission denied" | chmod +x backup-pi.sh restore-pi.sh | | "npm install fails" | Check Node.js version (need ≥22), try bun install | | "Skills not loading" | Verify settings.json has correct packages paths after restore | | "Models not found" | Check models.json restored correctly, restart Pi | | "Auth failed" | Verify auth.json restored, API keys valid |

Manual Verify Checklist After Restore

• [ ] pi --version shows correct version
• [ ] /ctx-doctor shows all checks pass
• [ ] /loop-police-status shows config loaded
• [ ] /scoped-memory-status shows enabled + last injection stats
• [ ] /memory-search "test" returns results
• [ ] /context-stats shows context breakdown
• [ ] /nim-status connects (if NVIDIA configured)
• [ ] Local extensions load (check settings.json paths)
• [ ] Run a simple task to verify end-to-end

License

MIT License

Copyright (c) 2025 Jamie Futch

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See the LICENSE file for the full license text.