pi-config-sync

Synchronize a Pi configuration between macOS, Linux, and Windows through a separate private Git repository. This repository contains the shareable CLI and Pi extension; your setup remains in the private repository you choose.

What is synchronized

Defaults:

• AGENTS.md, SYSTEM.md, APPEND_SYSTEM.md
• settings.json, with platform-specific values split out
• keybindings.json
• extensions/, skills/, prompts/, themes/, and agents/

Platform-specific defaults include shellPath, externalEditor, npmCommand, sessionDir, and httpProxy. Volatile values such as lastChangelogVersion and trackingId stay local. Install-identity keys (e.g. packages) are always shared — never split per-platform — so both machines use the identical install source.

Credentials, sessions, trust decisions, package caches, .env files, and private keys are excluded. A secret scanner blocks suspicious content before commit. models.json is only synchronized if explicitly included.

The repo manifest (pi-sync.json) is the single source of truth for install identity: it records the canonical Git URL and package version the last-syncing machine used. A new machine reads it to know what to install, and pi-sync doctor compares each machine's install against it to detect drift.

Installation

Install from this Git repository (works identically on macOS, Linux, and Windows; the built dist/ is committed so the pi-sync CLI works out of the box).

Bootstrap the CLI (one command, same on every platform — use the plain https:// URL; pnpm rejects the git: prefix that is pi's spec shorthand):

pnpm add --global https://github.com/m-weida/pi-config-sync.git

Install the pi extension and verify with the single canonical command (derives the correct per-tool URL form from the repo manifest's installUrl — or --repo — runs both installs, then checks install identity):

pi-sync install

pi-sync install is idempotent: re-run it any time to repair the install or re-verify after an update. Pass --repo <url> to install from a different source, or --skip-pnpm / --skip-pi to run only one step.

Git must be able to access the repository (e.g. Git Credential Manager on Windows, Keychain on macOS, or your normal GitHub credentials).

Development installation

For development from a clone of this repository:

pnpm install
pnpm build
pnpm link --global
pi install /absolute/path/to/pi-config-sync

After any change to src/ or extensions/, run pnpm build and commit the updated dist/ so Git installs pick up the change.

Initial setup

Create an empty private GitHub repository for the configuration, then run:

pi-sync setup \
  --repo https://github.com/YOU/private-pi-config.git \
  --device macbook

On Windows PowerShell:

pi-sync setup --repo https://github.com/YOU/private-pi-config.git --device windows-desktop

The configuration clone is kept internally at <agent-dir>/.pi-sync/repo.

Manual editing without running Pi

Edit the normal live files. Do not need to edit the internal clone.

macOS/Linux:

code ~/.pi/agent/AGENTS.md
pi-sync diff
pi-sync sync

Windows PowerShell:

code "$HOME\.pi\agent\AGENTS.md"
pi-sync diff
pi-sync sync

You can also edit the private repository directly:

pi-sync repo --open
# edit common/, platforms/darwin/, or platforms/win32/
pi-sync sync

Remote changes made through GitHub are received with pi-sync sync.

Commands

pi-sync setup --repo <url> --device <name>
pi-sync status
pi-sync diff
pi-sync sync                    # default command
pi-sync repo [--open]
pi-sync resolve                 # list merge conflicts, read-only
pi-sync continue                # after resolving and staging conflicts
pi-sync doctor
pi-sync apply                   # apply clone without network operations
pi-sync install                 # install/repair global CLI + pi extension, then doctor

Use --agent-dir <path> to override the Pi directory or set PI_CODING_AGENT_DIR. Use repeated --include <relative-path> options for additional safe paths, such as models.json after ensuring it contains no literal credentials.

Inside Pi, the extension provides analogous commands:

/pi-sync setup <repo-url> [device-name]
/pi-sync
/pi-sync status
/pi-sync diff
/pi-sync resolve
/pi-sync continue
/pi-sync doctor
/pi-sync install
/pi-sync repo

The extension reloads Pi resources after a successful synchronization. Some global settings can still require restarting Pi.

Conflict handling

The tool never force-pushes, resets, or automatically chooses one side. On a merge conflict:

pi-sync resolve
pi-sync repo --open
# edit conflict markers and stage the resolved files with Git
pi-sync continue

The live Pi file remains unchanged until the merge succeeds. Existing files are backed up before remote deletions or explicit apply operations.

Development

pnpm typecheck
pnpm build
pnpm test:only
# or build + tests together
pnpm test

Version bumps are automatic on merge to main (conventional commits decide major/minor/patch) — see CONTRIBUTING.md.