GoalBuddy gives Codex and Claude Code a finish line, a board, and a proof loop

The problem GoalBuddy attacks

Long coding sessions with agents drift. The plan from turn one is gone by turn twenty, context compacts, and the model reinvents the goal every time it loses the thread. GoalBuddy, an MIT-licensed npm package from tolimarchuk, is built against exactly that failure. It gives each harness execution command a finish line, a live work surface, and a proof loop, so a run can pause, resume, and verify without re-inventing the plan every turn.

The mechanics are deliberately boring. A goal run gets a small local workspace: a charter, a goal oracle, a board, notes, receipts, and a clear next task. The work stays in your repo as plain files, which turns out to be the load-bearing decision of the whole design.

One command to start

Installation and first goal both run through a single entry point:

npx goalbuddy

After it installs, restart Codex or Claude Code, then prepare a goal. In Codex the command is $goal-prep; in Claude Code it is /goal-prep. Goal Prep creates the board and prints the exact command to run next, which is the entire onboarding path. From there, native /goal runs the board in Codex, while Claude Code gets a /goalbuddy command so Claude's own /goal stays untouched.

The doctor subcommand verifies an install, and the reset subcommand removes GoalBuddy-owned runtime surfaces when you want them gone, including the goal_judge, goal_scout, and goal_worker agent files it installed for Codex.

Boards that outlive tools

The README states the thesis in five words: harnesses churn; repos persist. Because a GoalBuddy board is plain files under docs/goals/, a goal outlives whichever tool started it. Begin a goal in Codex today, resume it in Claude Code tomorrow, or the reverse, using the continuation command for whichever harness is at hand.

npx goalbuddy resume

resume lists every live board in the repo with its status and active task, and prints both continuation commands. Receipts record which harness performed each task, so the board history survives the handoff intact. Boards can even mix vendors inside one run: the dispatch command targets a specific CLI for a specific task.

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

dispatch renders the active task's prompt, runs the target CLI headless, extracts the returned receipt, and stamps it with the harness that earned it. The dispatcher itself never edits the board; the PM records it.

Write scope, checked by git

The most convincing engineering detail is how dispatch verifies scope. After a worker runs, GoalBuddy checks the diff mechanically with git: worker changes must stay inside the task's allowed_files list, and read-only roles must change nothing. This is not a prompt asking the model to behave. It is a mechanical check that fails loudly when the model misbehaves.

The role split supports this. Scout maps the repo. Judge chooses the largest safe useful slice. Worker completes the whole assigned slice and leaves a receipt. The prompt command renders a compact prompt for the active task that includes exact role identifiers for both harnesses: goal_scout, goal_worker, or goal_judge on Codex, and goal-scout, goal-worker, or goal-judge on Claude Code. The parallel-plan command extends this to multi-agent work, and a final Judge or PM audit maps receipts and verification back to the oracle before anything is marked complete.

Oracle first

GoalBuddy's thinking loop is written as a chain: Intent, Oracle, Surface, Loop, Proof. The oracle is the observable signal that says whether the original outcome is actually true. The README's list is specific: a test suite, a browser walkthrough, a demo transcript, a generated artifact, a benchmark, a source-backed answer, a release check, or a final human decision.

Then comes the line that gives the project its character: no oracle, no serious goal. Goals without a falsifiable end state are exactly the ones where agents loop forever producing plausible-looking work. By forcing the oracle to be named at prep time, GoalBuddy makes the difference between a finished goal and a vibes-based stopping point into a structural property instead of a hope. The receipt and task-card format (specified in docs/spec/receipt-v1.md as harness-neutral, plain YAML, machine-validated) is what lets the loop carry that proof across tools.

Slice sizing: safe does not mean small

The docs push back on a common failure mode of agent orchestration, which is atomizing work into tiny steps until the agent spends more effort on bookkeeping than on the outcome. GoalBuddy instead optimizes for the largest safe useful slice: a working screen, a working API path, a data pipeline step, a backend vertical slice, a real bug fix, or a milestone review.

Safe is defined as bounded, explicit, verified, and reversible, not as small. And the board watches for the opposite pathology: safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome. When it sees that pattern, it warns. That is a design opinion drawn from real runs, and it is the right one. Agents pad; the warning exists because someone watched it happen.

What lands in your repo

Goal prep creates a fixed layout under docs/goals/:

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 and is the single source of truth; the board UI is a view of that one file. notes/ keeps longer findings out of the main thread, and subgoals/ holds depth-1 child boards when a parent task needs a bounded branch of work. The project calls this stance goalmaxxed and uses it to keep the model small: one state.yaml per board, a hub as a switchboard for many boards, settings as viewer preferences rather than workflow state. Nothing here is an extension marketplace, and that restraint reads as intentional.

Editorial conclusion

GoalBuddy is a small tool with one good idea executed thoroughly: long agent runs need an oracle, a persistent board, and mechanically checked proof, not more prompting. The cross-harness resume, git-verified write scopes, and the no-oracle-no-goal rule all serve that idea. If your Codex or Claude Code sessions keep losing the plot on multi-day work, npx goalbuddy is a cheap experiment with a clear stopping condition.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tolimarchuk/goalbuddy on GitHub