A Pi recipe captures the expertise behind a frontier-grade agent so the same workflow can be run, measured, and improved anywhere Pi runs. Install one from Git and customize it locally.

Overview

Recipes are Pi packages: folders with a package.json manifest containing a pi block, plus agent YAML files, prompts, skills, and optional TypeScript runtime extensions. The recipes CLI installs or registers recipes in a local store and ensures the Pi extension is installed before recipes are run. The Pi extension resolves an installed recipe into a local directory and wires those recipe files into the live Pi session at launch time.

package.json owns both recipe identity and Node dependency metadata. The top-level name, version, and description identify the recipe, while the pi block declares recipe resources such as agents, extensions, skills, and prompts.

Documentation

• Recipe Flow: quick user-facing guide to installing, customizing, creating, and publishing recipes.
• Recipe CLI: creating, installing, resolving, publishing, and removing recipes.
• Pi Recipe Extension: installing the Pi extension, launching recipes, agent selection, resources, subagents, and recipe extension loading.
• Recipe Evals: declaring and running Harbor offline eval suites with exact pins.

Package Exports

• @introspection-ai/pi-recipes: extension factory and recipe-loading helpers.
• @introspection-ai/pi-recipes/pi-extension: Pi extension entrypoint.
• @introspection-ai/pi-recipes/recipe-store: recipe install and resolution helpers.
• pi-recipe-check (Rust crate, crates/pi-recipe-check): the pure recipe validation engine behind the vendored recipe-check binary, embeddable by other hosts such as introspection-cli.

Quick Start

Install the recipe tooling:

npm install -g @introspection-ai/pi-recipes

The first recipes install ... run automatically installs the companion Pi extension with pi install npm:@introspection-ai/pi-recipes.

Create a local recipe:

recipes create ./my-recipe
recipes check ./my-recipe
recipes install ./my-recipe

Launch it with Pi:

pi --recipe my-recipe
pi --recipe my-recipe --agent agent

recipes create writes a starter package.json, SYSTEM.md, agents/agent.yaml, and recipe README. Edit those files as the recipe grows. Named variants are agents too:

name: agent-opus
from: agent
model:
  name: openrouter/anthropic/claude-opus-4.8

Install Recipes

Install public GitHub recipes:

recipes install github:owner/repo
recipes install github:owner/repo/path/to/recipe
recipes install github:owner/repo#v1.0.0

Install private recipes with normal Git authentication:

recipes install [email protected]:owner/private-recipe.git
GITHUB_TOKEN=... recipes install github:owner/private-recipe

No recipe registry is required. Publishing a recipe creates or updates a GitHub repository and pushes the local recipe:

recipes publish ./my-recipe --github owner/my-recipe --visibility private

Use --visibility public to submit the recipe's public GitHub metadata to the marketplace catalog after a successful push. Catalog submissions are best-effort; private publishes are not listed.

Customize an installed recipe into an editable local copy:

recipes customize pi-codex
recipes check pi-codex
pi --recipe pi-codex

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development setup (TypeScript and the Rust validator), commit conventions, and the release process.

License

Apache-2.0