zuey-pi-setup
A portable snapshot of my pi setup — clone it and rebuild the full set of 24 extensions on a new machine.
pi 0.85.1 · Node 24 · macOS · Linux · Windows (Git Bash) · updated 2026-09-16
English · Tiếng Việt
Why this repo exists
pi has no config export/import. This repo is a deterministic way to carry the entire setup to another machine without copying caches:
~/.pi/agent/npm/(~250 MB) — not needed, pi reinstalls it fromsettings.json~/.pi/agent/auth.json— not committed (API keys + OAuth tokens), log in again on the new machine~/.pi/agent/sessions/(~56 MB) andmissions/— not committed (history/state, may contain internal data)
The mechanism: settings.json holds a packages array; pi reads it on startup and npm installs anything missing. So if you can carry the manifest, you carry the whole extension set.
Quickstart (new machine)
# 1) install pi, exact version
npm i -g @earendil-works/pi-coding-agent@0.85.1
# 2) clone
git clone https://github.com/mrgoonie/zuey-pi-setup.git
cd zuey-pi-setup
# 3) safe rehearsal into a temp dir (touches nothing real)
./scripts/pi-setup-restore.sh --from-config config --scratch --install --verify
# 4) the real thing
./scripts/pi-setup-restore.sh --install --verify
Then log the providers back in (auth is not in the repo):
pi auth check --provider opencode-go # and /login inside pi for each provider
One more manual step: @injaneity/pi-computer-use needs macOS Accessibility and Screen Recording granted to ~/Applications/pi-computer-use.app (it installs the helper itself). Run pi interactively once and finish the setup prompt — in print mode the extension stays inert.
Full details, copy/do-not-copy table, troubleshooting: docs/pi-setup-migration.md (Vietnamese only).
Windows: the scripts are bash → run them in Git Bash (or WSL), not PowerShell/cmd. See Windows (Git Bash).
Windows (Git Bash)
Verified end-to-end on Windows 11 + Git Bash (MSYS2, bash 5.3): restore → --install → --verify → backup → bundle rebuild. No extra steps beyond the Quickstart commands.
| Windows difference | Status |
|---|---|
| Shell | Git Bash (or WSL) is required. The scripts use POSIX bash plus MSYS tar/gzip/find/awk |
| Installing Node | Usually via fnm instead of nvm. pi installs globally per Node version → pi only exists in a shell that ran fnm use (path looks like .../fnm_multishells/<id>/pi) |
Counting packages (--verify) |
Uses node (as of this revision), not python3 — Windows often lacks python3, or hits the Microsoft Store stub |
shasum |
Absent in Git Bash → the script falls back to sha256sum |
Paths passed to the child pi |
MSYS converts PI_CODING_AGENT_DIR automatically (/c/Users/..., /tmp/... → C:/Users/...) — verified |
--scratch |
Works: mktemp -d plus path conversion for the child pi process |
| CRLF | Git Bash's bash tolerates CRLF (tested with a CRLF copy). .gitattributes still pins *.sh text eol=lf for safety |
| Symlinks | Creating them needs Developer Mode, but the repo only reads/backs up existing symlinks, so it does not matter |
tar |
Inside Git Bash this is GNU tar (/usr/bin/tar), not C:\Windows\System32\tar.exe |
| Terminal font | A Nerd Font is required while iconMode: "nerd" — see Terminal font |
The full Windows sequence:
# inside Git Bash
fnm use 24
npm i -g @earendil-works/pi-coding-agent@0.85.1
git clone https://github.com/mrgoonie/zuey-pi-setup.git && cd zuey-pi-setup
./scripts/pi-setup-restore.sh --from-config config --scratch --install --verify # rehearsal
./scripts/pi-setup-restore.sh --install --verify # for real
Screenshots
The statusline is laid out in exactly three rows — context bar scaled to the model's context window, token speed, git, cost, and other extensions' statuses pulled onto the same rows:
Light theme (thinking high) — cache-hit-rate and cache_ttl are 0 here, so they hide themselves:
Dark theme (thinking off) — all five widgets on row 2, including cache-hit-rate 79.8% and cache_ttl ~1s:
Cropped from CleanShot and compressed as WebP q90: 1078×626 / 40 KB and 1076×624 / 38 KB — 94% smaller than the original PNGs (696 KB). Unprocessed originals live in screenshots/originals/ (gitignored).
What's in the repo
zuey-pi-setup/
├── README.md ← you are reading this
├── README.vi.md Vietnamese README
├── .gitattributes keeps *.sh at LF (Windows-friendly)
├── docs/
│ └── pi-setup-migration.md detailed guide + verification data (Vietnamese)
├── fonts/ JetBrains Mono 1.0.2 (terminal font, OFL-1.1)
│ ├── README.md provenance, install steps, Nerd Font warning
│ ├── LICENSE.txt SIL Open Font License 1.1
│ └── JetBrainsMono-1.0.2/ ttf/ (1 MB, for terminals) + web/ (2 MB, for the web)
├── screenshots/ statusline images used in the README (WebP, ~40 KB each)
│ └── originals/ unprocessed CleanShot originals (gitignored)
├── scripts/
│ ├── pi-setup-backup.sh packages the current machine's setup
│ ├── pi-setup-restore.sh rebuilds that setup on a new machine
│ ├── pi-setup-verify-advisor.mjs validates advisor.json against pi-advisor-flow's real schema
│ ├── pi-lens-compact-lsp-status.mjs patches pi-lens so the LSP status line is compact (`LSP ✓` / `LSP ✗`)
│ └── pi-setup-patch-extensions.mjs patches the stale-ctx crashes in pi-footer + pi-goal-x (both live in node_modules)
├── backups/
│ └── pi-setup-portable.tar.gz ready-to-download bundle (filtered — see below)
└── config/ setup snapshot (plain files, git-diffable)
├── .pi-setup-exclude exclusion globs — backup honours this file
├── settings.json manifest of 24 packages + model/theme/compaction
├── advisor.json pi-advisor-flow config (at the config-dir root)
├── 99extensions.json 99percentpeople family config (todo namespace)
├── pi-lens-config.json pi-lens config — lives in ~/.pi-lens/, OUTSIDE the config dir
├── external-configs.txt manifest: which file goes where on restore
├── APPEND_SYSTEM.md extra system prompt
├── models-store.json model catalog (saves the 4h refresh wait)
├── model-fallback/
│ └── config.json pi-model-fallback rules (state.json is not taken)
└── extensions/ locally written extensions, not on npm
├── compaction-policy.ts the only compaction trigger in this setup (thresholds + failure backoff)
├── pi-footer-cache-tps.ts pushes cache-TTL + token speed (t/s) into pi-footer
└── pi-footer.json statusline layout (includes the context bar)
config/ is a mirror of the setup portion of ~/.pi/agent. Everything else (cache, secrets, history) is not included.
Not in the repo (generated by other tools, reinstallable)
| Excluded | Generated by | Why |
|---|---|---|
extensions/orca-*.ts (3 files, 1,239 lines) |
Orca (@orca-managed-pi-extension) |
Orca integration glue; Orca regenerates it when it manages pi |
extensions/agentkit-agent/, extensions/agentkit-hooks-engineer/ |
AgentKit (ak) |
1.2 MB of generated hooks plus caches holding absolute paths (native-skill-paths.json, 157 KB); ak reinstalls them |
missions/, memory/, skills/ |
pi / AgentKit | machine-specific state, not setup |
.pi-setup-exclude
scripts/pi-setup-backup.sh --config-dir config reads this file (one glob per line, # for comments) and deletes every match after mirroring. That is why re-running the backup never drags orca-*/agentkit-* back into the repo:
./scripts/pi-setup-backup.sh --config-dir config # → "excluded: 84 files matched .pi-setup-exclude"
Besides the two generated families it drops advisor-outcomes.jsonl, advisor-outcomes-salt (machine-local advisor logs) and extensions/*.bak* — the latter keeps the patch scripts' own backups (*.bak-pi-setup-patch) out of the repo.
The same file also works for tarball mode via --exclude-file:
./scripts/pi-setup-backup.sh -o backups/pi-setup-portable.tar.gz \
--exclude-file config/.pi-setup-exclude
A config that cannot be backed up: @pi-unipi/notify
~/.unipi/config/notify/config.json contains a Gotify token and Telegram botToken + chatId, so it is deliberately absent from EXTERNAL_CONFIGS — committing it would leak credentials to a public repo. Set it up again on the new machine:
/unipi:notify-set-gotify # configure the Gotify server
/unipi:notify-set-tg # configure the Telegram bot
/unipi:notify-settings # everything else
The same warning is written directly in scripts/pi-setup-backup.sh so it is not accidentally added later.
Config that lives outside the config dir
A few extensions keep config outside ~/.pi/agent/, so it cannot be collected by relative path. The script has a separate list for them:
# in scripts/pi-setup-backup.sh
EXTERNAL_CONFIGS=(
"~/.pi-lens/config.json:pi-lens-config.json"
)
- Backup copies each existing file into the artifact under
<name>(`pi-lens-config.