# Local toolchain

The Recipes extension teaches Pi to load recipes; the Introspection CLI scaffolds, checks, and runs them.

## Prerequisites

- [Node.js 24+](https://nodejs.org/)

## Install and set up

Install the [Introspection CLI](/sdk/cli):

**pnpm:**

```bash
pnpm add --global @introspection-ai/cli
```

**Bun:**

```bash
bun add --global @introspection-ai/cli
```

**Yarn:**

```bash
yarn global add @introspection-ai/cli
```

**npm:**

```bash
npm install --global @introspection-ai/cli
```

Then set up the local toolchain:

```bash
introspection setup
```

Setup installs Pi with its official npm method when it is missing, accepts any
existing Pi at or above the Recipes minimum, installs the exact compatible
Recipes release, and leaves existing Pi installations user-owned. Pi continues
to work as the standalone `pi` command.

## Work with recipes

| Command | Use it to |
| --- | --- |
| `introspection init <name>` | Scaffold a runnable recipe from a template after `introspection setup` has prepared the toolchain. No account needed. |
| `introspection check` | Validate the repository's recipes locally with the same checks the cloud runs on push. |
| `introspection local` | Resolve a `.introspection/` runtime manifest and run its recipe in a Pi session. Add `--agent <name>` to pick another agent. Fully local: no login or cloud lookup. |
| `introspection dev` | Serve local recipe changes to a cloud development runtime. |

### Check a recipe

Use `introspection check` when you want to catch invalid manifests, missing
resources, agent composition errors, and invalid portable policy without
starting a Pi session, such as in CI or a pre-push hook. The same check runs as
a preflight inside `introspection local` and `introspection dev`, and in the
cloud on push.

It validates the package against itself, so it catches what the recipe can be
wrong about on its own: a malformed file, a missing required field, a skill or
agent referenced but not declared, a policy that cannot be satisfied. It cannot
check the package against anything outside it. A declared system capability is
checked for shape but not for existence, and an MCP server the recipe declares
passes without any endpoint configured for it. Both of those resolve against a
runtime image and an environment's [bindings](/platform/bindings), so they fail
later — at `introspection dev`, or when a deployed task starts. A clean check
means the package is sound, not that it will run.

```bash
introspection check
```

A successful check proves the package is structurally sound—not that the agent
behaves well, has working credentials, or is ready for production.

The 0.3 checker draws an explicit line between validated policy and transparent
provider data:

| The check verifies | The check preserves but cannot verify |
| --- | --- |
| Files and references resolve, inheritance is acyclic, and closed agent, MCP, and `session` policy has valid keys, types, enums, and ranges. | Credentials, endpoints, runtime capabilities, and MCP bindings exist in the target environment. |
| `ai.options` uses snake_case and does not claim host-owned credentials, clients, headers, hooks, networking, telemetry, or session identity. | A portable Pi request option is supported by the selected model or provider at request time. |
| OpenRouter, Anthropic, and Vercel AI Gateway provider payloads have the supported outer shape. | The meaning or live endpoint compatibility of opaque routing and context-management fields. |

For example, the checker preserves an OpenRouter `require_parameters` routing
value, but only OpenRouter can determine whether the actual request parameters
match a currently available endpoint. Use `introspection local` or
`introspection dev` with real bindings to prove that runtime boundary.

A common local loop is:

```bash
introspection init my-agent
introspection local --work-dir ./my-agent
```

`local` checks that the package is structurally valid before starting Pi.
Running representative cases in a fresh session proves that its behavior is
useful.

## How it works with Pi

The Recipes extension resolves the package—manifest, agents, skills, prompts,
extensions, and MCP policy—and configures the Pi session before the first
turn. From there you are holding Pi's own session: the same flags, tools, and
interactions as any other Pi run.

Use a fresh Pi session for final behavioral checks so existing conversation
context does not mask problems.

See the [Recipes documentation](https://pi.recipes/docs/running-locally) for
the complete local-run reference, and the
[SDK reference](https://pi.recipes/docs/sdk-reference) for embedding recipes
in your own host process.

Local toolchain

The Recipes extension teaches Pi to load recipes; the Introspection CLI scaffolds, checks, and runs them.

Prerequisites

Node.js 24+

Install and set up

Install the Introspection CLI:

pnpm


pnpm add --global @introspection-ai/cli

Bun


bun add --global @introspection-ai/cli

Yarn


yarn global add @introspection-ai/cli

npm


npm install --global @introspection-ai/cli

Then set up the local toolchain:


introspection setup

Setup installs Pi with its official npm method when it is missing, accepts any existing Pi at or above the Recipes minimum, installs the exact compatible Recipes release, and leaves existing Pi installations user-owned. Pi continues to work as the standalone pi command.

Work with recipes

Command	Use it to
`introspection init <name>`	Scaffold a runnable recipe from a template after `introspection setup` has prepared the toolchain. No account needed.
`introspection check`	Validate the repository’s recipes locally with the same checks the cloud runs on push.
`introspection local`	Resolve a `.introspection/` runtime manifest and run its recipe in a Pi session. Add `--agent <name>` to pick another agent. Fully local: no login or cloud lookup.
`introspection dev`	Serve local recipe changes to a cloud development runtime.

Check a recipe

Use introspection check when you want to catch invalid manifests, missing resources, agent composition errors, and invalid portable policy without starting a Pi session, such as in CI or a pre-push hook. The same check runs as a preflight inside introspection local and introspection dev, and in the cloud on push.

It validates the package against itself, so it catches what the recipe can be wrong about on its own: a malformed file, a missing required field, a skill or agent referenced but not declared, a policy that cannot be satisfied. It cannot check the package against anything outside it. A declared system capability is checked for shape but not for existence, and an MCP server the recipe declares passes without any endpoint configured for it. Both of those resolve against a runtime image and an environment’s bindings, so they fail later — at introspection dev, or when a deployed task starts. A clean check means the package is sound, not that it will run.


introspection check

A successful check proves the package is structurally sound—not that the agent behaves well, has working credentials, or is ready for production.

The 0.3 checker draws an explicit line between validated policy and transparent provider data:

The check verifies	The check preserves but cannot verify
Files and references resolve, inheritance is acyclic, and closed agent, MCP, and `session` policy has valid keys, types, enums, and ranges.	Credentials, endpoints, runtime capabilities, and MCP bindings exist in the target environment.
`ai.options` uses snake_case and does not claim host-owned credentials, clients, headers, hooks, networking, telemetry, or session identity.	A portable Pi request option is supported by the selected model or provider at request time.
OpenRouter, Anthropic, and Vercel AI Gateway provider payloads have the supported outer shape.	The meaning or live endpoint compatibility of opaque routing and context-management fields.

For example, the checker preserves an OpenRouter require_parameters routing value, but only OpenRouter can determine whether the actual request parameters match a currently available endpoint. Use introspection local or introspection dev with real bindings to prove that runtime boundary.

A common local loop is:


introspection init my-agent
introspection local --work-dir ./my-agent

local checks that the package is structurally valid before starting Pi. Running representative cases in a fresh session proves that its behavior is useful.

How it works with Pi

The Recipes extension resolves the package—manifest, agents, skills, prompts, extensions, and MCP policy—and configures the Pi session before the first turn. From there you are holding Pi’s own session: the same flags, tools, and interactions as any other Pi run.

Use a fresh Pi session for final behavioral checks so existing conversation context does not mask problems.

See the Recipes documentation for the complete local-run reference, and the SDK reference for embedding recipes in your own host process.