Skip to content

Latest commit

 

History

History
203 lines (150 loc) · 6.5 KB

recipes.md

File metadata and controls

203 lines (150 loc) · 6.5 KB

< Back to README

Recipes

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.


Defining Recipes

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.

Call Recipe (Single Tool)

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.

Parallel Recipe (Concurrent Fetches)

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" } } }
      ]
    }
  }
}

Batch Recipe (Bulk Operations)

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"] } }
      ]
    }
  }
}

Pipeline Recipe (Chained Steps)

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.


Recipe Modes

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.


Running Recipes

callmux_recipe_run

Execute a named recipe:

{
  "recipe": "open_bug",
  "arguments": {
    "title": "Crash on startup",
    "body": "Steps to reproduce..."
  }
}

callmux_recipe_dry_run

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.


The $param Placeholder

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:

  • $param must 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

Designing Good Recipes

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.


See Also