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.

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.

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.

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.

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.

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.

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.

GoalBuddy can prepare safe parallel work; it does not run a parallel org chart or install arbitrary extension packs.

Use goalbuddy prompt docs/goals/<slug> to render a compact prompt for the active task without dumping the whole state file. The prompt includes a mandatory required_spawn_agent_type; Codex PMs should use that exact GoalBuddy agent (goal_scout, goal_worker, or goal_judge) instead of a generic role agent. 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 update

That updates both Codex and Claude Code.

GoalBuddy opens 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. When sharing a board in chat or docs, use a real Markdown link such as [Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/) so the URL is clickable. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.

Custom external integrations should be built as ordinary repo work with a concrete implementation plan, not installed from a GoalBuddy catalog.

See GoalBuddy 0.3.8: Board Hub Guardrails for the latest 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 docs/releases.

MIT