A simple operating loop for long /goal runs.
GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks, especially when the work branches into subgoals, parallel agents, and long-running verification.
It gives /goal a small local workspace: a charter, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
Run one command:
npx goalbuddyRestart Codex or Claude Code.
Then prepare a goal:
$goal-prep
In Claude Code, use:
/goal-prep
Goal Prep creates the board and prints the exact /goal command to run next. That is the whole path.
docs/goals/<your-goal>/
goal.md
state.yaml
notes/
subgoals/ # optional depth-1 child boards
goal.md says what you want.
state.yaml tracks the board.
notes/ keeps longer findings out of the main thread.
subgoals/ holds optional child boards when one parent task needs a bounded branch of work.
rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
Scout maps the repo.
Judge chooses the next bounded slice.
Worker changes code and leaves a receipt.
/goal keeps the loop honest until the original goal is actually done.
GoalBuddy keeps the model small:
state.yamlis the source of truth.- A board is a view of one
state.yaml. - The local hub is a switchboard for many boards.
- A subgoal is one depth-1
state.yamllinked from a parent task. - Settings are viewer preferences, not workflow state.
Use subgoals for bounded child work that belongs to a parent task. Use multiple local boards when parallel agents or separate goal runs are active at the same time. Keep the board open in light or dark mode while the work moves.
GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
Use goalbuddy prompt docs/goals/<slug> to render a compact prompt for the active task without dumping the whole state file. Use goalbuddy parallel-plan docs/goals/<slug> to inspect read-only or disjoint write-scope work that can be handed to native Codex or Claude Code agent flows. The command reports recommendations only; it does not mutate state or spawn agents.
When a new GoalBuddy version ships:
npx goalbuddy updateThat updates both Codex and Claude Code.
GoalBuddy can open a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
Multiple local boards reuse one readable goalbuddy.localhost hub with an in-header board switcher. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.
See GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode for the release notes.
- broad project improvements
- release prep
- bug hunts that need evidence
- refactors with verification steps
- anything too large for one prompt
GoalBuddy is MIT licensed and published on npm.
The implementation lives in this repo, but the happy path is intentionally tiny: install it, run Goal Prep, then let /goal work from the generated files.
For release process details, see RELEASE.md.
MIT
