Installation & Quickstart

Get pi-config installed, configure your project, start the local daemons, and run your first agent workflow so you can automate repository tasks in under a minute.

Prerequisites

• Node.js (>= 22)
• Git installed and configured
• pi >= 1.4.0 (install with npm install -g @earendil-works/pi-coding-agent)
• uv (Python package manager)

Note: pi-config requires pi 1.4.0 or newer. On an older version, CLI/ACPX providers stay unregistered and pi warns on session start.

Quick Example

# Install everything non-interactively
uv run scripts/install.py --all

# Start a session, then in the chat:
# /pidash start
# /pidiff start
# /scout-and-plan Review the authentication module and propose a migration plan to JWT.

Step-by-Step Guide

1. Install pi-config and tooling

Install the pi package (no git clone needed):

pi install npm:pi-orchestrator-config
uv tool install myk-pi-tools

To get everything at once — the pi package, myk-pi-tools, prek, acpx, agent-browser, trail (@trailhq/trail-code), Playwright, and the git-excludes setup — run the interactive installer instead:

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

Follow the prompts to select packages. To skip prompts and install everything available:

uv run scripts/install.py --all   # from a pi-config checkout

Note: The installer exits if pi is missing. Install @earendil-works/pi-coding-agent globally first. Only myk-pi-tools and prek require uv; the other steps require Node.js.

When it finishes, start a session:

pi

2. Add project settings

Create .pi/pi-config-settings.jsonc in your repository root (.json also works; if both exist the .jsonc file wins):

{
  "commit_trailer": "Assisted-by",
  "dco": true,
  "dream_interval_hours": 3,
  "pidash_enable": true,
  "pidiff_enable": true,
  "cli_agents": ["claude", "cursor"]
}

Note: Project settings override global defaults for the current repository. See Configuration & Settings for the full option list.

Prefer not to hand-edit JSON? Open the settings TUI from any session and edit the same keys with arrows and search:

/pi-config-settings

3. Start the background daemons

Inside an active pi TUI session:

/pidash start
/pidiff start

• /pidash start launches the web dashboard (default http://localhost:19190).
• /pidiff start launches the per-project diff viewer on a free local port.

Check daemon state anytime:

/pidash status
/pidiff status

Tip: Open the dashboard URL from the status output to monitor sessions and background work. See Using the Web Dashboard.

4. Run your first workflow

/scout-and-plan Review the authentication module and propose a migration plan to JWT.

This chains a scout pass (find relevant code) into a planner pass (implementation plan) without writing changes yet. For creating and routing specialists, see Managing Custom Agents.

Advanced Usage

Install only what you need

The installer can also add .pi/ and .worktrees/ to your global git excludes file so local agent data is not committed.

Configure via environment variables

Skip the settings file when you prefer env vars. Resolution order:

1. .pi/pi-config-settings.jsonc (project; .json is the fallback name)
2. ~/.pi/pi-config-settings.jsonc (global; .json is the fallback name)
3. Environment variables (for example PI_DREAM_INTERVAL_HOURS=3, CLI_AGENTS=claude,cursor)
4. Built-in defaults

See Configuration & Settings for keys and env var names. For CLI utilities used by review and memory workflows, see myk_pi_tools CLI Reference.

Keep project data out of git

Tip: The installer Environment Setup step can configure these entries for you.

Troubleshooting

• "Cannot continue without pi": Install the coding agent globally (npm install -g @earendil-works/pi-coding-agent), confirm pi is on your PATH, then re-run the installer.
• "pi X is below minimum required version 1.4.0": Update pi with npm install -g @earendil-works/pi-coding-agent, then /reload or restart the session.
• Daemon fails to start: Confirm pidash_enable / pidiff_enable are not set to false. Run /pidash status or /pidiff status. For pidash failures, check ~/.pi/pidash-server.log.
• pidash says TUI-only: Start daemons from an interactive pi session, not a headless/CLI-only mode.
• Pre-commit / formatting failures: Run prek run --all-files to apply fixes, then retry the commit.

Related Pages

• Configuration & Settings
• Using the Web Dashboard
• Built-in Workflow Commands
• Creating Slash Commands
• myk_pi_tools CLI Reference