Author a recipe locally

Recipe authoring runs on the Introspection CLI, which prepares Pi and the Recipes toolchain and then wraps them in a few local commands. Install the CLI and run introspection setup first — see CLI → Set up the local toolchain.

The loop

Authoring a recipe is a short cycle you repeat until the behavior is right:

1. Start from a template. introspection init my-agent scaffolds a runnable recipe, its runtime manifest, and a git repository. No account is needed. (--template selects another template from the catalog.)
2. Edit the source. Agent YAML, SYSTEM.md, skills, extensions, MCP policy — everything is ordinary files under the recipe directory.
3. Check it. introspection check validates the package structurally, with the same checks the cloud runs on push.
4. Run it. introspection local starts the recipe in a Pi session on your machine — no login, no cloud lookup. Add --agent <name> to pick a non-default agent, or -p "<prompt>" to run one prompt and exit.
5. Iterate. Use a fresh session for final behavioral checks so existing conversation context does not mask problems.

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

When the local behavior holds up, introspection dev connects the recipe to a cloud development runtime so hosted chats pick up your uncommitted edits live — see CLI → Cloud-connected development.

The commands

introspection skills prints the manifest-defined Introspection workflows for coding agents — see CLI → skills. Everything else — setup, doctor, eval, and the authenticated resource commands — is in the CLI command map.

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

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

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.

How it works with Pi

The Recipes extension for Pi 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.

Once the recipe deploys, the platform uses the registered recipe path — the recipe directory recorded when the runtime was created (see CLI → runtimes) — at a pinned commit. What is packaged from that path is covered in Packaging a recipe.

See the Recipes documentation  for the complete local-run reference, and Embedding recipes for running a recipe from your own host process.