{
  "guide": {
    "slug": "pi-dev",
    "title": "Pi.dev Guide",
    "subtitle": "A compact guide to Pi as a minimal, extensible terminal coding-agent harness.",
    "summary": "Pi is a local terminal coding-agent harness for developers who want to own and customize the harness itself: provider-neutral models, tree sessions, skills, extensions, packages, RPC, JSON event streams, and SDK embedding, with fewer built-in product workflows than Claude Code, Codex, Cursor, Copilot, Devin, or app builders.",
    "category": {
      "slug": "software",
      "name": "Software",
      "description": "Fact sheets for developer tools, AI systems, software platforms, and technical buying or adoption decisions."
    },
    "tags": [
      "ai-tools",
      "coding-agents",
      "agent-harnesses",
      "developer-tools"
    ],
    "version": "2026-05-03.2",
    "publishedAt": "2026-05-03",
    "updatedAt": "2026-05-03",
    "freshness": "Verified against Pi first-party docs/site, GitHub repo metadata, npm package metadata, and current alternative-tool docs on 2026-05-03. Re-check provider/model coverage, npm version, GitHub counts, and pricing before making adoption or vendor decisions.",
    "heroLabel": "AI coding tool guide",
    "vaultPath": "Research/Technology/Software Development/AI Tools/Pi.dev Guide.md",
    "r2JsonKey": "guides/pi-dev/2026-05-03.2.json",
    "thesisCards": [
      {
        "label": "The move",
        "title": "Own the harness.",
        "body": "Pi keeps the core small and puts workflow shape into extensions, skills, prompts, themes, packages, RPC, and SDK surfaces."
      },
      {
        "label": "The catch",
        "title": "You inherit the safety boundary.",
        "body": "Extensions and packages can run code with full system access, and core Pi intentionally avoids built-in permission popups."
      },
      {
        "label": "The choice",
        "title": "Harness, product, or app builder?",
        "body": "Pi competes most directly with terminal coding agents and agent SDKs, not with prompt-to-app builders."
      }
    ],
    "stats": [
      {
        "label": "Install",
        "value": "npm global",
        "detail": "@mariozechner/pi-coding-agent installs the pi CLI."
      },
      {
        "label": "Observed version",
        "value": "0.72.1",
        "detail": "npm metadata checked 2026-05-03."
      },
      {
        "label": "Modes",
        "value": "TUI + JSON/RPC/SDK",
        "detail": "Interactive, print, event stream, process protocol, and Node APIs."
      },
      {
        "label": "License",
        "value": "MIT",
        "detail": "Observed for pi-mono and the npm package."
      }
    ],
    "sections": [
      {
        "id": "bottom-line",
        "eyebrow": "Bottom line",
        "title": "Pi is for developers who want to customize the coding-agent harness itself.",
        "body": "Use Pi when the job is local agent work, harness experimentation, provider/model flexibility, and custom workflows. Use something else when the job is hosted delegation, IDE-native assistance, GitHub issue-to-PR automation, enterprise backlog execution, or prompt-to-app creation."
      },
      {
        "id": "snapshot",
        "eyebrow": "Snapshot",
        "title": "What Pi is",
        "table": {
          "columns": [
            "Axis",
            "Pi.dev snapshot"
          ],
          "rows": [
            [
              "Product shape",
              "Minimal terminal coding-agent harness plus reusable agent packages."
            ],
            [
              "Install",
              "npm install -g @mariozechner/pi-coding-agent; command is pi."
            ],
            [
              "Default tools",
              "read, write, edit, and bash; optional read-only grep, find, and ls."
            ],
            [
              "Modes",
              "Interactive TUI, print, JSON event stream, RPC, and Node/TypeScript SDK."
            ],
            [
              "Context system",
              "AGENTS.md / CLAUDE.md, SYSTEM.md, APPEND_SYSTEM.md, skills, prompt templates, and compaction."
            ],
            [
              "Extensibility",
              "TypeScript extensions, Agent Skills, prompt templates, themes, and Pi packages."
            ],
            [
              "Pricing",
              "No separate Pi SaaS price found; model costs depend on provider subscription or API-key usage."
            ]
          ]
        }
      },
      {
        "id": "feature-map",
        "eyebrow": "Feature map",
        "title": "The important primitives",
        "table": {
          "columns": [
            "Feature",
            "What it does",
            "Why it matters",
            "Caveat"
          ],
          "rows": [
            [
              "Minimal tool surface",
              "Starts with file read/write/edit plus shell execution.",
              "Easier to reason about than a giant preloaded tool belt.",
              "Powerful enough to damage a repo; use git checkpoints or containers."
            ],
            [
              "Provider switching",
              "Can use subscription logins or API keys across many providers.",
              "More backend-neutral than Claude-only or OpenAI-only tools.",
              "Provider/model lists are release-bound."
            ],
            [
              "Tree sessions",
              "Stores branchable JSONL session history.",
              "Lets you rewind, fork, resume, and inspect the agent's working history.",
              "Does not replace tests, commits, or review."
            ],
            [
              "Extensions",
              "TypeScript modules can add tools, commands, UI, events, providers, gates, sub-agents, MCP, and more.",
              "This is the real customization layer.",
              "Extensions are arbitrary code."
            ],
            [
              "Packages",
              "Bundle extensions, skills, prompts, and themes.",
              "Makes custom harness behavior portable.",
              "Third-party package quality and safety vary."
            ]
          ]
        }
      },
      {
        "id": "comparison-ladder",
        "eyebrow": "Upgrade / downgrade",
        "title": "Choose by product layer",
        "table": {
          "columns": [
            "Pick",
            "What you gain",
            "What you lose",
            "Choose it when"
          ],
          "rows": [
            [
              "Simpler: Aider",
              "Mature Git-first terminal pair programmer.",
              "Less of a general-purpose harness and package system.",
              "You mostly want pair programming and patch generation in a repo."
            ],
            [
              "Target: Pi",
              "Provider-neutral terminal harness, tree sessions, hackable extensions, skills, packages, RPC, and SDK.",
              "Less built-in polish around permissions, hosted delegation, IDE UI, and enterprise governance.",
              "You want to customize the agent harness itself."
            ],
            [
              "Lateral daily driver: Claude Code or Codex CLI",
              "More productized local coding-agent experience and strong first-party model integration.",
              "Less provider-neutral and less bring-your-own-harness than Pi.",
              "You want a polished local agent more than an extensible toolkit."
            ],
            [
              "GitHub-native: Copilot coding agent",
              "Issue/comment-to-PR workflow in GitHub with ephemeral Actions-backed environments.",
              "Not a local interactive harness.",
              "Your team already lives in GitHub issues and PRs."
            ],
            [
              "Enterprise/upmarket: Devin or OpenHands",
              "Managed or self-hostable software-agent workflows, cloud environments, integrations, and backlog delegation.",
              "More operational or vendor surface than Pi.",
              "You need organization-scale delegation, auditability, or cloud execution."
            ],
            [
              "Adjacent builders: Replit Agent, Lovable, Bolt, v0",
              "Prompt-to-app creation, previews, hosting/deploy flows, and nontechnical-user ergonomics.",
              "Less useful as a general existing-repo coding harness.",
              "The job is build this app more than operate this codebase."
            ]
          ]
        }
      },
      {
        "id": "decision-surface",
        "eyebrow": "Decision surface",
        "title": "What to use instead",
        "table": {
          "columns": [
            "If you want...",
            "Use"
          ],
          "rows": [
            [
              "A hackable local coding harness that can become your own agent workbench",
              "Pi"
            ],
            [
              "A small terminal pair programmer with fewer moving parts",
              "Aider"
            ],
            [
              "The most polished terminal coding agent tied to Anthropic",
              "Claude Code"
            ],
            [
              "OpenAI local/cloud coding with app, CLI, IDE, and automation surfaces",
              "Codex"
            ],
            [
              "AI inside your editor and background agents attached to that editor",
              "Cursor"
            ],
            [
              "GitHub issue-to-PR automation under GitHub controls",
              "Copilot coding agent"
            ],
            [
              "Managed autonomous engineering work for a team backlog",
              "Devin"
            ],
            [
              "Open-source agent infrastructure or self-hostable coding-agent platform",
              "OpenHands"
            ],
            [
              "A product/backend framework for agent endpoints",
              "Flue"
            ],
            [
              "A generated web/mobile app with hosting and previews",
              "Replit Agent, Lovable, Bolt, or v0"
            ]
          ]
        }
      },
      {
        "id": "edge-cases",
        "eyebrow": "Caveats",
        "title": "Where Pi can surprise you",
        "bullets": [
          "No built-in MCP, sub-agents, plan mode, permission popups, to-dos, or background bash by design.",
          "Third-party extensions and Pi packages should be treated like developer tooling with shell access.",
          "Provider/model coverage, npm version, and GitHub counts are volatile and should be refreshed before publishing.",
          "Pi is not an app builder or hosted delegation product by itself.",
          "Pricing is indirect through model subscriptions or API providers rather than a clearly published Pi SaaS plan."
        ]
      }
    ],
    "claims": [
      {
        "id": "pi-positioning",
        "claim": "Pi is a minimal terminal coding harness oriented around extensibility.",
        "sourceId": "pi-docs",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "Product positioning, not independent benchmark evidence.",
        "guideLocation": "Bottom line"
      },
      {
        "id": "pi-install",
        "claim": "Pi installs through @mariozechner/pi-coding-agent and exposes the pi CLI.",
        "sourceId": "pi-quickstart",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "Package version changes frequently.",
        "guideLocation": "Snapshot"
      },
      {
        "id": "pi-tools",
        "claim": "Pi's default tools are read, write, edit, and bash, with optional grep, find, and ls.",
        "sourceId": "pi-quickstart",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "Tools execute in the current workspace and can modify files.",
        "guideLocation": "Feature map"
      },
      {
        "id": "pi-modes",
        "claim": "Pi supports interactive, print, JSON event stream, RPC, and SDK usage.",
        "sourceId": "pi-usage",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "The homepage groups print and JSON together in its four-mode framing.",
        "guideLocation": "Snapshot"
      },
      {
        "id": "pi-sessions",
        "claim": "Pi sessions are JSONL tree histories under ~/.pi/agent/sessions/.",
        "sourceId": "pi-session-format",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "Session format can migrate across releases.",
        "guideLocation": "Feature map"
      },
      {
        "id": "pi-extensibility",
        "claim": "Pi extensions and packages can add custom tools, commands, UI, event hooks, providers, permission gates, sub-agents, MCP, prompts, skills, and themes.",
        "sourceId": "pi-extensions",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "Extensions and packages can run arbitrary code and require trust.",
        "guideLocation": "Feature map"
      },
      {
        "id": "pi-omissions",
        "claim": "Pi intentionally omits MCP, sub-agents, permission popups, plan mode, to-dos, and background bash from the core.",
        "sourceId": "pi-homepage",
        "evidenceType": "official",
        "confidence": "high",
        "caveat": "These workflows can be added through extensions or packages.",
        "guideLocation": "Caveats"
      },
      {
        "id": "pi-pricing",
        "claim": "No separate Pi SaaS pricing was found; model usage appears to depend on provider subscriptions or API keys.",
        "sourceId": "pi-providers",
        "evidenceType": "inference",
        "confidence": "medium",
        "caveat": "A future pricing page or commercial packaging could change this.",
        "guideLocation": "Snapshot"
      }
    ],
    "sources": [
      {
        "id": "pi-homepage",
        "title": "Pi homepage",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-docs",
        "title": "Pi documentation",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-quickstart",
        "title": "Pi quickstart",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/quickstart",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-usage",
        "title": "Using Pi",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/usage",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-providers",
        "title": "Pi providers",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/providers",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-session-format",
        "title": "Pi session format",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/session-format",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-extensions",
        "title": "Pi extensions",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/extensions",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-skills",
        "title": "Pi skills",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/skills",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-packages",
        "title": "Pi packages",
        "publisher": "Pi.dev",
        "url": "https://pi.dev/docs/latest/packages",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "pi-github",
        "title": "badlogic/pi-mono",
        "publisher": "GitHub",
        "url": "https://github.com/badlogic/pi-mono",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "aider-docs",
        "title": "Aider documentation",
        "publisher": "Aider",
        "url": "https://aider.chat/docs/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "claude-code-overview",
        "title": "Claude Code overview",
        "publisher": "Anthropic",
        "url": "https://docs.anthropic.com/en/docs/claude-code/overview",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "openai-codex",
        "title": "OpenAI Codex",
        "publisher": "OpenAI",
        "url": "https://openai.com/codex/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "openai-codex-cli",
        "title": "OpenAI Codex CLI getting started",
        "publisher": "OpenAI Help Center",
        "url": "https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "cursor-background-agents",
        "title": "Cursor background agents",
        "publisher": "Cursor",
        "url": "https://docs.cursor.com/en/background-agents",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "github-copilot-coding-agent",
        "title": "About assigning tasks to Copilot",
        "publisher": "GitHub Docs",
        "url": "https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "devin-docs",
        "title": "Devin documentation",
        "publisher": "Devin",
        "url": "https://docs.devin.ai/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "openhands-docs",
        "title": "OpenHands documentation",
        "publisher": "OpenHands",
        "url": "https://docs.openhands.dev/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "replit-agent-docs",
        "title": "Replit Agent",
        "publisher": "Replit Docs",
        "url": "https://docs.replit.com/core-concepts/agent",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "lovable-docs",
        "title": "Lovable documentation",
        "publisher": "Lovable",
        "url": "https://docs.lovable.dev/",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "bolt-docs",
        "title": "Bolt getting started",
        "publisher": "Bolt",
        "url": "https://support.bolt.new/building/getting-started",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      },
      {
        "id": "v0-docs",
        "title": "v0 documentation",
        "publisher": "v0",
        "url": "https://v0.dev/docs",
        "accessedAt": "2026-05-03",
        "sourceType": "official"
      }
    ],
    "revisions": [
      {
        "version": "2026-05-03.1",
        "date": "2026-05-03",
        "changes": [
          "Created and published the public guide package.",
          "Added comparison ladder across terminal agents, IDE agents, GitHub-native agents, enterprise agents, frameworks, and app builders.",
          "Added claim receipts and public source rows for Pi and comparison tools."
        ]
      }
    ]
  },
  "publicUrl": "https://fieldguides.co/g/pi-dev"
}