Idea: Adopt pi as Org-Wide Terminal Coding Agent Harness

[don-petry]

Overview

pi (earendil-works/pi) is a free, MIT-licensed terminal coding agent harness by Mario Zechner. Rather than a sealed product, it is a composable platform: a thin wrapper around your LLM of choice (15+ providers) with file read/write/edit, bash execution, a TypeScript extension API, and a 2,800+ package ecosystem.

This complements our existing Copilot + Claude Code setup — not replaces it — by giving developers a local, hackable, model-agnostic coding agent with deep org customization.

---

Why It Fits petry-projects

Our Stack	pi Alignment
AGENTS.md in every repo	pi auto-loads AGENTS.md at startup — zero extra config
GitHub Copilot subscriptions	pi can reuse existing Copilot subscriptions as its LLM
Claude Code / Anthropic	pi can reuse Claude Pro/Max subscriptions or Anthropic API keys
TypeScript/Shell scripts	Extensions are plain TypeScript (no compile step)
Custom Copilot agents	pi skills are compatible with the Agent Skills standard (agentskills.io)
PR review automation	pi SDK/RPC mode can be embedded in Actions workflows

---

Proof-of-Concept Setup

1. Install

npm install -g @earendil-works/pi-coding-agent   # Node >=22.19

2. Project Context (.pi/SYSTEM.md per repo)

pi reads AGENTS.md automatically. Add .pi/SYSTEM.md for pi-specific instructions:

You are a coding assistant for petry-projects.
Follow org standards in AGENTS.md at all times.
Never modify .github/workflows/agent-shield.yml.
Run tests before committing. Use POSIX-compatible shell.

3. Shared Team Settings (.pi/settings.json committed to each repo)

{
  "packages": [
    "pi-lens",
    "pi-subagents",
    "pi-mcp-adapter"
  ]
}

pi auto-installs these for every team member on first run — standardizing the toolset across the org.

4. Org-Level Permission Gate Extension

A TypeScript extension enforcing org rules locally (distribute via .github-private):

pi.on("tool_call", async (event, ctx) => {
  // Block agent-shield from being modified
  const path: string = event.input.path ?? "";
  if ((event.toolName === "write" || event.toolName === "edit") && path.includes("agent-shield.yml")) {
    return { block: true, reason: "agent-shield.yml is protected per org standards" };
  }
  // Confirm before git push or gh pr create
  const cmd: string = event.input.command ?? "";
  if (event.toolName === "bash" && /git push|gh pr create/.test(cmd)) {
    const ok = await ctx.ui.confirm("Confirm", `Allow: ${cmd}?`);
    if (!ok) return { block: true, reason: "Blocked by user" };
  }
});

5. CI/Actions Integration (RPC mode)

pi's JSONL RPC mode drives it non-interactively from GitHub Actions:

- name: pi code review
  run: |
    pi --mode json -p "Review the diff in this PR for security issues, org standard violations, and bugs."

This could augment our existing pr-reviewer Copilot agent for local/offline scenarios or as a second opinion.

---

Comparison to Our Current Stack

	GitHub Copilot Agent	Claude Code	pi
Model choice	GitHub-hosted only	Claude only	15+ providers, BYOK
Runs where	GitHub.com / cloud	Local terminal	Local terminal
Extensible	Limited	Limited	Full TypeScript API
SDK/RPC for Actions	❌	❌	✅
Cost	$10–19/mo/user	BYOK	Free (BYOK)
AGENTS.md support	Via Copilot	✅	✅

Proposed role: pi fills the local developer terminal slot in our agentic stack — Copilot handles cloud/PR automation, Claude Code handles deep Anthropic-specific work, and pi handles day-to-day local sessions with full extensibility and model flexibility.

---

Suggested Next Steps

1. Pilot: 1–2 developers install pi and use it for a sprint alongside our existing AGENTS.md
2. Org extension: Build and share the org-guard.ts extension via .github-private
3. Shared .pi/settings.json: Standardize across 2–3 repos and measure adoption
4. Actions integration: Prototype pi RPC mode in one workflow vs. current pr-reviewer
5. Decision: Evaluate after pilot — adopt, expand, or park

---

Resources

• 🌐 pi.dev — official docs
• 📦 earendil-works/pi — source (MIT)
• 📦 pi.dev/packages — 2,800+ community packages
• 💬 Discord — community
• 📖 Agent Skills standard — cross-agent skill compatibility

[don-petry]

I would like to see research regarding the performance of this harness vs. Claude, Copilot, and other competitors.

The Idea should be renamed to consider other SWE agent harnesses and evaluate and select the best of breed.

[github-actions[bot]]

Enhancement: pi Agent Harness — Gap Analysis & Integration Criteria

Sharpened problem & goal
The proposal positions pi as a complementary local coding agent (not replacing Copilot + Claude Code) leveraging its multi-provider routing and TypeScript extension API. The key ambiguity: what specific capability gap does pi fill that Copilot + Claude Code cannot? Without identifying 2–3 concrete workflows where pi demonstrably outperforms the current setup, "adopt pi" risks adding a third tool that duplicates the first two. The proposal should sharpen to a gap analysis before recommending adoption.

Context
Relevant existing infrastructure:

• The claim that pi "auto-loads AGENTS.md" is a key adoption signal — but Claude Code already loads CLAUDE.md/AGENTS.md natively; verify pi's support is not README-aspirational before treating it as a differentiator
• scripts/lib/model-pricing.tsv + token_report.sh — if pi is adopted, its invocations should emit usage artifacts in the same format so the Token Cost Observatory (Discussion 💡 Token Cost Observatory with Pre-Agentic Optimization #332) covers multi-tool spend; this is a hard integration requirement, not optional
• frameworks/ — managed via git subtree (bmad-method, spec-kit, gsd); pi could follow the same subtree pattern for managed updates, or remain as a developer-installed binary — the governance model should be explicit
• Discussion Evaluate additional providers, models, and optimizations #631 (multi-vendor strategy) directly relates: pi's value is highest if the org actively wants model-agnostic routing; evaluate pi alongside, not separately from, that initiative

Maintenance signal to verify before recommending adoption: last commit date, open issue response time, and whether the project has a stable API or is pre-1.0.

Impact / Effort

• Impact: MEDIUM — highest value if there is a specific local-development workflow the current tools handle poorly (e.g., offline/air-gapped dev, cost-sensitive exploration on cheaper models); LOW if it duplicates existing tooling
• Effort: S — installing pi org-wide is trivial; the real effort is defining what workflows use it and ensuring usage tracking covers it

Suggested acceptance criteria

• A written gap analysis (docs/tools/pi-evaluation.md) identifies 2–3 specific use cases where pi outperforms the current Copilot + Claude Code setup with concrete examples — if no gaps are found, a "not recommended, because" conclusion is equally valid
• pi's AGENTS.md auto-loading is verified against an actual petry-projects repo (not just stated in the README) and any gaps or differences from Claude Code's behavior are documented
• If adopted, pi invocations emit token-usage artifacts compatible with token_report.sh so the Token Cost Observatory covers all tooling spend
• The org adoption decision explicitly addresses: developer-local only vs. CI-integrated, and the supply-chain/maintenance risk of an external binary dependency
• A 2-week pilot with at least 2 developers produces a usage report comparing pi vs. Copilot/Claude Code for the identified use cases before any org-wide rollout