> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-integrations-pi-package.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi

> Give the Pi coding agent native Stagehand browser tools registered directly by an extension.

The Pi integration gives a Pi agent native `run`, `snapshot`, and `screenshot` tools backed by one persistent Stagehand browser per Pi session. Pi ships without built-in MCP by design; extensions register tools directly, so this integration runs in process without an MCP server or bridge. The tool descriptions, runtime validators, and system prompt come from the shared facade contract, so the tools behave the same as the MCP-based integrations.

<Note>
  The extension uses Pi’s official [package format](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md). Browserbase must publish the first `@browserbasehq/pi` release before you can use the npm install below; use the source install below while testing an unreleased change.
</Note>

## Prerequisites

* Node.js 24 or newer
* A model-provider credential for Pi (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`)
* A current Google Chrome installation for local browser mode

## Quickstart

<Steps>
  <Step title="Install the Pi package">
    ```bash theme={null}
    pi install npm:@browserbasehq/pi
    ```

    Use `pi install -l npm:@browserbasehq/pi` to install only for the current project. Restart Pi after installing so it loads the extension.
  </Step>

  <Step title="Configure the Pi model">
    ```bash theme={null}
    export OPENAI_API_KEY="your-openai-api-key"
    ```

    Export `ANTHROPIC_API_KEY` instead to use an Anthropic model. This credential is for Pi's own model, not the browser.
  </Step>

  <Step title="Choose the browser">
    The extension defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise it uses local Chrome:

    ```bash theme={null}
    export STAGEHAND_BROWSER="browserbase"
    export BROWSERBASE_API_KEY="your-browserbase-api-key"
    ```
  </Step>

  <Step title="Run a browser task">
    ```bash theme={null}
    pi --no-session -p "Open https://example.com and report the page title." </dev/null
    ```
  </Step>
</Steps>

<Note>
  Print mode reads piped stdin, so redirect `</dev/null` when running a one-shot task. A user-level `pi install` makes the extension available to future sessions. For project-local installs, complete Pi’s project trust flow interactively before running headless.
</Note>

## Try the extension from source

For development before the first release, build and install the package from the repository. The build bundles the private facade so installed consumers do not depend on the monorepo.

```bash theme={null}
git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build --filter @browserbasehq/pi
pi install ./packages/integrations/pi
```

Use `pi list` to inspect installed packages, `pi update npm:@browserbasehq/pi` to update a published installation, and `pi remove npm:@browserbasehq/pi` to remove it.

## Configuration

| Variable                  | Purpose                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `OPENAI_API_KEY`          | Credential for Pi's own model.                                                                                         |
| `ANTHROPIC_API_KEY`       | Alternative credential for Pi's own model.                                                                             |
| `STAGEHAND_BROWSER`       | Select `local` or `browserbase`.                                                                                       |
| `BROWSERBASE_API_KEY`     | Required for Browserbase.                                                                                              |
| `BROWSERBASE_PROJECT_ID`  | Optional Browserbase project ID.                                                                                       |
| `STAGEHAND_MODEL_NAME`    | Optional. The facade tools are deterministic and do not call a Stagehand model today.                                  |
| `STAGEHAND_MODEL_API_KEY` | Optional credential for `STAGEHAND_MODEL_NAME`; the extension can infer a supported provider key from its environment. |

## Session lifecycle

The extension factory does not start a browser; factories also run in invocations that never start a session, such as `pi --list-models`. The browser launches lazily on the first tool call, relaunches if it closed, and closes on session shutdown. Shutdown awaits a still-pending launch before closing so it does not leak a racing launch.

`snapshot` and `run` return text content. `screenshot` returns real image content because Pi supports multimodal tool results.

<Warning>
  `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary).
</Warning>

<Card title="Pi integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/pi">
  Read the extension tool registrations and lazy browser lifecycle.
</Card>