1. Plans: the execution engine
A plan is a YAML document listing steps, each a tool call whose inputs may reference earlier results:{{E0.teams.0.name}} is the template language — typed dataflow between steps, zero inference. Inference appears only where the plan puts it: a prompt tool step for a sub-task, and the finish — a solver report, structured JSON, or nothing.
Control flow lives in seven executor-intercepted steps: an exit gate ends the plan early with a success or error state, a decide step forks into one of two branches on the same gates — both gated logically (when on exit, if on decide) or by a cheap model judgment (infer) — a filter step partitions a list with that same gate evaluated per item (spelled where), and map/reduce steps run a body once per item of a list, collecting the results or folding them into one value. Two more reach outside the plan for what it cannot compute: an agent step runs a bounded tool-calling loop when which tool to call next depends on an earlier result, and an ask step puts a question to the person running the plan — declaring, in the plan, what to do when there is no person.
Plans run three ways: directly (graph plan run), as a tool anything else can invoke, or authored by the LLM planner inside plan_and_execute.
The key behavioral difference: human-authored plans never replan. If a step fails, you get a structured error — the plan you wrote is the plan that runs. plan_and_execute plans are LLM-authored, so defects there trigger a replan with the error fed back. Details in Errors & replanning.
2. One tool catalog
Everything a plan step or the agent can do is a tool, and every tool lives in one namespaced catalog:
This is what makes plans composable: authoring a plan adds a tool to the catalog, and a plan’s steps draw from that same catalog — including other plans. The composition rules and the commands for inspecting and invoking the catalog live in The tool catalog.
3. The shape cache
MCP tools rarely declare what their output looks like — but the planner needs to know, or it can’t write{{E0.teams.0.name}}. So graph learns: every successful tool call records an inferred schema and example of that tool’s output. The planner reads this cache at planning time, which means every probe and every chat turn makes plan_and_execute author better plans. See The shape cache.
4. The workbench
Plans have a dedicated review surface:graph workbench plan (alias graph wb plan), a dual-pane TUI. The chat agent drafts and edits the plan in a side pane while you inspect its steps, validate on every change, and run it under a debugger that pauses before each tool call — so you can trust a plan’s writes before you commit it. Details in Workbench.
5. The agent loop
graph ask and graph chat run a standard tool-calling loop over the catalog: your message goes to the model, tool calls execute (in parallel within a round), results feed back, and the loop continues until the model answers in text. Plans are just tools here — the agent calls plan__sprint_analysis the same way it calls linear__list_issues.
Use it to prototype: probe tools, sketch a workflow conversationally, seed the shape cache — then freeze what works into a plan for anything you’ll run twice.
6. Threads
Everyask and chat turn persists to a thread under the data directory — messages, tool calls, and results.
What an invocation costs
Running a plan directly (graph plan run) is one LLM call (the solver) or zero (output/silent plans), however many tool calls it makes. A chat turn that invokes a plan tool is exactly three:
- Agent — reads your message, decides to call
plan__project_status - Solver — inside the plan, synthesizes the report from the collected step results (streams dimmed to stderr as progress)
- Agent — reads the report and writes the final answer (stdout)