Build and run a recipe

A recipe is the right tool when the same visible sequence of agents and gates should run repeatedly on issues. You build it in Settings, launch it from an issue, and inspect each step in that issue's execution panel. If you are still deciding whether a recipe is the right shape, start with Choose how to orchestrate work.

This walkthrough creates a small implementation recipe: one agent receives an issue, makes the change, and opens a pull request.

Before you start

Create or choose an agent in Settings → Agents that is allowed to edit the repository. The recipe editor stores a reference to that agent configuration; it does not duplicate its prompt or permissions.

1. Create the recipe

  1. Open Settings → Recipes at the project scope.
  2. Choose New Recipe, leave Start blank selected, and choose Create. Use Copy of existing only when an existing graph is a useful starting point.
  3. Name it Implement and open PR and add a short description.
  4. Leave Hidden from the new-issue picker off so the recipe is available when starting issue work. Turn it on only when the recipe should remain runnable from Settings but should not appear in that picker.

The canvas begins with a Trigger node. Leave it set to Manual and Issue. Manual means a person launches it; Issue gives the run the selected issue and an isolated worktree.

2. Add the implementation agent

Select the Trigger and press N. The editor adds an Agent below it and connects the nodes. You can also press Tab and choose Agent, or drag from a Trigger output to empty canvas and choose the node type there.

Select the Agent and:

  1. Choose your implementation agent from the agent menu.
  2. Leave Branch set to New. This isolates the change and gives the PR node a branch to open.
  3. Rename the node to Implement if you want the execution panel to read more clearly.

The shortcut creates the control and context connections the agent needs. If you connect nodes manually, drag control out to control in so the agent runs after the trigger, and context out to context in so it receives the issue. Hold Shift while dragging when both nodes support both connections to add the pair together.

3. Add the pull request

Select the Agent, press Tab, and choose PR. The PR node has a built-in create-pr output contract requiring a title and body. The agent writes that structured result at the end of its work; the PR node opens the pull request from the agent's branch.

The finished canvas has three nodes:

Trigger → Implement → PR

Both Trigger → Implement and Implement → PR need a solid control connection and a dashed context connection. Select a node to reveal unconnected port labels. If a connection is wrong, select the edge and remove it, then drag between the matching ports again.

4. Validate and save

Resolve every warning shown above the canvas. For this recipe, check that:

  • the Trigger is present;
  • the Agent and PR each have incoming control flow;
  • the Agent has an agent selected;
  • control and context both reach the PR node.

Choose Save. A recipe also needs a non-empty name and at least one node. Scheduled recipes have an additional requirement: they must belong to a project.

The editor also supports Add node for Trigger, Agent, PR, Checkpoint, Condition, Artifact, Instruction, and any configured custom Action. Add those only when the work requires them; the three-node recipe above is complete as written.

5. Launch it on an issue

  1. Open an issue with a concrete change to make.
  2. In the launch composer, choose Implement and open PR.
  3. Review the implementation agent row. Choose a backend and model if the saved defaults are unavailable; reasoning effort, runtime options, runner, and branch target are optional launch-time choices.
  4. Choose Start.

If Start is disabled, read the message in the composer. It identifies missing agent, model, backend, runner, or branch information that must be resolved before launch.

6. Inspect the run

The issue opens its newest execution by default. In the execution panel:

  • open the Implement row to follow the transcript, tools, todos, and changed files;
  • inspect failed or blocked rows for the control that resumes or restarts them;
  • open the PR artifact when the agent finishes to review the title and body;
  • use Restart when you intentionally want a new execution of the saved recipe.

An execution keeps the recipe and agent settings it started with. Editing the source recipe affects later launches, not this run. Controls that edit an active execution change only that execution's copy.

Add a gate only when the work needs one

  • Use an Artifact when an agent must produce structured data for a later step. Define its fields and choose whether a person must confirm the output.
  • Use a Condition when one result should select between named paths.
  • Use a Checkpoint to run a command after an upstream step; exit code 0 continues and a non-zero exit blocks. It is not a human approval node.
  • Use an Instruction to add authored guidance to downstream context.
  • Use a custom Action for a configured programmatic operation. Pull requests use the dedicated PR node.

For portable YAML, node fields, and edge syntax, see Recipe file reference.