Personal pi-setup for Pi coding agent: extensions, custom themes, skills, config examples, and sync tooling.

Recommendation: install the Pi CLI first, then run this setup. This repo wraps and customizes an existing Pi install; it is not a replacement installer for Pi itself.

~/.pi/agent is the live Pi setup. This repo is the versioned pi-setup copy used to back up that live setup to GitHub and recreate it on any machine.

Live Pi runtime / source of truth:
  ~/.pi/agent/extensions
  ~/.pi/agent/themes
  ~/.pi/agent/skills
  ~/.pi/agent/settings.json
  ~/.pi/agent/mcp.json

Versioned pi-setup repo:
  ~/dev/ai-agents/pi-setup
  updated from live Pi files by pi-setup-sync

Normal flow:

make Pi changes in ~/.pi/agent  ->  pi-setup-sync  ->  GitHub
GitHub clone on another machine ->  install Pi CLI -> ./install.sh --restore --copy-config -> ~/.pi/agent

Do not install this checkout as an active Pi package in normal use. Loading both ~/.pi/agent and this repo causes duplicate skill/theme conflict warnings at startup. If you are editing Pi functionality while your shell is inside this repo, edit the live file under ~/.pi/agent/... first, then run pi-setup-sync to copy it back here.

• bin/pi — compact Pi launcher wrapper
  • one-line major/minor update notices instead of large startup boxes
  • preserves Pi's native themed header and loaded skills/extensions/themes listing
• extensions/ — versioned copies of custom Pi extensions
  • themed startup welcome card
  • /context usage breakdown for startup tokens, messages, and tool calls (scrollback output; not added to model context)
  • /filechanges review/accept/decline workflow for Pi-made edit/write changes
  • custom footer with token usage and git branch
  • local model manager
• themes/ — versioned copies of custom themes
  • nebula-pulse (current default)
  • opencode
  • tokyo-night
  • one-dark-pro
  • dracula
  • catppuccin-mocha
  • nord
  • gruvbox
  • rose-pine
  • synthwave-84
• skills/ — versioned portable copies of installed Pi skills
  • diagnose, find-docs, find-skills, grill-me, grill-with-docs, handoff, hf-cli, improve-codebase-architecture, mcp-code-search, teach, write-a-skill
• config/ — safe example config files

Install Pi first (preferred), so pi already works before this repo adds the optional compact launcher. In containers or unusual installs, Pi may live at /usr/local/bin/pi; the launcher now detects that, and you can override it with PI_REAL_BIN=/path/to/pi.

On a minimal Ubuntu machine/container, install clone prerequisites first:

sudo apt-get update
sudo apt-get install -y git ca-certificates

Clone the repo, then restore the live Pi setup from it:

git clone git@github.com:abhinand5/pi-setup.git ~/dev/ai-agents/pi-setup
cd ~/dev/ai-agents/pi-setup
./install.sh --restore --copy-config

For HTTPS:

git clone https://github.com/abhinand5/pi-setup.git ~/dev/ai-agents/pi-setup
cd ~/dev/ai-agents/pi-setup
./install.sh --restore --copy-config

--restore copies repo resources into ~/.pi/agent/extensions, ~/.pi/agent/themes, and ~/.pi/agent/skills.

--copy-config copies config/settings.example.json and config/mcp.example.json into ~/.pi/agent/.

The example settings intentionally do not include personal model/provider selections (defaultProvider, defaultModel, or enabledModels). Configure your own models after restore; otherwise Pi may warn about model IDs that only exist on someone else's machine.

Warnings:

• --restore replaces the current contents of those live resource directories.
• --copy-config overwrites ~/.pi/agent/settings.json and ~/.pi/agent/mcp.json.

pi-setup-sync does not hardcode a GitHub URL. It commits in the checkout it is installed from and runs git push, so it uses that checkout's configured git remote.

For your own backup, fork or create your own repo first, then clone that repo:

git clone git@github.com:<user>/<repo>.git ~/dev/ai-agents/pi-setup
cd ~/dev/ai-agents/pi-setup
./install.sh --restore --copy-config

If you cloned this repo first and want future syncs to push to your own GitHub repo, change origin:

git remote -v
git remote set-url origin git@github.com:<user>/<repo>.git
git remote -v

Then pi-setup-sync will back up your live ~/.pi/agent changes to that remote.

On a machine that already has the live files in ~/.pi/agent, run:

./install.sh

This installs:

• pi-setup-sync into ~/.local/bin
• compact launcher bin/pi into ~/.local/bin/pi

It also removes any legacy settings entry that points Pi at this repo as an active package.

To remove only what this repo installed/restored while leaving the underlying Pi CLI untouched:

./uninstall.sh

This removes the compact launcher, the pi-setup-sync helper if it points at this checkout, and restored resources under ~/.pi/agent/extensions, themes, and skills that are owned by this repo. It removes copied example config files only when they are still identical to the examples; modified settings are left in place.

Preview first:

./uninstall.sh --dry-run

After changing Pi locally, run this from the repo:

./sync.sh

Install the global helper from this checkout:

./setup_sync.sh

Then use it from anywhere:

pi-setup-sync

pi-setup-sync copies current ~/.pi/agent/extensions, ~/.pi/agent/themes, selected skills, settings.json, and mcp.json into this repo, validates JSON/theme tokens, commits, and pushes. It strips any self-referential package entry that would make Pi load this pi-setup repo at startup.

Syncing requires git and python3; pushing requires normal GitHub credentials for this repo.

Custom commit message:

pi-setup-sync "Update themes and footer"

Commit without pushing:

pi-setup-sync --no-push "Checkpoint local Pi setup"

Skill backup scans ~/.pi/agent/skills and ~/.agents/skills, resolves symlinks, dedupes duplicates, and stores portable copies in skills/. All skills are selected by default; press Enter at the selector to accept all in one keystroke. To customize, use ↑/↓ to move, Space to toggle, a for all, n for none, and Enter to continue.

Non-interactive options:

pi-setup-sync --all-skills
pi-setup-sync --skills hf-cli,diagnose "Back up selected skills"
pi-setup-sync --no-skills "Skip skill backup"

Run the Docker end-to-end smoke test when you want to verify the setup/restore contract without adding CI:

tests/docker-e2e.sh

The test starts a fresh Ubuntu container, installs minimal clone prerequisites, clones this repo from its git remote, runs ./install.sh --restore --copy-config, verifies the live ~/.pi/agent layout, then checks that pi-setup-sync can copy a live change back into the cloned repo without pushing.

Useful variants:

tests/docker-e2e.sh --restore-only
tests/docker-e2e.sh --remote https://github.com/<user>/<repo>.git --branch main

Welcome update notices only appear for major/minor updates, not patches. Toggle them with:

/welcome updates on
/welcome updates off

Review files changed by Pi before keeping or reverting them:

/filechanges          # inspect tracked edit/write changes and diffs
/filechanges-accept   # keep files and clear the log
/filechanges-decline  # revert tracked changes

In non-interactive print/json mode, accept/decline require force.

Never commit secrets or runtime state:

• ~/.pi/agent/auth.json
• ~/.pi/agent/sessions/
• ~/.pi/agent/npm/
• ~/.pi/agent/git/
• ~/.pi/agent/local-models.json unless intentionally sanitized
• cache files such as mcp-cache.json

References and inspirations.

• Pi Packages
• mattpocock/skills
• amosblomqvist/pi-config
• llama.cpp
• noonghunna/club-3090
• r/LocalLLaMA