Pi Orchestrator Config

A pi package that implements an orchestrator pattern — the main agent delegates all work to specialist subagents.

📚 Full Documentation

What's Included

Extension: orchestrator

Single extension that provides:

Agents (26)

Prompt Templates

Inter-Agent Communication (coms)

Two systems for Pi agents to communicate with each other, activated on-demand via slash commands:

P2P Local (/coms) — Direct Unix socket communication between agents on the same machine. No server needed.

/coms start --name planner --purpose "Plans the work"
/coms stop
/coms status

Tools available once activated:

Forked from disler/pi-vs-claude-code coms extensions. We own these files — FIFO message queue, structured task delegation via coms protocol.

Installation

Docker (Recommended)

The recommended way to run pi-config is via the pre-built container image. It provides filesystem isolation, consistent tooling, and all dependencies pre-installed.

docker pull ghcr.io/myk-org/pi-config:latest

See the Docker section below for the full run command and shell alias.

Native (without Docker)

Run the interactive installer — it walks you through each component with multi-select checkboxes:

uv run https://raw.githubusercontent.com/myk-org/pi-config/main/scripts/install.py

Or if you already have the repo cloned:

uv run scripts/install.py

The installer covers:

• Pi Packages — pi-config, pi-vertex-claude, pi-web-access, myk-pi-tools, bun
• Python Tools — mcp-launchpad (mcpl), prek
• npm Packages — acpx, agent-browser
• Browser Automation — playwright + chromium
• Environment Setup — gitignore configuration

For non-interactive (CI) usage:

uv run scripts/install.py --all

Updating

Docker

docker pull ghcr.io/myk-org/pi-config:latest

The container runs pi update automatically on each start.

Native

pi update                          # Pi package
uv tool upgrade myk-pi-tools      # CLI tool

After updating, run /reload in pi or restart pi to pick up changes. Refresh the global agent package after acpx-provider / cli-provider / settings changes so ~/.pi is not a mixed checkout (see issue #651).

Usage

Automatic delegation

Just describe your task — the orchestrator routes to the right specialist:

Add retry logic to the HTTP client in src/api.py

Workflow prompts

/implement add Redis caching to the session store
/scout-and-plan refactor auth to support OAuth
/implement-and-review add input validation to API endpoints

Slash commands

/pr-review 42
/release --dry-run
/review-local main
/query-db stats

Direct subagent usage

Use python-expert to fix the type errors in src/models.py
Run scout and planner in a chain to analyze the auth module

Run agent with specific model:

# Discover available models
list_models(provider="litellm")

# Run agent with explicit model
subagent(agent="worker", task="...", model="litellm/claude-opus-4-6-1m")

# Parallel tasks with per-task models
subagent(tasks=[{agent: "worker", task: "...", model: "litellm/claude-opus-4-6-1m", cwd: "..."}])

Code Review Loop

After any code change, the orchestrator runs 6 agents in parallel (5 reviewers + test-automator):

1. code-reviewer-quality — Code quality & maintainability
2. code-reviewer-guidelines — Project guidelines adherence
3. code-reviewer-security — Bugs, logic errors, security
4. code-reviewer-docs — Documentation quality, completeness, accuracy
5. code-reviewer-spec — Code/PR/issue spec alignment
6. test-automator — Runs project tests (pytest, node tests, pre-commit)

When review_loop_enforcement is enabled, the loop stops once all reviewers approve with 0 findings and tests pass (tests_passed: true in pi-config-review-state.jsonl), OR after review_loop_max_cycles total cycles (default 3, valid integers 1-10; env: digit string "1"-"10" only (after trim)) — whichever comes first. Each cycle always completes fix/explain (5a) before the cap check; the cap only blocks re-dispatch (step 2 / all 6 agents, including test-automator), not responding to findings. At cap, report Not fixed (explained why not → outstanding) vs Fixed (verification blocked by the cap — cannot re-dispatch to confirm clean). Invalid values (including non-digit forms like "10.0" / "1e1") fall through to the next resolution layer / default 3. Disable the review loop via review_loop_enforcement: false, not via max_cycles. Commit blocking is code-enforced via isCommitAllowed: allows commit when isReviewClean (status: clean + tests_passed: true, or status: none), or when max cycles are exhausted (status is has_findings or clean, no pending reviewers, cycle >= review_loop_max_cycles — no tests_passed requirement). Review enforcement and dirty tracking are automatically skipped on chore/bump-version-<version> branches (e.g. chore/bump-version-4.2.1-1234567890, used by the release workflow).

Staged mode (--autorabbit/--autoqodo in /review-handler) shares one total review_loop_max_cycles budget across both its Spec Compliance and Code Quality stages — not a separate cap per stage.

Use /review-status to inspect the current review loop state. Pass a worktree path to check a specific worktree (e.g., /review-status .worktrees/issue-42).

Customization

Project Settings

Copy the example file to your project and customize:

cp pi-config-settings.example.jsonc .pi/pi-config-settings.json

Settings files support JSONC (JSON with // comments). See pi-config-settings.example.jsonc for all available settings with descriptions.

Resolution order: project file → global ~/.pi/pi-config-settings.json → env var → default.

See dev-docs/project-settings.md for the full settings table.

Reviewer Environment Variables

These are set automatically by the orchestrator when spawning reviewer agents:

Per-Project Resource Management

Use pi config -l to manage which resources (reviewers, skills, prompt templates) are enabled per-project:

pi config -l          # Open project-local resource config

Press Tab to switch between global and project-local views. This lets you disable specific reviewers or skills for a project without editing JSON files.

Override agents

Place a .md file with the same name frontmatter in ~/.pi/agent/agents/ (user) or .pi/agents/ (project) to override a bundled agent.

Priority: project > user > package (bundled).

Custom Rules

The orchestrator loads rules from three directories (later layers override same-filename entries):

To add a custom rule, create a .md file in the appropriate directory:

# User-level rule (applies to all projects)
mkdir -p ~/.pi/agent/rules
cat > ~/.pi/agent/rules/75-my-rule.md << 'EOF'
# My Rule

Your orchestrator instructions here.
EOF

# Project-level rule (applies to current project only)
mkdir -p .pi/rules
cat > .pi/rules/90-project-rule.md << 'EOF'
# Project Rule

Project-specific instructions.
EOF

Rules auto-load alphabetically. Same-filename entries are overridden (project > user > package). Missing directories are silently skipped.

Conditional assembly

Rules support settings/feature conditionals at prompt assembly (assembleRuleText in rule-placeholders.ts). Full syntax, truthiness, and assembly order: dev-docs/project-settings.md (Rules assembly).

Markers: {{IF:key}}…{{/IF}}, {{IFNOT:key}}…{{/IFNOT}}, comparisons {{IF:key==value}} / {{IF:key!=value}}. Whole-file frontmatter: requires_setting / requires. Conditionals run per file (no cross-file matching), then bodies are joined, then placeholders like {{REVIEW_LOOP_MAX_CYCLES}} are substituted.

Add project agents

Create .pi/agents/my-agent.md in your project with frontmatter:

---
name: my-agent
description: What this agent does
tools: read, write, edit, bash
---

Agent system prompt here.

Project agents included by default (agentScope defaults to "both").

Image Generation

The generate_image tool creates images from structured descriptions via Gemini API.

Configuration:

Set image_model in pi-config-settings.json or use PI_IMAGE_MODEL env var.

Usage: Ask naturally — "generate an image of a sunset" — or use structured params: subject, action, scene, composition, lighting, style, text, aspect_ratio.

In containers, images are auto-served via HTTP for browser preview.

Cache Miss Notices

Enable showCacheMissNotices in pi settings to see transcript notices on significant prompt-cache misses — useful for investigating unexpected token costs:

pi config              # Toggle showCacheMissNotices in settings UI

Defaults to false. Enable when debugging cost spikes from cache invalidation.

Docker (Sandboxed Execution)

Run pi inside a disposable container for filesystem isolation — the agent can only access your mounted project directory and pi settings. Everything else on the host is protected.

Why?

• Safety — Prevents accidental rm -rf, modifications outside the project, or unintended system changes
• Filesystem isolation — pi can only read/write the mounted project directory
• Consistent tooling — All required tools pre-installed in a single image
• Disposable — Container is destroyed after each session (--rm)

CLI provider binaries (optional cli_agents): The image installs the CLIs used by cli-* providers — claude (Claude Code), gemini (@google/gemini-cli), and agent (Cursor Agent CLI). Enable with cli_agents in settings (e.g. ["claude","cursor","gemini"]). Binary missing at load → cli-* not registered. After register, filterModels hides models when unavailable: PATH cleared while agent state remains, restore PATH; after session_shutdown (AgentState cleared and initialized reset) the next factory re-registers on /new|/resume|/fork (PATH alone is not enough). See dev-docs/cli-provider.md.

ACPX provider agents (optional acpx_agents): ACPX wraps CLI agents via the ACP runtime. Supported agents: cursor, claude, gemini. Enable with acpx_agents in settings (e.g. ["cursor","claude","gemini"]). Each ACPX agent requires the underlying CLI binary on PATH (agent for cursor, claude for claude, gemini for gemini) — missing binary → acpx-* not registered.

CLI specialist agents (Cursor / Claude / Gemini): On container start, entrypoint.sh symlinks package agents/*.md into the mounted project:

• .cursor/agents/
• .claude/agents/
• .gemini/agents/

Uses ln -sfn (safe if multiple pi-docker sessions share the same folder). Those three directories are added to the container global gitignore. Native installs do not auto- sync — copy or symlink yourself (see dev-docs/cli-provider.md).

Extension ops logs: cli-provider and dreaming write to ~/.pi/logs/ (not the chat UI). Fallback: $TMPDIR/pi-logs/. Details in dev-docs/cli-provider.md (Logging).

Pre-built image

docker pull ghcr.io/myk-org/pi-config:latest

Build from source (optional)

Note: The image is built for linux/amd64 only. On ARM hosts, build with --platform linux/amd64.

git clone https://github.com/myk-org/pi-config.git
cd pi-config
docker build -t ghcr.io/myk-org/pi-config:latest .

Run

docker run --rm -it \
  --name "pi-config-$(basename $PWD)-$(date +%s)" \
  --network host \
  --env-file /path/to/.env \
  -v "$PWD":"$PWD":rw \
  -v "$HOME/.pi":"$HOME/.pi":rw \
  -v "$HOME/.gitconfig":"$HOME/.gitconfig":ro \
  -v "$HOME/.gitignore-global":"$HOME/.gitignore-global":ro \
  -v "$HOME/.ssh":"$HOME/.ssh":ro \
  -v "$HOME/.config/gh":"$HOME/.config/gh":ro \
  -w "$PWD" \
  ghcr.io/myk-org/pi-config:latest

Environment file

Create a .env file with external service credentials and container-specific variables. Pi-config settings (image_model, acpx_agents, vertex_claude_1m, etc.) go in .pi/pi-config-settings.json — not here:

# Timezone (host timezone for correct timestamps) — plain value, no inline comment:
# `docker run --env-file` does not strip trailing comments.
TZ=America/New_York

# Host username (creates /home/<user> -> container home symlink so host paths resolve)
PI_HOST_USER=youruser

# Host UID/GID belong on the docker alias (see below), not hardcoded here:
#   -e PI_HOST_UID="$(id -u)" -e PI_HOST_GID="$(id -g)"
# The entrypoint remaps user `node` to those ids so bind-mounted 0600/0700
# files (~/.npmrc, ~/.ssh) are readable. IPA/LDAP users are not UID 1000.

# Google Cloud / Vertex AI
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-east5
GOOGLE_APPLICATION_CREDENTIALS=/home/youruser/.config/gcloud/application_default_credentials.json

# GitHub
GITHUB_TOKEN=ghp_xxx
GITHUB_API_TOKEN=ghp_xxx
GH_CONFIG_DIR=/home/youruser/.config/gh

# Gemini (optional — required for image generation)
GEMINI_API_KEY=xxx

# mcpl (MCP Launchpad) config path inside the container (must match mount target)
# Use your actual home path — it resolves inside the container via the PI_HOST_USER symlink
MCPL_CONFIG_FILES=/home/youruser/.config/mcpl/mcp.json

Pass via --env-file /path/to/.env in the docker run command.

Project memory

The memory system stores per-repo lessons and patterns in .pi/memory/topics/ as markdown files organized by category (lessons, preferences, patterns, decisions, completions, mistakes).

• Pinned — user-requested memories (via /remember), never auto-removed
• Learned — auto-extracted by dreaming, can be reorganized/removed

The .pi/memory/ directory is auto-added to the global gitignore in the container (along with .pi/, .worktrees/, .cursor/agents/, .claude/agents/, and .gemini/agents/).

For native (non-container) usage, add memory (and optionally CLI agent dirs) to your global gitignore:

echo '.pi/memory/' >> ~/.gitignore-global
# If you symlink pi agents for cli-cursor / cli-claude / cli-gemini:
echo '.cursor/agents/' >> ~/.gitignore-global
echo '.claude/agents/' >> ~/.gitignore-global
echo '.gemini/agents/' >> ~/.gitignore-global
git config --global core.excludesFile ~/.gitignore-global

Pidash — live web dashboard

Pidash is a web-based dashboard that runs alongside the TUI, accessible from any browser including mobile phones.

How it works:

• A daemon (pidash-server.ts) runs on port 19190 and aggregates all pi sessions
• Each interactive pi session's extension (pidash.ts) connects to the daemon and forwards events
• Oneshot (pi -p / --print / --mode json) skips pidash register, so no session connects
• The React web UI shows live conversations, tool calls, and session status

Features:

• Multi-session dashboard with sidebar grouped by project
• Live conversation streaming (user, assistant, tool, thinking)
• Send messages from browser to pi
• Model and thinking level switching from browser
• Extension commands (/release, /dream, /remember, etc.) work from browser
• Info bar: model, tokens, context %, git status (with PR #N when present)
• TUI status line: clickable pi-diff / pi-dash labels and open-PR #N hyperlink
• Per-project diff viewer (pidiff) — opens in browser via clickable pi-diff status-line link, powered by @pierre/diffs + @pierre/trees, with review comments
• Collapsible thinking and tool blocks with copy buttons
• ask_user tool bridging (answer from browser or TUI)
• Mobile responsive
• Event buffering for message replay on refresh
• Browser push notifications for background events (configurable per event type)
• Async agent live streaming (real-time tool calls and output inline in chat)
• Sidebar session working indicator (pulsing green dot when AI is active)
• [HH:MM] timestamps on all messages

Access:

# Automatically starts with pi — open in browser:
http://localhost:19190

# From other devices on your network:
http://<your-ip>:19190

# Custom port (or set pidash_port in pi-config-settings.json):
PI_PIDASH_PORT=9999 pi

# Disable pidash (or set pidash_enable: false in pi-config-settings.json):
PI_PIDASH_ENABLE=false pi

Oneshot (pi -p / --print / --mode json) skips register of pidash, pidiff, pitasks, and coms so those daemons/watchers do not start. CLI and ACPX providers still load. --mode rpc is long-lived and is not skipped.

Management:

/pidash status    # Check server status
/pidash stop      # Stop the daemon
/pidash start     # Start the daemon
/pidash restart   # Restart the daemon

Building the UI (first run only — auto-built):

cd extensions/pidash/pidash-ui
npm install && npm run build

Note: Session switching (/resume) and new sessions (/new) from the browser are not yet supported due to a pi API limitation. Use the TUI for these operations.

Pidiff — per-project diff viewer

Pidiff is a per-project diff viewer that opens in your browser, providing rich branch diffs with inline review comments.

How it works:

• Each interactive pi session spawns its own server (pidiff-server.ts) on a random free port
• Oneshot (pi -p / --print / --mode json) skips pidiff register, so no per-session server starts
• Container and native sessions get separate servers automatically
• Lockfiles in .pi/tmp/ track port and PID for each server
• The extension (pidiff.ts) connects to its session's server and registers its repo
• The React UI uses @pierre/diffs and @pierre/trees for a full-featured diff experience

Features:

• Branch diff and commit comparison
• File tree with search and filtering
• Inline review comments on specific lines
• Publish review comments back to the pi session
• Per-project isolation — no port conflicts between sessions
• Accessible via clickable pi-diff label in the status line (and from pidash)

Access:

# Open in browser (click `pi-diff` in the status line, or use the port):
http://localhost:<port>

# Disable pidiff (or set pidiff_enable: false in pi-config-settings.json):
PI_PIDIFF_ENABLE=false pi

Management:

/pidiff status    # Check server status
/pidiff stop      # Stop the server
/pidiff start     # Start the server
/pidiff restart   # Restart the server

Optional mounts

What's in the image

myk-pi-tools subcommands

What's protected

Filesystem isolation — the container cannot access anything outside the mounted volumes:

• ✅ $PWD (your project) — read/write
• ✅ ~/.pi (pi settings/sessions) — read/write
• ✅ Git, GitHub, SSH config — read-only
• ❌ Other directories on your host — not accessible
• ❌ Other git repos — not accessible
• ❌ System files — not accessible

Network — --network host shares the host network stack, so the container can reach any service your host can (LAN, localhost), and the host can reach services started inside the container. This is required for local MCP servers, LiteLLM proxy, and file preview (agents serve generated HTML/frontend files via HTTP for browser access). If your LLM provider is cloud-based, you don't use local MCPs, and you don't need file preview, you can omit --network host.

Shell alias

Add to your ~/.bashrc or ~/.zshrc:

alias pi-docker='docker pull ghcr.io/myk-org/pi-config:latest && \
  docker run --rm -it \
  --name "pi-config-$(basename $PWD)-$(date +%s)" \
  --network host \
  --env-file "$HOME/.pi/.env" \
  -e PI_HOST_UID="$(id -u)" \
  -e PI_HOST_GID="$(id -g)" \
  -v "$PWD":"$PWD":rw \
  -v "$HOME/.pi":"$HOME/.pi":rw \
  -v "$HOME/.gitconfig":"$HOME/.gitconfig":ro \
  -v "$HOME/.gitignore-global":"$HOME/.gitignore-global":ro \
  -v "$HOME/.ssh":"$HOME/.ssh":ro \
  -v "$HOME/.config/gh":"$HOME/.config/gh":ro \
  -v "$HOME/.config/mcpl/mcp.json":"$HOME/.config/mcpl/mcp.json":ro \ # adjust host path to your mcpl config location
  -v "$HOME/.agents":"$HOME/.agents":rw \
  -v "$HOME/.config/gcloud/application_default_credentials.json":"$HOME/.config/gcloud/application_default_credentials.json":ro \
  -v "$HOME/.config/cursor/auth.json":"$HOME/.config/cursor/auth.json":ro \
  -v "$HOME/.claude/credentials.json":"$HOME/.claude/credentials.json":ro \
  -v "$HOME/.config/glab-cli":"$HOME/.config/glab-cli":ro \
  -v "$HOME/screenshots":"$HOME/screenshots":ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  -w "$PWD" \
  ghcr.io/myk-org/pi-config:latest'

Then just run pi-docker from any project directory.

Startup note: The container runs as non-root user node. At start the entrypoint remaps node to PI_HOST_UID/PI_HOST_GID (pass $(id -u) / $(id -g) on the alias) so bind-mounted secrets match the host user. Without those env vars, node stays UID 1000 (breaks IPA/LDAP hosts). pi install runs on each start. A WARNING on stderr is normal when the package is already cached in ~/.pi. If pi misbehaves or the warning persists, verify network connectivity and run pi install git:github.com/myk-org/pi-config and pi install git:github.com/myk-org/pi-config/packages/pi-vertex-claude manually.

Discord Bot

Control your pi sessions from your phone via Discord DMs.

Setup

1. Create a Discord bot:

   • Go to Discord Developer Portal
   • Click "New Application" → name it (e.g., "pi-agent")
   • Go to "Bot" section → click "Reset Token" → copy the token
   • Enable "Message Content Intent" under "Privileged Gateway Intents"
   • Go to "OAuth2 > URL Generator" → select scope bot → select permissions: Send Messages, Read Message History, Add Reactions, View Channels
   • Open the generated URL → add bot to your server

2. Configure:

   # Create config file
   cat > ~/.pi/discord.env << EOF
   DISCORD_BOT_TOKEN=your-token-here
   DISCORD_ALLOWED_USERS=your-discord-user-id
   EOF
   

   Find your Discord user ID: Settings > Advanced > Developer Mode ON, then right-click yourself > Copy User ID.

3. Restart pidash: The Discord bot runs inside the pidash server daemon. Restart it to pick up the config:

   /pidash restart
   

Discord Commands

How It Works

The Discord bot runs inside the pidash server daemon (no separate process):

Discord app (phone) ↔ Discord cloud ↔ pidash server (localhost) ↔ pi sessions

No ports to open — the bot connects outbound to Discord’s API. The bot starts automatically with pidash when DISCORD_BOT_TOKEN is configured.

Development

See DEVELOPMENT.md for tips on testing extensions locally, running tests, and managing Python dependencies.

Prerequisites

• pi (minimum version: 0.84.0)
• gh CLI (for GitHub operations)
• uv (for Python execution)
• myk-pi-tools (optional, for /pr-review and /release)

Workspace Packages

pi-sidecar

A standalone HTTP sidecar wrapping the Pi SDK, living under packages/pi-sidecar/.

CLI commands: npx pi-sidecar (start server), npx pi-sidecar-start (background start/stop).

See packages/pi-sidecar/README.md for full documentation. See packages/pi-sidecar/CONSUMER-GUIDE.md for integration best practices.

pi-vertex-claude

Google Vertex AI Claude provider for Pi, living under packages/pi-vertex-claude/.

See packages/pi-vertex-claude/README.md for full documentation.

License

MIT