goal-planner — Claude Code subagent: what it does, how to install
goal-planner — a GOAP planner subagent that turns a goal into an ordered set of actions and reworks the plan when a step fails.
no license ★ 850 updated 2026-10-26
.claude/agents/goal-planner.mdWhat goal-planner does
This subagent treats planning as a search problem. You give it the current state and the state you want; each action carries preconditions, effects and a price. An A* search then picks the sequence with the lowest total cost rather than the first one that happens to fit.
Scope is what separates the modes: run one action, plan inside a fixed set of actions, or roam across everything available and split a large objective into smaller ones. Once execution starts, results get compared against the expected state on an OODA loop and the route is recalculated on a mismatch. A step can be handed to code, to the model, or to a blend of both, and an action may name tool groups such as grep or a profiler plus a fallback for when they are missing.
What the search works on is preconditions you can verify and effects that show up in the state. Loose action definitions give you a plan built on guesswork. The agent file lives at .claude/agents/goal-planner.md.
What it helps with
- break a vague goal like getting an app production-ready into ordered steps
- spot which preconditions block a deploy before running it
- rebuild the plan when one step fails or returns something unexpected
- pick the cheapest route when several action sequences reach the goal
- tie each action to the tools it needs, with a fallback if they are absent
Example prompts for the agent
- Use the goal-planner subagent to map out a deploy plan with all its dependencies.
- Have goal-planner split “make the legacy module production-ready” into steps with checks.
- Ask goal-planner to replan after the test run fails.
How to install goal-planner
Manually: put the files in place
.claude/agents/goal-planner.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/goal-planner.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/goal-planner.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about goal-planner
How do I install goal-planner in Claude Code?
Copy the agent file to .claude/agents/goal-planner.md in your project.
What does goal-planner do?
It plans from a goal state, weighing actions by preconditions, effects and cost, then searches for the cheapest sequence with A*.
What makes its plans reliable?
Actions need preconditions that can be checked and effects that appear in the world state. That is what the search runs on.