goalbuddy

GoalBuddy

A simple operating loop for long goal runs.

GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks by giving each harness's execution command a finish line, a live work surface, and a proof loop.

It gives a goal run 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 command to run next. That is the whole path.

In Codex, native /goal runs the board. In Claude Code, GoalBuddy installs /goalbuddy so Claude's own /goal command remains untouched.

Cross-Harness Goals

Harnesses churn; repos persist. A GoalBuddy board lives in your repo as plain files, so the goal outlives whichever tool started it: begin a goal in Codex, resume it in Claude Code tomorrow, or the other way around, using the command for that harness.

npx goalbuddy resume

resume lists every live board in the repo with its status, active task, and both continuation commands: Codex /goal Follow docs/goals/<slug>/goal.md. and Claude Code /goalbuddy Follow docs/goals/<slug>/goal.md.. Receipts can record which harness performed each task, so the board's history survives the handoff intact.

Boards can also mix vendors within a single run — a Claude judge and a Codex worker on the same board:

npx goalbuddy dispatch docs/goals/<slug> --to codex

dispatch renders the active task's prompt, runs the target CLI headless (codex or claude-code), extracts the returned receipt, and verifies write scope mechanically with git: worker changes must stay inside the task's allowed_files, and read-only roles must change nothing. The dispatcher never edits the board — the PM records the receipt, stamped with the harness that earned it.

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.

The receipt and task-card format is specified in docs/spec/receipt-v1.md — harness-neutral, plain YAML, machine-validated.

Scout maps the repo.

Judge chooses the largest safe useful slice.

Worker completes the whole assigned slice and leaves a receipt.

The execution command 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.

Use goalbuddy prompt docs/goals/<slug> to render a compact prompt for the active task without dumping the whole state file. The prompt includes exact role identifiers for both harnesses: Codex uses required_spawn_agent_type (goal_scout, goal_worker, or goal_judge), while Claude Code uses required_claude_subagent_type (goal-scout, goal-worker, or goal-judge). PMs should use the exact GoalBuddy role instead of a generic 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.

Update

When a new GoalBuddy version ships:

npx goalbuddy update

That updates both Codex and Claude Code.

Live Boards

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.4.3: Restore Claude's Native /goal for the latest release notes.

Good For

• broad project improvements
• release prep
• bug hunts that need evidence
• refactors with verification steps
• anything too large for one prompt

For This Repo

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 use the printed Codex /goal or Claude Code /goalbuddy command.

For release process details, see docs/releases.

Star History

License

MIT