Skip to main content
A plan is a list of steps that run in order, the same way every time. Each step calls a tool, and the plan makes a model call only where a step asks for one. Agents call plans as tools, so work an agent repeats can run without a model choosing each call.

​
Plan files

A plan is a YAML file in ./.graph/plans/ or ~/.config/graph/plans/. It has an identifier, a description that tells agents when to call it, its steps, and a finish that says what it returns. Steps read the plan’s inputs as {{input.<field>}} and earlier results as {{<id>.<field>}}, in the template language. See Plan file for every field.

​
Steps

A step calls one of:
  • A catalog tool: builtin__*, user__*, or an MCP server’s <server>__*
  • Another plan, as plan__<identifier>
  • A named agent, as agent__<name>
  • A control step, which the plan runs itself
Model calls happen only in agent steps, model-backed tools such as builtin__infer, infer and decide conditions, and a solver finish.

​
How a plan ends

finish decides what a plan returns:
  • output returns a map of step results as JSON, with no model call.
  • solver has a model write the answer from the results.
  • silent returns nothing, for plans that only act.

​
Running plans

  • graph plan run <identifier> runs a plan from the terminal or a script.
  • Agents and other plans call it as plan__<identifier>.
  • graph mcp serve offers it to MCP clients as plan_<identifier>.
A failing step fails the run. graph doesn’t rewrite a plan you wrote to work around it.

​
Where plans live

graph reads ./.graph/plans/ before ~/.config/graph/plans/, and the first plan with an identifier wins, so a project plan replaces one in your home directory. A plan with a built-in plan’s identifier replaces the built-in. Commit ./.graph/plans/ to give your whole team the same plans.

​
Guides

Draft a plan in the workbench

Turn a goal into a working, saved plan.

Run a plan

Run a plan with inputs and use its result.

Debug a plan

Step through a run in the workbench.

Stop early with exit gates

End a plan when a condition holds.

Branch with route

Take different steps depending on the data.

Select items with filter

Keep only the items that matter.

Iterate with map and reduce

Run steps per item, or fold a list into one value.

Delegate a step to an agent

Hand a fuzzy task to an agent and get typed output back.

Ask for input mid-run

Pause a plan to ask a person a question.

Compose plans

Split a large plan into plans that call each other.

Handle failures

Tell why a run failed and choose how to respond.