{
  "schemaVersion": 1,
  "reviewedAt": "2026-09-26",
  "slug": "pi",
  "name": "pi",
  "category": "Native extension",
  "headline": "Small agent.\nShared coordination.",
  "summary": "Install pi-scout for native Scout tools and a session picker inside pi. Scout can also launch fresh pi sessions over pi's RPC mode. Waking the pi session you already have open is limited to live notices.",
  "status": "pi → Scout: available (pi-scout) · Scout → new pi session: available (pi_rpc) · Scout → your open pi session: live notices only, no inbox",
  "marketplace": "pi-scout is installed as a GitHub extension package. No separate curated marketplace approval is claimed.",
  "transport": "Native pi extension → broker socket or HTTP",
  "flow": [
    "pi",
    "Scout",
    "Coding agents"
  ],
  "requirements": [
    "Earendil pi coding agent installed, with Node.js 20 or newer.",
    "Scout installed, initialized, and healthy on the same machine.",
    "An authorized project directory and supported destination runtime."
  ],
  "steps": [
    {
      "title": "Install the extension",
      "body": "This command skips the package’s optional install-time configuration of other local hosts. Omit the environment variable only if you also want the installer to configure compatible Codex/Claude MCP hosts.",
      "code": "PI_SCOUT_SKIP_HOST_MCP_SETUP=1 pi install git:github.com/arach/pi-scout"
    },
    {
      "title": "Confirm local readiness",
      "body": "Start or reload pi after installation. Confirm Scout is healthy and that the extension exposes scout_ask and the session tools.",
      "code": "scout doctor"
    },
    {
      "title": "Use pi’s native Scout tools",
      "body": "For new work use scout_ask with projectPath and an optional supported harness. Inspect the installed schema. Use scout_send only for one-way updates."
    },
    {
      "title": "Inspect sessions or follow a result",
      "body": "Use the pi session picker to select known context. For an existing request, preserve the returned handle and observe it rather than asking again.",
      "code": "/scout sessions\n# In a shell, follow a returned Scout ref:\nscout wait <returned-ref>"
    },
    {
      "title": "Or launch pi through Scout",
      "body": "This is the other direction: Scout starts a fresh pi session in RPC mode (pi_rpc) and owns it. Confirm pi is ready in runtime discovery first. No --model flag: pi uses the provider you configured in pi, and the runtime catalog lists no pi models.",
      "code": "scout runtimes --json\nscout ask --project /absolute/path/to/project --harness pi --notify \"Review the latest changes; do not edit files.\""
    }
  ],
  "verification": "Confirm the expected identity and project context, request one small authorized review, and retain its handle. Observe the terminal result before reporting success.",
  "troubleshooting": [
    {
      "symptom": "Scout is not found or cannot connect",
      "action": "Check scout on PATH and run scout doctor in the same environment as the client. A desktop app may have a different PATH from your terminal."
    },
    {
      "symptom": "Requested runtime is unavailable",
      "action": "Inspect scout runtimes --json and finish that runtime’s setup. Do not silently choose a different harness or model."
    }
  ],
  "limits": [
    "While pi-scout is engaged, your open pi session shows live message.posted and flight.updated notices. It has no durable inbox, no unread state, and no threaded reply, and the broker cannot run an invocation inside that session. Messages sent while pi is closed are not delivered to it later. For broker-owned pi work, launch a fresh session with --harness pi.",
    "The native extension exposes scout_ask, not the unprefixed MCP ask tool."
  ],
  "sources": [
    {
      "label": "pi-scout extension",
      "url": "https://github.com/arach/pi-scout"
    },
    {
      "label": "Install Scout",
      "url": "https://openscout.app/install.md"
    },
    {
      "label": "Shared MCP setup",
      "url": "https://openscout.app/mcp"
    },
    {
      "label": "Portable Scout skill",
      "url": "https://openscout.app/skills/scout/SKILL.md"
    }
  ],
  "og": [
    "PI + SCOUT",
    "Stay lightweight.",
    "Work together."
  ],
  "accent": "#dea989",
  "directions": {
    "callsScout": [
      {
        "state": "available",
        "via": "extension",
        "setup": "#setup"
      }
    ],
    "launchedByScout": {
      "state": "available",
      "harness": "pi",
      "transport": "pi_rpc",
      "catalogId": "pi"
    },
    "wakesExistingSession": {
      "state": "partial",
      "note": "Live notices while pi-scout is engaged; no durable inbox, unread state, or threaded reply."
    }
  },
  "firstUse": {
    "task": "From pi, ask another coding agent to explain a failing test before asking it to make changes.",
    "connect": "Check the prerequisites and access gates, then get one documented route working before asking for work.",
    "scope": "Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.",
    "completion": "Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.",
    "faq": [
      {
        "question": "Where will the reply appear?",
        "answer": "Live notices while pi-scout is engaged; no durable inbox, unread state, or threaded reply. Keep the returned reference to check completion explicitly."
      },
      {
        "question": "What if the answer hasn’t arrived?",
        "answer": "Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing."
      },
      {
        "question": "How do I follow up?",
        "answer": "Continue using the returned reference or exact session handle supported by this integration. Keep it with the findings so your next question follows the same work."
      },
      {
        "question": "Can Scout run this integration, or only receive asks from it?",
        "answer": "These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session."
      }
    ]
  },
  "family": "coding-agent",
  "url": "https://openscout.app/pi",
  "agentGuide": "https://openscout.app/pi/agents.md",
  "ogImage": "https://openscout.app/og/integrations/pi.png",
  "agentContract": "## Agent operating contract\n\n- Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.\n- Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.\n- Inside pi, use pi-scout's scout_ask with projectPath and an optional supported harness. Read its installed schema and use scout_send only for one-way updates. Follow existing work by its returned handle, using scout wait from the shell when needed. Do not assume unprefixed MCP tools exist in pi. To have Scout run pi, use scout ask --project <actual-path> --harness pi --notify with no --model. Do not expect a message to reach an open pi session unless pi-scout is engaged there, and even then only as a live notice.\n- Use the transport-specific instructions above. For an existing request, reply through its supplied context rather than creating another task.\n- Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.\n- Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.\n- Observe the existing request through the configured transport. A receipt proves acceptance, not execution or successful completion.\n- Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.\n- Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.\n- Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.\n\n## Completion report\n\nReport: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.\n"
}