Pi Customization

Grounding

1. pi-mono/packages/coding-agent/docs/themes.md — theme JSON format (name, optional vars, required 51 colors tokens), locations (~/.pi/agent/themes/*.json, .pi/themes/*.json, packages, settings, CLI --theme), hot reload, color value formats.
2. pi-mono/packages/coding-agent/docs/keybindings.md — customization via ~/.pi/agent/keybindings.json, namespaced action IDs (tui.input.submit, tui.editor.cursorUp, app.interrupt, etc.), key format (modifier+key), full action tables.
3. pi-mono/packages/coding-agent/docs/prompt-templates.md — Markdown snippets invoked via /name, locations (~/.pi/agent/prompts/*.md, .pi/prompts/*.md, packages), positional arguments ($1, $2, $@, ${@:N}), YAML frontmatter with optional description.
4. pi-mono/packages/coding-agent/README.md — Context Files section for .pi/SYSTEM.md, ~/.pi/agent/SYSTEM.md, and APPEND_SYSTEM.md.
5. pi-mono/packages/coding-agent/docs/settings.md — the overall settings.json structure for tying these together.

Invariants

• Theme Format: Themes define name (required, unique), optional vars for reusable color aliases, and all 51 colors tokens. There is no type, ui, syntax, or borders top-level key — everything is under colors. Loaded from ~/.pi/agent/themes/*.json (global) and .pi/themes/*.json (project).
• Keybinding Config: Keybindings are configured in ~/.pi/agent/keybindings.json (not settings.json). IDs are namespaced: tui.input.submit (submit), tui.editor.cursorUp, app.interrupt, etc. Run /reload to apply changes without restarting.
• Prompt Template Arguments: Templates use $1, $2, $@, ${@:N} positional syntax — not {variable} or <include>. The filename (minus .md) becomes the /name command.
• System Prompt Override: Replace the default system prompt with .pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global). Use APPEND_SYSTEM.md to append instead of replace. Context files and skills are still appended after the override.

Workflows