What is Mentu Recipes?

Mentu Recipes runs multi-step agent workflows defined as plain JSON files. Each step declares up front where it may write and what must be true when it finishes. The runner holds it to that: writes outside the declared boundary are quarantined instead of committed, declared artifacts are committed when the step closes, deterministic checks are recorded against the claim, and every run leaves a record on disk you can read afterwards.

Steps run against OpenAI, DeepSeek, the Claude and Codex CLIs, OpenAI-compatible endpoints, local model servers, or a local shell. Recipes are files, so they diff, review, and version like the rest of your code.

These docs cover mentu-recipes, the public runner. That is the whole of what you can install today.

The contract a step signs

A step makes its claims before it runs, and the runner checks them after.

Field	What it does	On failure
completion_keyword	The completion signal. The step is complete only if the keyword appears in its output.	step fails
expected_changes	The write boundary. Matching files are committed when the step closes.	writes outside it are quarantined as a patch, step is marked warn_bookkeeping
verify.commands	Shell assertions run from the step directory.	step fails
verify.file_absent	Asserts a path does not exist.	step fails
verify.git_clean_outside	Bounds writes without committing anything.	step fails
verify.grep_present / grep_absent	Asserts what a file must and must not say.	recorded, step is marked warn_bookkeeping, run continues

That last row is the one to know before you rely on it. A grep assertion that does not hold is recorded loudly and does not stop the run. Put an assertion that must stop a run in verify.commands.

What a run leaves behind

Each run writes a directory under .mentu/runs/<run-id>/: run.json, state.json, a baseline.json record of the git state the run started from, an events.jsonl event log, the captured stdout and stderr of every step, and a quarantine/ patch for any undeclared write. mentu-recipes report renders one run. mentu-recipes analyze-runs aggregates the workspace without reading prompt or output contents.

Because a run record is a normal file, resume and retry-step can pick a run back up: steps already marked success or warn_bookkeeping are skipped and incomplete branches run again.

Scope

This runner implements the recipe and step model, DAG scheduling with derived layers, declared write boundaries with quarantine of undeclared changes, deterministic verification, per-backend completion policy, retries and timeouts, resume and per-step retry, run records, local run analytics, and Keychain-backed credential resolution.

It does not implement an append-only hash-chained ledger, trust scoring, hash-gated recipe commitment, or per-step worktree isolation. Run records in this runner are plain JSON written per run: they are not chained, and nothing in this runner verifies them after the fact.

Cloud hooks are optional and off by default. Local execution never depends on them, and step output is sent only when a recipe sets "cloud": { "evaluate_steps": true }.

Next steps

• Quickstart: install, author a shell recipe, run it, read the record.
• Authoring a recipe: write boundaries, verification, and what doctor flags.
• Recipe schema: every field the runner reads.
• Patterns: sequence, parallel, and compound shapes.