/Recipes
Docs

Overview

A recipe is a portable agent-system package. Pi Recipes is the open format and toolchain for creating, validating, running, and distributing those packages. Introspection is the first-party managed cloud for operating and improving them.

Choose a path

  • Create a focused recipe from scratch.
  • Customize a catalog recipe into source you own.
  • Compose shared instructions, specialized agents, skills, and extensions.
  • Declare capabilities with optional portable endpoint metadata while keeping environment-specific bindings and credentials outside the package.
  • Validate, run locally, then distribute a commit-pinned Git source.

For agents

Use llms.txt to discover the documentation and catalog.json for the stable machine-readable recipe catalog and installation metadata.

Why recipes

A one-off session captures one run. A recipe keeps the system behind it: agent definitions, instructions, model profiles, skills, tools, runtime extensions, connection policies, judges, and pinned evaluation suites.

The recipe owns portable intent, including policy and any portable endpoint declarations. The runtime supplies model credentials, secrets, environment-specific endpoint bindings or overrides, isolation, persistence, and execution lifecycle. This boundary lets the same recipe run locally or in a compatible host on infrastructure you choose. Suitability for Fly.io, Vercel, or a private cluster depends on that host's adapter and runtime requirements; Pi Recipes ships no provider adapter.

What the format covers

  • Agent: instructions, agents, model profiles, skills, prompts, tools, subagents, and TypeScript runtime extensions.
  • Capabilities: required connection identities, fail-closed MCP server and tool policies, and optional portable endpoint metadata. The runtime supplies secrets and environment-specific bindings or overrides.
  • Quality: portable judge definitions and exactly pinned Harbor evaluation suites that travel with the recipe version.

Install the recipe tooling

Install Pi first and confirm pi is on PATH. Pi Recipes extends the harness; it does not install Pi itself.

Pi Recipes currently requires Node.js 24 or later.

Install the recipe CLI once. The companion Pi extension is set up separately when first needed.

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

The first recipes install run installs the Pi extension if it is missing. You can also run setup explicitly:

recipes setup

Install and run a recipe

Install a verified recipe tag from GitHub, then launch Pi with that recipe active.

recipes install introspection-recipes/pi-codex#0.1.1
recipes list
pi --recipe pi-codex

Browse the catalog to find recipes. Use Recipe CLI for the full command reference, or Customize when you want to fork an installed recipe and make it yours, or Distribute to publish an interoperable Git-backed recipe.

What a recipe contains

package.json carries package metadata and a pi block that declares the resources and policies Pi should load:

{
  "name": "my-recipe",
  "version": "0.1.0",
  "description": "The agent recipe for this workflow.",
  "type": "module",
  "pi": {
    "agents": ["agents/*.yaml"],
    "extensions": ["extensions/*.ts"],
    "skills": ["skills/**/SKILL.md"],
    "mcp": {
      "servers": [
        {
          "id": "contacts",
          "required": true,
          "tools": { "include": ["search_contacts"] }
        }
      ]
    },
    "evals": {
      "suites": [
        {
          "name": "smoke",
          "type": "registry",
          "dataset": "acme/agent-smoke",
          "version": "1.0.0"
        }
      ]
    }
  }
}

Authored judges live under judges/. A referenced MCP manifest may carry portable endpoint metadata; environment-specific endpoints and credentials stay in a local ignored file or host binding. In either case, capability policy remains separate from connectivity.

The manifest version is optional package/display metadata. In the public catalog, the separate version field is the verified Git install ref used to build the install command. A reproducible release uses a commit SHA or a tag protected by an immutable-release policy. See Reference for the canonical specification and managed-host boundary.

Keep the folder in Git. Each commit is a reviewable version of the complete agent system, and anyone with access to the repository can install and run that same recipe.