Pi Config

Portable global configuration for the Pi coding agent, managed with Chezmoi.

Layout

The repository root is a Chezmoi source directory. .chezmoiroot points Chezmoi at chezmoi/, keeping development files out of the target state:

chezmoi/
├── .chezmoiignore
├── .chezmoiscripts/
│   └── run_onchange_after_install-nono-profile.sh.tmpl
├── .chezmoitemplates/
│   ├── custom-settings.yml
│   ├── keybindings.yml
│   └── nono-pi-profile.yml
├── dot_pi/agent/
│   ├── AGENTS.md
│   ├── PORTING.md
│   ├── keybindings.json.tmpl
│   └── packages/piconfig/
└── bin/executable_pi-sandbox

Chezmoi maps dot_pi/agent/ to ~/.pi/agent/ and bin/ to ~/bin/. Managed files are regular files, not Stow symlinks, so Pi can change its working copy without modifying this repository.

Installation

Install Chezmoi, Pi, and Bun first. From this repository, inspect and apply the source state with:

chezmoi --source "$PWD" diff
chezmoi --source "$PWD" apply

The compatibility command performs the same source-authoritative apply and also installs the local package dependencies and the declared shared skill: Use chezmoi diff before it if you want to review changes first.

make install

The old Stow deployment must be removed before the first Chezmoi apply. Set INSTALL_SKILLS=0 to skip the optional shared skill installation:

make install INSTALL_SKILLS=0

Chezmoi applies the custom settings through a modify_ source file. The version-controlled settings, keybindings, and nono profile are YAML, while Chezmoi renders the installed files as JSON. Existing machine-local settings are preserved, while the keys in .chezmoitemplates/custom-settings.yml take precedence. Authentication, trust data, sessions, model data, package caches, and other Pi runtime state are not source-controlled.

Useful compatibility targets are:

make install-pi      # Chezmoi apply, dependencies, and Pi package sync
make install-skills  # Shared skill installation
make sync-plugins    # Reconcile configured Pi packages
make sync-settings   # Reapply only the managed settings merge
make pull-config     # Merge installed JSON changes back into YAML sources
make uninstall       # Remove unchanged managed files; preserve local changes

Packages

The custom settings template declares:

• this repository's local extension package (./packages/piconfig), and
• pinned third-party Pi packages, including pi-service-tier and pi-subagents.

Pi's built-in MCP extension handles stdio and Streamable HTTP servers, so no separate MCP adapter package is needed. It reads user servers from ~/.pi/agent/mcp.json and project servers from .pi/mcp.json. Server configuration and credentials remain machine-local and are not tracked here.

Pi loads and manages package resources through these settings. make install runs pi update --extensions after applying them so package synchronization finishes before sandboxed sessions start. pi install is not a replacement for Chezmoi: it registers packages, but does not deploy the global context, keybindings, sandbox profile, or launcher.

Codex Flex processing

The pinned pi-service-tier package exposes flex for the built-in openai-codex provider. After installation, run /service-tier and select flex for OpenAI Codex, or persist the choice in ~/.pi/agent/service-tier.json:

{
  "openai-codex": "flex"
}

It injects service_tier: "flex" into Codex Responses requests; no tier is enabled until you select or configure one.

Permission commands

The permissions extension uses a small command blacklist. Ordinary commands, including commands that modify project files, run without prompts. Destructive and privileged commands are blocked; edit chezmoi/dot_pi/agent/packages/piconfig/permissions/policy.yml when an exception is needed.

For sandboxed sessions, use the launcher installed by Chezmoi:

~/bin/pi-sandbox

When nono is installed, the launcher runs the piconfig profile and grants read/write access to the current project and Pi/Bun resources, plus read access to ~/.lua. On macOS it also grants read-only access to /opt/homebrew in both the session and sandboxed git command, so Homebrew runtime libraries can load. It also allows Neovim's $XDG_CONFIG_HOME/nvim, $XDG_DATA_HOME/nvim, $XDG_STATE_HOME/nvim, and $XDG_CACHE_HOME/nvim directories for config, plugins, ShaDa, swap, and undo data. It also allows mise's configuration, cache, and installed runtimes. The sandboxed git command can read trusted global/system Git config files and their declared include targets. For GPG signing, it can connect to and bind only ~/.gnupg/S.keyboxd and ~/.gnupg/S.gpg-agent. Chezmoi installs the profile at $XDG_CONFIG_HOME/nono/profiles/piconfig.json (or ~/.config/nono/profiles/piconfig.json when XDG_CONFIG_HOME is unset), keeping the active policy outside the writable Pi state directory. Set NONO_PI_PROFILE to use another profile.

Without nono, the launcher warns and runs Pi normally.

Validation

make test

This runs the extension unit tests and an isolated-home Chezmoi installation test. The installation test verifies that managed files are regular executable files, the settings merge is preserved, the nono profile is installed in the XDG config directory, source changes overwrite managed copies on apply, and authentication, trust, session, and locally modified files survive uninstall.

State boundary

Git tracks only portable configuration, templates, scripts, and extension source. It does not track Pi authentication, sessions, trust decisions, models, package caches, or generated package dependencies. Pi may change the installed copies locally; use chezmoi diff before applying source changes and make pull-config to import changes from the YAML-backed JSON files. The pull command preserves unmanaged settings keys, updates managed settings from the installed copy, and rewrites the YAML representation. Use chezmoi re-add only for ordinary non-template files.