Skip to content
Back to search

pi-setup

Personal Pi coding agent setup

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abhinand5--pi-setup/badge.svg)](/listings/abhinand5--pi-setup)

HTML

<a href="/listings/abhinand5--pi-setup"><img src="/api/listings/abhinand5--pi-setup/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Fast path with preview first:

# Show exactly what would change without installing anything
curl -fsSL https://raw.githubusercontent.com/abhinand5/pi-setup/main/install.sh \
  | bash -s -- --restore --copy-config --dry-run

# Install with a timestamped backup you can revert
curl -fsSL https://raw.githubusercontent.com/abhinand5/pi-setup/main/install.sh \
  | bash -s -- --restore --copy-config --backup

The one-line installer clones/updates this repo at `~/dev/ai-agents/pi-setup` by default, then runs the checked-out installer. Override with `PI_SETUP_CHECKOUT=/path/to/pi-setup` or `PI_SETUP_REPO_URL=https://github.com/<user>/<repo>.git`.

Manual clone path:

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 --backup

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 --backup

Useful installer options:

./install.sh --restore --copy-config --dry-run   # preview without changing files
./install.sh --restore --copy-config --backup    # save current live files first
./install.sh --revert ~/.pi/agent/backups/pi-setup-YYYYMMDD-HHMMSS

`--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/`.

`--backup` saves current `extensions`, `themes`, `skills`, `settings.json`, and `mcp.json` under `~/.pi/agent/backups/pi-setup-*` before replacing anything. Revert with the exact command printed at the end of install.

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`. - Use `--dry-run` first if you only want to preview the restore.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 359 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Abhinand's Pi Setup
  2. <p align="center">
  3. <img src="assets/featured.png" alt="Pi setup screenshot" width="800">
  4. </p>
  5. Personal `pi-setup` for [Pi coding agent](https://pi.dev): extensions, custom themes, skills, config examples, and sync tooling.
  6. **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.
  7. ## Core model
  8. `~/.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.
  9. ```txt
  10. Live Pi runtime / source of truth:
  11. ~/.pi/agent/extensions
  12. ~/.pi/agent/themes
  13. ~/.pi/agent/skills
  14. ~/.pi/agent/settings.json
  15. ~/.pi/agent/mcp.json
  16. Versioned pi-setup repo:
  17. ~/dev/ai-agents/pi-setup
  18. updated from live Pi files by pi-setup-sync
  19. ```
  20. Normal flow:
  21. ```txt
  22. make Pi changes in ~/.pi/agent -> pi-setup-sync -> GitHub
  23. GitHub clone on another machine -> install Pi CLI -> ./install.sh --restore --copy-config -> ~/.pi/agent
  24. ```
  25. 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.
  26. ## What's included
  27. | Area | Included |
  28. | --- | --- |
  29. | Launcher | Compact `pi` wrapper with one-line major/minor update notices |
  30. | Install safety | `--dry-run` preview, `--backup`, and `--revert <backup-dir>` |
  31. | Sync | `pi-setup-sync` copies live `~/.pi/agent` resources back to this repo, commits, and pushes |
  32. | Extensions | welcome header, context breakdown, file-change review, safety guard, custom footer, local model manager |
  33. | Config examples | Safe `settings.example.json` and `mcp.example.json` without personal provider/model choices |
  34. | Themes | `nebula-pulse`, `opencode`, `tokyo-night`, `one-dark-pro`, and more |
  35. | Skills | Portable backups of installed Pi/agent skills |
  36. | Smoke test | Docker restore/sync contract test in `tests/docker-e2e.sh` |
  37. - `bin/pi` — compact Pi launcher wrapper
  38. - one-line major/minor update notices instead of large startup boxes
  39. - suppresses Pi's large built-in update boxes via `PI_OFFLINE=1` after its own compact notice
  40. - detects the real Pi binary from `PI_REAL_BIN`, `/usr/local/bin/pi`, `/usr/bin/pi`, or `/opt/homebrew/bin/pi`
  41. - preserves Pi's native themed header and loaded skills/extensions/themes listing
  42. - `extensions/` — versioned copies of custom Pi extensions
  43. - themed startup welcome card with `/welcome updates on|off`
  44. - `/context` usage breakdown for startup tokens, messages, and tool calls (scrollback output; not added to model context)
  45. - `/filechanges` review/accept/decline workflow for Pi-made `edit`/`write` changes
  46. - `/safety` and `/permissions` guard rails for risky shell/file actions
  47. - custom footer with input/output/reasoning tokens, cost, context %, tokens/sec, model, thinking level, and git branch
  48. - `/local-models` manager for OpenAI-compatible local endpoints such as Ollama, LM Studio, RunPod, or llama.cpp servers
  49. - `themes/` — versioned copies of custom themes
  50. - `nebula-pulse` *(current default)*
  51. - `opencode`
  52. - `tokyo-night`
  53. - `one-dark-pro`
  54. - `dracula`
  55. - `catppuccin-mocha`
  56. - `nord`
  57. - `gruvbox`
  58. - `rose-pine`
  59. - `synthwave-84`
  60. - `skills/` — versioned portable copies of installed Pi skills
  61. - diagnose, find-docs, find-skills, grill-me, grill-with-docs, handoff, hf-cli, improve-codebase-architecture, mcp-code-search, teach, write-a-skill
  62. - `config/` — safe example config files
  63. ## Set up from GitHub on a machine
  64. 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`.
  65. On a minimal Ubuntu machine/container, install clone prerequisites first:
  66. ```bash
  67. sudo apt-get update
  68. sudo apt-get install -y git ca-certificates
  69. ```
  70. Fast path with preview first:
  71. ```bash
  72. # Show exactly what would change without installing anything
  73. curl -fsSL https://raw.githubusercontent.com/abhinand5/pi-setup/main/install.sh \
  74. | bash -s -- --restore --copy-config --dry-run
  75. # Install with a timestamped backup you can revert
  76. curl -fsSL https://raw.githubusercontent.com/abhinand5/pi-setup/main/install.sh \
  77. | bash -s -- --restore --copy-config --backup
  78. ```
  79. The one-line installer clones/updates this repo at `~/dev/ai-agents/pi-setup` by default, then runs the checked-out installer. Override with `PI_SETUP_CHECKOUT=/path/to/pi-setup` or `PI_SETUP_REPO_URL=https://github.com/<user>/<repo>.git`.
  80. Manual clone path:
  81. ```bash
  82. git clone git@github.com:abhinand5/pi-setup.git ~/dev/ai-agents/pi-setup
  83. cd ~/dev/ai-agents/pi-setup
  84. ./install.sh --restore --copy-config --backup
  85. ```
  86. For HTTPS:
  87. ```bash
  88. git clone https://github.com/abhinand5/pi-setup.git ~/dev/ai-agents/pi-setup
  89. cd ~/dev/ai-agents/pi-setup
  90. ./install.sh --restore --copy-config --backup
  91. ```
  92. Useful installer options:
  93. ```bash
  94. ./install.sh --restore --copy-config --dry-run # preview without changing files
  95. ./install.sh --restore --copy-config --backup # save current live files first
  96. ./install.sh --revert ~/.pi/agent/backups/pi-setup-YYYYMMDD-HHMMSS
  97. ```
  98. `--restore` copies repo resources into `~/.pi/agent/extensions`, `~/.pi/agent/themes`, and `~/.pi/agent/skills`.
  99. `--copy-config` copies `config/settings.example.json` and `config/mcp.example.json` into `~/.pi/agent/`.
  100. `--backup` saves current `extensions`, `themes`, `skills`, `settings.json`, and `mcp.json` under `~/.pi/agent/backups/pi-setup-*` before replacing anything. Revert with the exact command printed at the end of install.
  101. 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.
  102. Warnings:
  103. - `--restore` replaces the current contents of those live resource directories.
  104. - `--copy-config` overwrites `~/.pi/agent/settings.json` and `~/.pi/agent/mcp.json`.
  105. - Use `--dry-run` first if you only want to preview the restore.
  106. ## Use your own GitHub repo
  107. `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.
  108. For your own backup, fork or create your own repo first, then clone that repo:
  109. ```bash
  110. git clone git@github.com:<user>/<repo>.git ~/dev/ai-agents/pi-setup
  111. cd ~/dev/ai-agents/pi-setup
  112. ./install.sh --restore --copy-config
  113. ```
  114. If you cloned this repo first and want future syncs to push to your own GitHub repo, change `origin`:
  115. ```bash
  116. git remote -v
  117. git remote set-url origin git@github.com:<user>/<repo>.git
  118. git remote -v
  119. ```
  120. Then `pi-setup-sync` will back up your live `~/.pi/agent` changes to that remote.
  121. ## Install helper commands only
  122. On a machine that already has the live files in `~/.pi/agent`, run:
  123. ```bash
  124. ./install.sh
  125. ```
  126. This installs:
  127. - `pi-setup-sync` into `~/.local/bin`
  128. - compact launcher `bin/pi` into `~/.local/bin/pi`
  129. It also removes any legacy settings entry that points Pi at this repo as an active package.
  130. ## Uninstall pi-setup changes
  131. To remove only what this repo installed/restored while leaving the underlying Pi CLI untouched:
  132. ```bash
  133. ./uninstall.sh
  134. ```
  135. 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.
  136. Preview first:
  137. ```bash
  138. ./uninstall.sh --dry-run
  139. ```
  140. ## Sync live Pi tweaks back to GitHub
  141. After changing Pi locally, run this from the repo:
  142. ```bash
  143. ./sync.sh
  144. ```
  145. Install the global helper from this checkout:
  146. ```bash
  147. ./setup_sync.sh
  148. ```
  149. Then use it from anywhere:
  150. ```bash
  151. pi-setup-sync
  152. ```
  153. `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.
  154. Syncing requires `git` and `python3`; pushing requires normal GitHub credentials for this repo.
  155. Custom commit message:
  156. ```bash
  157. pi-setup-sync "Update themes and footer"
  158. ```
  159. Commit without pushing:
  160. ```bash
  161. pi-setup-sync --no-push "Checkpoint local Pi setup"
  162. ```
  163. 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.
  164. Non-interactive options:
  165. ```bash
  166. pi-setup-sync --all-skills
  167. pi-setup-sync --skills hf-cli,diagnose "Back up selected skills"
  168. pi-setup-sync --no-skills "Skip skill backup"
  169. ```
  170. ## Manual tests
  171. Run the Docker end-to-end smoke test when you want to verify the setup/restore contract without adding CI:
  172. ```bash
  173. tests/docker-e2e.sh
  174. ```
  175. 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.
  176. Useful variants:
  177. ```bash
  178. tests/docker-e2e.sh --restore-only
  179. tests/docker-e2e.sh --remote https://github.com/<user>/<repo>.git --branch main
  180. ```
  181. ## Feature audit
  182. This repo currently includes these Pi customizations.
  183. ### Launcher and startup
  184. - `bin/pi` wraps an existing Pi CLI instead of replacing it.
  185. - Shows compact update notices only for major/minor Pi or npm package updates.
  186. - Uses `PI_COMPACT_UPDATE_CHECK=0` or `/welcome updates off` to disable compact update notices.
  187. - Uses `PI_REAL_BIN=/path/to/pi` if Pi is installed somewhere unusual.
  188. - `extensions/flow-title.ts` replaces the startup header with a themed Pi logo, version, active model, cwd, key hints, and project name.
  189. ### Commands added by extensions
  190. ```txt
  191. /welcome updates on|off # toggle compact startup update notices
  192. /context # explain context-window usage
  193. /filechanges # inspect tracked edit/write changes and diffs
  194. /filechanges-accept [force] # keep files and clear the filechanges log
  195. /filechanges-decline [force] # revert tracked Pi-made changes
  196. /safety enable|disable|status # manage Safety Guard
  197. /permissions ... # alias for /safety
  198. /local-models # add, refresh, remove, and select local LLM endpoints
  199. ```
  200. ### Context and review workflow
  201. - `/context` estimates startup prompt, skills, context files, selected tools, messages, and tool-call result usage.
  202. - `/filechanges` tracks successful Pi `edit` and `write` tool calls, stores baselines in the session, shows a status/widget, renders diffs, and can accept or revert all tracked changes.
  203. - Non-interactive accept/decline requires `force` to avoid accidental destructive reverts.
  204. ### Safety Guard
  205. - Injects a short safety instruction before agent start.
  206. - Blocks or asks for confirmation before destructive/risky actions not explicitly requested by the user.
  207. - Detects force pushes, amend/rebase/reset hard, branch/tag deletion, recursive deletion, protected path writes, package removals, service changes, broad `sudo`, and context purge.
  208. - In git repos, normal recoverable edits are allowed without extra prompts.
  209. ### Local models
  210. - `/local-models` manages OpenAI-compatible endpoints.
  211. - Stores endpoint metadata in `~/.pi/agent/local-models.json`.
  212. - Registers available models as `local-<endpoint-id>` providers during extension load so `/model` can see them.
  213. - Supports endpoint refresh, model selection, and endpoint removal.
  214. ### Footer and themes
  215. - Custom footer shows input/output/reasoning tokens, cost, context percentage, tokens/sec, current model, thinking level, and git branch.
  216. - Theme files define reusable palettes for the header, footer, diffs, thinking levels, markdown, and tool output.
  217. ### Configured packages
  218. `config/settings.example.json` registers these external Pi packages by default:
  219. - ask-user-question and todo tools
  220. - Markdown preview/export
  221. - MCP adapter
  222. - context-mode and related context skills
  223. - goal completion helper
  224. - advisor tool
  225. - spinner, rewind, `/btw`, and fff search
  226. `config/mcp.example.json` currently configures the remote grep MCP server.
  227. ## Useful Pi commands
  228. Welcome update notices only appear for major/minor updates, not patches. Toggle them with:
  229. ```txt
  230. /welcome updates on
  231. /welcome updates off
  232. ```
  233. Review files changed by Pi before keeping or reverting them:
  234. ```txt
  235. /filechanges # inspect tracked edit/write changes and diffs
  236. /filechanges-accept # keep files and clear the log
  237. /filechanges-decline # revert tracked changes
  238. ```
  239. In non-interactive print/json mode, accept/decline require `force`.
  240. ## Do not commit
  241. Never commit secrets or runtime state:
  242. - `~/.pi/agent/auth.json`
  243. - `~/.pi/agent/sessions/`
  244. - `~/.pi/agent/npm/`
  245. - `~/.pi/agent/git/`
  246. - `~/.pi/agent/local-models.json` unless intentionally sanitized
  247. - cache files such as `mcp-cache.json`
  248. ## References / Citations
  249. References and inspirations.
  250. - [Pi Packages](https://pi.dev/packages)
  251. - [mattpocock/skills](https://github.com/mattpocock/skills)
  252. - [amosblomqvist/pi-config](https://github.com/amosblomqvist/pi-config)
  253. - [llama.cpp](https://github.com/ggml-org/llama.cpp)
  254. - [noonghunna/club-3090](https://github.com/noonghunna/club-3090)
  255. - [r/LocalLLaMA](https://www.reddit.com/r/LocalLLaMA)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.