Integrations

pi

Run pair on pi, skill discovery with no wiring, project trust in headless mode, and pi as a pair-cli run engine.

pi (@earendil-works/pi-coding-agent) is a harness: an environment configured to execute pair's process. It is also an engine pair-cli run can drive, which is what makes unattended delivery portable beyond Claude Code.

This page is the user-facing setup guide. The facts it describes are maintained once, in the agent-harness framework inside the Knowledge Base your agents read: that guide is the source of truth, this page is not a second copy of it. Run /pair-capability-setup-harness to have pair configure pi for you rather than doing it by hand.

Prerequisites

  • pi installed and authenticated (pi --help works), /pair-capability-setup-harness with $harness: pi proposes the install (or an update below 0.86.1) and runs it only on your yes, also on a machine where pair was installed long before pi
  • A pair-enabled project (pair-cli install completed, .pair/ exists)

Skill Discovery: Nothing to Wire

pi discovers .agents/skills/*/SKILL.md, walking up from the current directory to the git repository root, plus .pi/skills/ for the project and ~/.pi/agent/skills/ globally. pair install already distributes skills to .agents/skills/, so pair's skills are visible with no configuration.

To load another harness's skill directory verbatim, declare it in the project's .pi/settings.json:

{ "skills": ["../.claude/skills"] }

Project Context

pi loads one context file per directory, in this precedence: AGENTS.override.md > AGENTS.md > AGENTS.MD > CLAUDE.md > CLAUDE.MD. A repository carrying both AGENTS.md and CLAUDE.md never loads both from the same directory, AGENTS.md wins. Nothing to deduplicate, and no reduced-context variant needed.

A personal ~/.pi/agent/AGENTS.md is layered into every session on every project. Know it is there before debugging a session that behaves unexpectedly.

Headless Execution and Project Trust

pi -p "<prompt>" runs one shot non-interactively; pi --mode json emits a JSONL event stream (what pair-cli run reads).

A headless pi run silently ignores project-local resources of an untrusted project, including the project .agents/skills it would otherwise discover. Non-interactive modes never show the trust prompt, so trust must exist before the run. Prefer a per-directory decision in ~/.pi/agent/trust.json (pi's own /trust, or /pair-capability-setup-harness provisioning it for this project only).

Setting defaultProjectTrust: "always" globally trusts every project pi ever opens on that machine: a much larger blast radius, and only appropriate on a dedicated automation box.

pair-cli run never writes that trust store. If pi has no trust decision for the project, the run fails loudly and tells you how to provision it; --approve-project-trust lets you proceed anyway, knowing project-local resources may be ignored.

Driving pi with pair-cli run

# One iteration, resolution printed, nothing spawned
pair-cli run --engine pi --root 212 --dry-run
 
# Unattended within a narrow perimeter
pair-cli run --engine pi --root 212 --autonomous --max-iterations 3

pi has no permission prompts by design, so it cannot run with confirmations active. pair-cli run therefore requires --autonomous explicitly for pi rather than pretending confirmations exist, autonomy is a decision you take, not one the driver takes for you.

To make pi the project's default engine, declare it in pair.config.json:

{ "engine": { "id": "pi" } }

In-Session Cycle with pi-subagents

pi's base agent has no sub-agents. The third-party pi-subagents package adds them, and /pair-workflow-cycle uses it to drive a card from inside an interactive pi session: every stage runs as a subagent child, and a reuse transition revives the same stage agent instead of starting a new one.

  • Install on request only: ask /pair-capability-setup-harness ($harness: pi) for pi-subagents: it installs the pinned version (0.71.0), globally or project-local as you choose. A project-local package loads only once the project is trusted.
  • Started without it, the cycle proposes the install: on yes it installs and asks you to re-run; on no it stops (use pair-cli run --card N from a shell instead). It never installs on its own.
  • A different version is reported with an offer to align it; decline and the cycle proceeds, stating the version is unverified.
  • Tool shape is checked before every dispatch; a mismatch stops with an error naming the expected version.
  • Resume is rehydrated from the transcript: pi-subagents revives a stage as a new child that reads its previous session file. pair's bridge always tells it to read that file first, so the step does not depend on the model choosing to.
  • Resume stays in its session: a stage is resumed only inside the pi session that ran it. In a new pi session (or when pi cannot resume the child) the stage runs fresh, and the cycle says so.

What pi Does Not Support

  • MCP: by design (pi's own docs). A project whose tech/automation.md declares Requires: mcp is not fit for pi, and /pair-capability-setup-harness stops before writing any configuration rather than half-configuring it.
  • Sub-agents, permission popups, plan mode, background bash, intentionally absent from the base agent. Without pi-subagents (above), pi is driven per stage by an external process (pair-cli run, ADR-021 tier 2) rather than by an in-harness fan-out primitive.
  • A built-in sandbox: pi runs with your permissions. Isolation for unattended work (container, VM) is the operator's responsibility.

Verify It Works

pi -p "/pair-next"

Expected: pi reads AGENTS.md, finds the skills, and reports the next action. If it ignores the project's skills, check project trust first: that is the usual cause.

Previous

opencode

Next

Web and Cloud Environments

On this page