pi-builder

Personal Pi customization package for Pi.

This package helps you keep a private, editable copy of your Pi customization setup while installing the runtime extension through npm.

Installation

Install the package in Pi:

pi install npm:@dbaida/pi-builder

Restart Pi after installation, or run this inside Pi:

/reload

First run

On startup, pi-builder checks for GitHub CLI:

gh --version
gh auth status

If gh is installed and logged in, pi-builder creates or reuses a private GitHub repository in your account named:

pi-builder-config

Then it clones that private config repository to your global Pi agent directory:

~/.pi/agent/.pi-builder-config

After the private repository is ready, pi-builder updates your global Pi settings so future loads use the editable local config repo instead of the public npm package:

npm:@dbaida/pi-builder → ~/.pi/agent/.pi-builder-config

Restart Pi after this first-time switch so Pi loads the local package source.

If you use a custom Pi agent directory with PI_CODING_AGENT_DIR, the clone is created there instead:

$PI_CODING_AGENT_DIR/.pi-builder-config

The private config repo is initialized from:

https://github.com/dmytrobaida/pi-builder.git

You can override the private repo name with:

PI_BUILDER_CONFIG_REPO_NAME=my-custom-pi-config pi

Status widget

pi-builder shows a multiline widget below the editor with useful details:

pi-builder
  local: version 0.1.3-udv-1, 2 file(s) changed
  upstream: new version available: 0.1.4 (current 0.1.3)
  gh: authenticated
  path: ~/.pi/agent/.pi-builder-config

Refresh or print the same information on demand:

/pi-builder status

Customizing your private config

After first run, your editable config lives in:

~/.pi/agent/.pi-builder-config

Start with the single pi-builder command:

/pi-builder help

User customizations belong in the user/ directories:

user/extensions/  # custom Pi extensions
user/skills/      # custom skills
user/prompts/     # prompt templates
user/themes/      # themes

pi-builder protects its sealed runtime files from agent edits to reduce merge conflicts when you upgrade later. Ask Pi to place new custom code under user/ instead of editing the sealed package files.

The private config repo includes these guide files so users and agents do not need to search around:

AGENTS.md
CUSTOMIZE.md
user/README.md

Commands

Show help:

/pi-builder help

Show where the local config repository is stored:

/pi-builder repo-location

Ask Pi to extend your private config safely:

/pi-builder extend add a prompt template for reviewing pull requests

Create starter customization files:

/pi-builder new-extension current-time
/pi-builder new-skill release-checklist
/pi-builder new-prompt review-pr
/pi-builder new-theme my-theme

Copy global Pi resources into your private config repo:

/pi-builder sync-global

Validate your private config and reload Pi resources:

/pi-builder validate

Edit your personal injected agent rules:

/pi-builder agents

Rules are stored in user/AGENTS.md and injected into every session so you can define your own agent rules, code style, and preferences.

Commit, tag, and push local config changes to your private repo's main branch:

/pi-builder sync

Use this command instead of raw git push for config changes so each private-repo push includes the required user-development tag. Before committing, pi-builder checks that your local config repo is up to date with origin/main and remote user-development tags so it does not create duplicate tags or push over changes from another machine.

Sync tags use this format:

<current-extension-version>-udv-<number>

Example:

0.1.3-udv-1

Merge the latest upstream pi-builder changes into your private config repo, tag the result, and push it automatically:

/pi-builder upgrade

If Git reports merge conflicts, pi-builder stops before pushing so you can resolve them.

Check common setup problems:

/pi-builder doctor

Repeated workflow suggestions

If pi-builder notices you asking for a similar workflow repeatedly, it can ask whether you want to turn that workflow into a reusable skill, prompt, or extension under user/.

Updating

To update to the latest package version:

pi update npm:@dbaida/pi-builder

Or update all installed Pi packages:

pi update --extensions

Restart Pi after updating, or run:

/reload

Troubleshooting

Check that Pi sees the package:

pi list

If pi-builder reports that GitHub CLI is missing, install it and restart Pi:

brew install gh

If pi-builder reports that GitHub CLI is not logged in, run:

gh auth login

If the config repository was not cloned:

1. Check the bottom status bar for the error message.
2. Check that git and gh are installed.
3. Check that gh auth status succeeds.
4. Run /reload inside Pi or restart Pi.

If Pi still loads the npm package after the private repository is ready, restart Pi and check your global Pi settings:

~/.pi/agent/settings.json

The packages list should contain your local config repo path instead of npm:@dbaida/pi-builder.

Security

Pi extensions run with your local user permissions. Only install Pi packages from sources you trust.