Recipes are config-defined workflows that agents call by name. Define a multi-step operation once in your config, then any agent in any session can execute it with callmux_recipe_run and a single argument.
Think of them as team-wide shortcuts: encoding conventions ("bugs always get the bug label"), workflows ("triage means fetch both issues"), and pipelines ("search then analyze") into callable names.
Recipes live in the recipes section of your config file. Each recipe wraps one of the existing meta-tools (call, parallel, batch, or pipeline) and can substitute runtime arguments using { "$param": "name" } placeholders.
The simplest form: one tool call with fixed and dynamic arguments.
{
"recipes": {
"open_bug": {
"description": "Create a labeled bug issue",
"mode": "call",
"server": "github",
"tool": "create_issue",
"arguments": {
"title": { "$param": "title" },
"body": { "$param": "body" },
"labels": ["bug"]
}
}
}
}The agent calls it with:
{
"recipe": "open_bug",
"arguments": {
"title": "Crash on startup",
"body": "Steps to reproduce..."
}
}callmux expands it into create_issue with labels: ["bug"] baked in. The agent doesn't need to know which labels to use or which server to target.
Fire multiple independent calls at once:
{
"recipes": {
"triage_pair": {
"description": "Fetch two issues for comparison",
"mode": "parallel",
"calls": [
{ "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "first" } } },
{ "server": "github", "tool": "get_issue", "arguments": { "issue_number": { "$param": "second" } } }
]
}
}
}Same tool, many items:
{
"recipes": {
"label_bugs": {
"description": "Add bug label to multiple issues",
"mode": "batch",
"server": "github",
"tool": "update_issue",
"items": [
{ "arguments": { "issue_number": { "$param": "issue1" }, "labels": ["bug"] } },
{ "arguments": { "issue_number": { "$param": "issue2" }, "labels": ["bug"] } }
]
}
}
}Each step feeds into the next via inputMapping:
{
"recipes": {
"search_and_analyze": {
"description": "Search issues then analyze results",
"mode": "pipeline",
"steps": [
{ "tool": "search_issues", "arguments": { "query": { "$param": "query" } } },
{ "tool": "analyze", "arguments": {}, "inputMapping": { "data": "$json" } }
]
}
}
}Pipeline failures are intentionally recoverable. A failed or thrown step stops the chain and returns status: "failed", failedStep, and all completed step outputs up to the failing step. Steps with inputMapping also report mappedArguments for values that were sent and skippedMappings for expressions that could not be resolved, such as non-JSON previous output or a missing $json.field.path.
By default, unresolved mappings are skipped and the step still runs. For required IDs, file paths, repos, issue numbers, or mutation targets, set onMappingMissing: "fail" on the step:
{
"tool": "get_issue",
"inputMapping": { "issue_number": "$json.items.0.number" },
"onMappingMissing": "fail"
}With onMappingMissing: "fail", callmux stops before executing that step and returns status: "failed", failedStep, and the skipped mapping diagnostics.
| Mode | Wraps | Description |
|---|---|---|
call |
callmux_call |
Single tool call with param substitution |
parallel |
callmux_parallel |
Concurrent calls, results returned together |
batch |
callmux_batch |
Same tool, many items |
pipeline |
callmux_pipeline |
Chained steps with inputMapping |
Recipes may include timeoutMs and absolute cwd overrides at the recipe level, on individual calls, items, or steps. Per-call values win over the recipe-level value.
Recipe results inherit the wrapped meta-tool's recovery shape. Parallel and batch recipes return per-call or per-item results with status, succeeded, failed, and failedIndexes; pipeline recipes return completed step outputs, failedStep on failure, and mapping diagnostics.
Execute a named recipe:
{
"recipe": "open_bug",
"arguments": {
"title": "Crash on startup",
"body": "Steps to reproduce..."
}
}Preview what a recipe will do without executing downstream tools:
{
"recipe": "open_bug",
"arguments": {
"title": "Crash on startup",
"body": "Steps to reproduce..."
}
}Returns the expanded calls, cache-hit candidates, and any validation errors. Use this when testing new recipes or debugging $param substitution.
Use { "$param": "name" } as an entire JSON value to mark it for runtime substitution. The placeholder is replaced with the corresponding value from the arguments object passed to callmux_recipe_run.
Rules:
$parammust be the only key in the object.{ "$param": "x", "extra": true }is invalid- Missing params at runtime produce a clear error
- Params can substitute any JSON type: strings, numbers, booleans, arrays, objects
Encode team conventions. If every bug issue gets the same labels, repo, and assignee, that's a recipe. The agent only supplies the title and body.
Name for discoverability. Agents see recipe names in callmux_status. Use clear, action-oriented names: open_bug, triage_pair, search_and_analyze.
Add descriptions. The description field shows up in status output, helping agents pick the right recipe without trial-and-error.
Dry-run first. When building or modifying recipes, use callmux_recipe_dry_run to verify expansion before live execution.
Prefer recipes over agent instructions. Instead of telling each agent "when creating bugs, always add the bug label and assign to the triage team," define it once in a recipe. It's enforced at infrastructure level, works across all clients, and survives prompt changes.
- Config Reference - full config schema including recipes field
- Meta-Only Mode - recipes work in meta-only mode without changes