GoalBuddy
A simple operating loop for long /goal runs.
GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks by giving native /goal a finish line, a live work surface, and a proof loop.
It gives /goal a small local workspace: a charter, a goal oracle, 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.
Start Here
Run one command:
npx goalbuddy
Restart 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.
Codex Install Model
For Codex, the canonical install is the native plugin plus bundled agents:
~/.codex/plugins/cache/goalbuddy/goalbuddy/<version>/
~/.codex/agents/goal_judge.toml
~/.codex/agents/goal_scout.toml
~/.codex/agents/goal_worker.toml
The Codex plugin bundles $goal-prep; a clean Codex install should not need personal ~/.codex/skills/goalbuddy or ~/.codex/skills/goal-maker folders. Native Codex /goal is a separate OpenAI-gated feature. GoalBuddy prepares local boards and handoff prompts for it, but it does not enable or replace native /goal.
To verify a Codex install:
npx goalbuddy doctor --target codex --goal-ready
To remove GoalBuddy-owned Codex runtime surfaces:
npx goalbuddy reset --target codex
Native codex plugin remove goalbuddy@goalbuddy only removes the native plugin surface. GoalBuddy also owns the goal_*.toml agent files it installed, its Codex plugin cache, its marketplace entry, and old personal skill folders from earlier installs. Use goalbuddy reset --target codex when you want those GoalBuddy-owned files removed too.
What It Creates
docs/goals/<your-goal>/
goal.md
state.yaml
notes/
.goalbuddy-board/ # generated local board files
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.
How It Thinks
Intent -> Oracle -> Surface -> Loop -> Proof
The oracle is the observable signal that says whether the original owner outcome is actually true: a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision.
No oracle, no serious goal.
The local board is the default work surface. It is not an extension marketplace; it is the built-in view of the state.yaml truth.
Scout maps the repo.
Judge chooses the largest safe useful slice.
Worker completes the whole assigned slice and leaves a receipt.
/goal keeps the loop honest until a final Judge/PM audit maps receipts and verification back to the oracle and records the full outcome complete.
Slice Sizing
Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
GoalBuddy should not optimize for tiny safe tasks. It should optimize for the largest safe useful slice: a working screen, working API path, data pipeline step, backend vertical slice, real bug fix, or milestone review. The board warns when it sees safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome.
Goalmaxxed
GoalBuddy keeps the model small:
state.yaml is 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.yaml linked 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.
Execution Quality
GoalBuddy can prepare safe parallel work; it does not run a parallel org chart or install arbitrary extension packs.
