Step by step for new team members

Install with two commands

Requires Node.js 22.19.0 or newer. You do not need to install Pi Coding Agent first: piagent-setup installs the exact host version pinned by the current release. Run it inside the project directory. It installs the Pi package, initializes .pi/, installs the MCP baseline and subagents, and runs doctor. Use --no-mcp, --no-subagents, --no-herdr, or --global-only to omit optional parts.

npm install -g @piagent/platform
piagent-setup

Because setup runs from the installed package, the source written to .pi/settings.json is npm:@piagent/platform@<version>. It resolves consistently on teammate machines and can be committed.

If you use Herdr, install it first. piagent-setup installs the Herdr Pi integration when herdr is present on PATH. Otherwise it skips the integration with a warning; after installing Herdr, run piagent-setup --global-only.

brew install herdr                            # macOS
curl -fsSL https://herdr.dev/install.sh | sh  # macOS or Linux

The curl form executes a downloaded installer. For an auditable path, use brew or download from GitHub releases. Herdr stable supports macOS and Linux; Windows remains preview.

See the release and install policy for pinned rollout, updates, rollback, and the latest channel for personal machines.

Open the project repository

Start Pi from the repository directory. In a trusted repository, use the trusted-run wrapper only when controlled automation is needed.

cd /path/to/project
pi

For multiple parallel agents, run herdr instead of pi and assign one role per pane: implementation, read-only review, verification, or notes. Herdr coordinates terminals and sessions; it is not a security boundary. Gates remain in the Pi extension and OAuth still occurs in Pi. See the Herdr workflow.

Onboard context

Run this once in a new repository to record project context, verification matrices, and protected areas under .pi/. /onboard opens the menu and status; run launches the project-reading workflow.

/onboard
/onboard run

Select profile and technology

Use /profile setup for the interactive selector: choose the profile, then the technology by role. Full-stack setup selects frontend, backend, and database.

/profile setup
/profile tech setup fullstack

Select a permission mode

Use read-only for scouting, workspace-write for normal coding, and guarded full access for trusted automation.

/permission status
/permission workspace-write

Run a workflow

Use the command that matches the intent so the agent does not spend context rediscovering the process. Start a fresh session for context-heavy work.

/workflow task Implement the requested bounded change.
/workflow review current diff
/fresh task Implement the requested bounded change.

Verify before handoff

The final gate trusts only commands that actually ran, exited successfully, and matched the verification plan. After pinning or upgrading a version, run doctor in the project:

piagent-doctor

Platform maintainers also run npm run verify in the source repository. See CONTRIBUTING.

Uninstall when no longer needed

piagent-uninstall is a dry run by default. Add --apply to make changes because it edits Pi settings that other tools may also use. The default removes only the platform's Pi package; add-ons, the Pi host, and project state are opt-in.

piagent-uninstall
piagent-uninstall --apply

Add-ons, the Pi host, project state, and the global npm helper each have separate opt-in flags listed by piagent-uninstall --help. Removal follows packages registered in Pi settings, so registrations created by older releases are still found.