Skip to main content

Launch and Share Recipes

Using a recipe once it exists: launching from the empty-canvas launcher, a worktree, scratch or folder row, the toolbar launcher or the New Worktree dialog, running one across several worktrees at once, agent-initiated runs, sharing recipes with a team through the repository, and exporting or importing them.

Updated
Reviewed

The Empty-Canvas Launcher

When a worktree has no panels open in the grid, the canvas is not blank: it is a launcher. It is the same surface Terminals & Panels calls the empty grid; this page covers it from the recipe side. Under the project's name, branch and path, the sections stack down the column, each arriving 30 ms after the one above it so the surface reads as a sequence rather than a wall:

  1. Quick launch: the wide Search agents & panels… button that opens the panel palette, then a chip per agent you keep on the toolbar plus New terminal and Browse files, each showing its live keybinding where one is bound. Nothing conditional sits above it, so it never moves.
  2. Resume: a single line for the most recent resumable agent session, with a +N more entry into the searchable resume list when there is deeper history. It renders nothing at all when there is nothing to resume, so a genuine first run stays quiet. See Session Management.
  3. Recipes: the recipe runner described below, shown once the project's recipes have loaded.
  4. Project Pulse: the activity strip, when it is enabled. See Project Pulse.
  5. Tips: a rotating hint, shown only once you have launched an agent at least once.

While the Daintree tour is on offer, an invitation card closes the column. Switching projects re-enters nothing, since the sections were already mounted, so Daintree replays the entry animation by hand on a project switch. The whole sequence is suppressed under prefers-reduced-motion, Daintree's own reduce-animations toggle, and performance mode.

The launcher keeps quick actions, resume, recipes and Project pulse together while an agent runs in the dock.

Grid Mode and List Mode

With six or fewer recipes, the recipe section is a grid of cards: one column for a single recipe, two for two, and three for three or more, narrowing as the canvas does. Each card prints the recipe's name, its scope label and a summary of what it launches, and a shadowed one is dimmed and reads Runs team recipe. Pinned recipes come first. A Create new recipe… card closes the grid, and a Manage recipes button under it opens the Recipe Manager.

Past six recipes, the section switches to a compact list under a Recipes header with a Filter recipes… field and a Manage button. The field is not focused when the canvas appears, so it never steals the caret; Tab or a click reaches it. In list mode, recipes are grouped into three sections:

  • Pinned: recipes with Pin to canvas turned on
  • Recent: the five most recently used of the rest, newest first
  • All: remaining recipes in alphabetical order

Typing in the filter replaces the groups with ranked results: fuzzy matching on recipe names, weighted 70% by name relevance and 30% by how often and how recently you ran the recipe, with usage counting half as much after seven days. A list with a filter typed in stays a list even if it drops to six recipes or fewer.

Keyboard Shortcuts

KeyAction
↑ / ↓ (and ← / → in the grid)Move between recipes, wrapping through Create new recipe…
EnterRun the highlighted recipe, or open the editor when Create new recipe… is highlighted
EscapeClear the filter
F2 F2 F2 Edit the highlighted recipe (list mode, from the filter field)

Plugin recipes can't be edited, so F2 F2 F2 does nothing on one. Right-click a recipe for the other actions.

Status Banners

When you launch a recipe from the canvas, the runner can show a banner above the recipes reporting what happened. There are two.

The spawn-failure banner, an error banner, appears when one or more panels fail to start. It reads like "Started 2 of 3 terminals. 1 failed: Dev server." and offers a Retry failed action. Retry re-runs only the panels that failed. The panels that already started keep running, untouched.

The unresolved-variables banner, a warning banner, appears when a prompt variable couldn't be resolved, for example when no issue is linked. It reads "Missing context for {{issue_number}}" and explains that "These variables stayed empty in the launched commands." The check covers the agent panel's initial prompt.

Stale banners clear themselves on the next run, or when you switch worktrees.

Context Menu

Right-click a recipe card or row for Run, Edit, Duplicate, Pin to canvas (or Unpin from canvas), and Delete recipe…. A plugin recipe offers neither Edit nor Delete; duplicate it to get a copy you can change.

Before You Have Any Recipes

With no recipes saved, the section falls back to a create prompt, but it uses what it knows about the project first. If Daintree has detected run commands, up to two of them appear as suggestion pills, name on the left and command on the right, filtered to the ones that look like a dev, start, serve, test or build script. Clicking one runs it in a terminal. Only when nothing is detected does the line "Launch agents, dev servers, and terminals together with one click" stand alone. Either way, a Create your first recipe… button sits below.

The cap of two is deliberate: the empty state should be an obvious next click, not a catalog.

Past six recipes, the cards become a list with its own filter. These seven recipes are all pinned.

Other Ways to Run a Recipe

From a sidebar row

Open a worktree card's menu (the ⋯ button, or right-click the card) and choose Recipes. Under Run it lists every recipe available in that worktree, and picking one runs it there with the worktree's linked issue, pull request and branch as variables. While one recipe is starting, the others are disabled and marked Recipe running. The same submenu holds Save current layout as recipe….

A scratch workspace, or a project folder that is not a git repository, has no worktree card, but its row has the same kind of menu, from its ⋯ button or a right-click, with launch, open, copy and recipe actions. Its Recipes submenu lists the recipes that are not tied to a worktree and runs them in the folder itself. There is no branch or linked issue there, so only {{worktree_path}} fills in, and the row has no Save current layout entry.

From the toolbar

The toolbar's Launcher lists recipes in a Recipes group alongside agents and panels, and its search field ("Search agents, panels, and recipes") matches them by name and scope. Choosing one runs it in the active worktree. Hover a recipe row and use its pin control to put that recipe on the toolbar as a one-click button; the same control takes it off again. Deleting a recipe removes its toolbar button. With no recipes yet, the Launcher offers Create a recipe instead.

When creating a worktree

The Recipe field of the New Worktree dialog runs a recipe in the worktree as soon as it is created, and bulk creation runs one recipe on every worktree it creates. The field starts on your default worktree recipe and also offers Clone current layout. If the recipe fails, the worktree is still created and a notice offers Retry recipe.

Launching Across Worktrees

Terminal spawning is rate limited across the whole app: a burst of six, then one per second, so a flood of new PTYs cannot swamp the host. A recipe fanout would pay that toll once per terminal, which is why a recipe run does not queue as individual spawns.

Instead, every terminal in one recipe run shares a single spawn admission batch: one slot is claimed for the whole burst, and each terminal is admitted against it. Bulk worktree creation extends the same batch across worktrees, so creating worktrees for a list of issues and running the same recipe on each one cold-spawns as one bounded operation rather than one worktree at a time.

The batch is bounded, not unlimited. A batch admits at most 30 PTYs, and bulk creation chunks the work into as many batches as it needs rather than raising that ceiling. Each batch expires after 30 seconds, so a run that dies partway through cannot hold an admission slot open. Dev preview panels don't count against it, since they aren't PTYs.

Other limits apply to a single run. A recipe can define at most 10 panels. A run also respects the panel limits in Settings > Panel grid > Panel limits: when it would take the workspace past the confirmation threshold, Daintree asks before starting it, and at the hard limit it starts only what fits. Anything that does not start comes back as a reported failure, not a silent drop. To drive the agents once they are running, see Fleet.

Agent-Initiated Runs

The Daintree Assistant and MCP clients run recipes through two tools. An agent should call recipe.list first, wait for loading to finish (an empty list while it is still loading means "not read yet", not "none"), and use the returned recipe ID and origin rather than guessing an ID from a name.

recipe.run always asks for your confirmation, and the dialog lists the terminals the recipe will start. Approving it authorizes exactly that list:

  • An approved run starts every terminal the dialog showed.
  • A run pre-authorized by a standing automation grant, which shows nobody a preview, starts at most three terminals.
  • If the recipe changed between your approval and the run, nothing starts, and each terminal reports "Recipe changed since it was approved".

The result reports which panels started and which failed, with a reason for each. A panel starting successfully does not establish that the command or agent task finished successfully.

Team Recipes

Team recipes live in .daintree/recipes/ inside the repository and are committed to git, so everyone working on the project has them. Each recipe is saved as its own JSON file, named after the recipe in lowercase with spaces turned into hyphens. That keeps git diffs clean and minimizes merge conflicts. Every project recipe you create or import is written here.

Daintree loads any .daintree/recipes/*.json files when a project opens, and reloads them when its window regains focus, so a git pull in another terminal shows up when you come back. The focus reload waits while the recipe editor or the Recipe Manager is open. New team members get the shared recipes after pulling, with no extra step. Saving to the repository writes straight to .daintree/recipes/ and does not need the "Store settings in repository" toggle enabled first.

Saving a Recipe to the Repo

  1. Open the Recipe Manager (Shift-Command-P Control-Shift-P Control-Shift-P and search for "Manage recipes")
  2. On a Global, project or plugin recipe, open More actions (⋯) and choose Save as team recipe…
  3. Confirm with Save as team recipe. If a team recipe with the same name already exists, the dialog warns that saving will replace it. Daintree writes the recipe to .daintree/recipes/
  4. For a recipe you own, Daintree then asks whether to delete the original: choose Delete original or Keep both. Plugin contributions remain owned by the supplying plugin; the repository copy is independent

Environment Variable Handling

When a recipe is written to the repository, Daintree blanks every environment variable value and keeps the keys. That keeps secrets out of git. The keys stay behind as a signal to teammates about which environment variables they need to fill in locally. Daintree also refuses to save a recipe whose environment value looks like a credential in the first place; see importing recipes.

Warning
Environment variable values are blanked automatically when a recipe is written to the repository. The keys are kept so teammates know what to configure locally, but no secret values are written to the file.

Your local values are not lost. Daintree keeps a machine-local mirror of each in-repo recipe holding the values you filled in, and reconciles the two whenever the repository copy changes, so a pull that rewrites the shared file does not blank your environment or reset the recipe's usage history.

Committing Team Recipes

Daintree writes the recipe file. It does not commit it. You stage and commit the file yourself.

Tip
After saving a recipe to the repo, run git add .daintree/recipes/ && git commit to share it with your team. Daintree loads any .daintree/recipes/*.json files when a project is opened.

How recipe files are written

Every recipe write (a create, an edit, a delete, and the reconciliation pass that folds the repository's files back into your local store) goes through a single queue per project, one turn at a time. Each turn reads the state the previous turn left on disk. That closes the window where a reconcile and an edit could read the same snapshot and one of them silently win.

Reconciliation also refuses to guess. If .daintree/recipes/ is missing entirely (you checked out a commit that predates it), or if the directory could only be read in part, Daintree cannot tell a recipe a teammate deleted from one that simply doesn't exist on this branch. In that case it makes no filesystem changes at all and defers until the directory is readable again, so your local-only environment values and usage metadata survive a branch switch.

When a teammate edits the same recipe

If an in-repo recipe's file changed on disk between the moment Daintree loaded it and the moment you save (a git pull, a branch switch, a stash pop), the write is refused rather than applied. Your edit is rolled back in the UI and a dialog titled Recipe '<name>' changed on disk asks how to reconcile:

  • Reload from disk discards your in-flight edit and refreshes to match the file. This is the safer choice and the one the dialog leads with.
  • Overwrite recipe re-applies your edit on top, replacing the newer file content.
  • Cancel, or dismissing the dialog, leaves the rolled-back state in place, so you can look at the file and retry.

A second case uses the same dialog under the title Recipe '<name>' uses unsupported content: the file holds something this version of Daintree can't represent, most likely written by a newer build. Daintree read the recipe without those parts, so saving would delete them from the file. Reload from disk keeps the file as it is; Overwrite and discard saves your edit and drops the unsupported parts. Reconciliation applies the same caution: it never promotes a local recipe over such a file.

A related case is a filename collision: two recipes whose names reduce to the same file name. Only one can own the file. The other stays project-local rather than being dropped, and a low-priority Recipe name conflict notification names it so you can rename one.

Export and Import

Exporting Recipes

The Recipe Manager's More actions menu exports a recipe two ways:

  • Copy as JSON copies the recipe to the clipboard. A brief "Copied" flash confirms it.
  • Export to file… opens a save dialog to write a .json file to disk.

Both leave out the internal project id, the shadowing marker and any plugin origin, so re-importing a plugin recipe produces a plain recipe you own. Settings > Project > Recipes also has a Copy as JSON button on each row.

Importing Recipes

The Recipe Manager's Import menu has two options:

  • Import from clipboard… opens a dialog with an Import as selector (Project or Global) and a text area for pasting JSON.
  • Import from file… opens a file picker for .json files and imports into the current project.

Invalid panels are dropped rather than failing the whole import; see Create and edit for exactly what validation checks.