GoalBuddy's package keeps two command names and a postinstall hook

Two command names, one script

The package publishes two binaries and both point at the same file:

"bin": {
  "goalbuddy": "internal/cli/goal-maker.mjs",
  "goal-maker": "internal/cli/goal-maker.mjs"
}

The second one is the older name, kept alive as an alias. You can see the same history in the install section, which says a clean Codex install should not need personal `~/.codex/skills/goalbuddy` or `~/.codex/skills/goal-maker` folders, and in the cleanup section, which lists old personal skill folders from earlier installs among the things GoalBuddy still owns. So the legacy spelling is present in three places at once: a console script, a skill folder that should no longer be needed, and a removal path that has to know about it. The published file list is correspondingly explicit about what travels: two marketplace manifests under .agents/plugins/ and .claude-plugin/, the plugins/goalbuddy tree, internal/assets, internal/cli, the goalbuddy directory, CHANGELOG.md, README.md, CONTRIBUTING.md and docs/releases.

Installing the package runs a script that writes into your home directory

The scripts block has a postinstall hook that runs a Node file:

"postinstall": "node internal/cli/postinstall.mjs",
"publish:check": "node internal/cli/check-publish-version.mjs && npm run pack:dry-run",
"prepublishOnly": "node internal/cli/check-publish-version.mjs"

So a plain install of this package executes code, and what that code does is documented further down, on the Codex side, as the canonical install being a native plugin plus bundled agents living in three places:

~/.codex/plugins/cache/goalbuddy/goalbuddy/<version>/
~/.codex/agents/goal_judge.toml
~/.codex/agents/goal_scout.toml
~/.codex/agents/goal_worker.toml

Note that the cache path is versioned, so successive installs accumulate one directory per version. On the Claude Code side the corresponding change is a command: GoalBuddy installs `/goalbuddy` so that Claude's own `/goal` stays untouched. The start path is short, one command and a restart, then a preparation step, `$goal-prep` in Codex and `/goal-prep` in Claude Code, which creates the board and prints the exact command to run next.

Removing the native plugin leaves four surfaces behind

This is the section worth reading twice, because the obvious uninstall is incomplete and the page says so. 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. The command for the full removal is:

npx goalbuddy reset --target codex

and the same paragraph tells you to use it when you want those GoalBuddy-owned files removed too. There is a matching verifier for the other direction, `npx goalbuddy doctor --target codex --goal-ready`, for checking that an install is what it claims to be. Updates have their own command, `npx goalbuddy update`, which the page says updates both Codex and Claude Code. The release names suggest why this care exists: v0.4.3 is titled as restoring Claude's native `/goal`, v0.4.2 as honest continuation state and v0.4.1 as installed contract fixes.

dispatch checks write scope with git and refuses to touch the board

Boards can mix vendors inside one run, and the command that does it is the one with a real safety story:

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

dispatch renders the active task's prompt, runs the target CLI headless, with codex or claude-code as the target, extracts the returned receipt, and then verifies write scope mechanically with git. A worker's changes must stay inside the task's `allowed_files`, and a read-only role must change nothing. The rule that makes this more than a suggestion is the second one: the dispatcher never edits the board. The PM records the receipt, stamped with the harness that earned it, so a run that mixed a Claude judge with a Codex worker keeps a history that says who did what. The read-only counterpart is `goalbuddy parallel-plan docs/goals/<slug>`, which inspects read-only or disjoint write-scope work and reports recommendations only, without mutating state or spawning agents.

Three roles, two spellings, two harnesses

The loop is written as a five-step chain, Intent to Oracle to Surface to Loop to Proof, and the oracle is the part with teeth: the observable signal that says whether the original owner's outcome is actually true, whether that is 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. The rule attached to it is short, no oracle, no serious goal. Three roles implement it: Scout maps the repo, Judge chooses the largest safe useful slice, Worker completes the whole assigned slice and leaves a receipt, and a final Judge or PM audit maps receipts and verification back to the oracle. The role identifiers do not translate cleanly between harnesses. Codex uses `required_spawn_agent_type` with `goal_scout`, `goal_worker` or `goal_judge`, spelled with underscores, while Claude Code uses `required_claude_subagent_type` with `goal-scout`, `goal-worker` or `goal-judge`, spelled with hyphens. The page says to use the exact GoalBuddy role rather than a generic agent, which matters precisely because the two spellings are not interchangeable.

The project's own policy is against making tasks small

The Slice Sizing section argues against the instinct most of these tools encourage. Safe does not mean small. Safe means bounded, explicit, verified, and reversible. The stated goal is the largest safe useful slice, with the examples given being a working screen, a working API path, a data pipeline step, a backend vertical slice, a real bug fix or a milestone review. There is a stated warning condition too: the board complains when it sees safe-looking work that keeps adding helpers, contracts, proof files or doc notes without moving the outcome. That is a specific anti-pattern the tool watches for, and it is the opposite of what a slicing tool that optimises for tiny safe tasks would do. The storage model underneath it is deliberately small: `state.yaml` is the source of truth, a board is a view of one `state.yaml`, a subgoal is one depth-1 `state.yaml` linked from a parent task, the local hub is a switchboard for many boards, and settings are viewer preferences rather than workflow state.

Everything lands under docs/goals, and the page stops mid-sentence

A goal run creates one directory in your repository:

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, and subgoals/ holds bounded child boards. Because these are plain files, the argument for the tool is portability: begin a goal in Codex, resume it in Claude Code tomorrow, using the command for that harness, since `resume` prints both continuation commands and both are the same sentence, Follow docs/goals/<slug>/goal.md. Receipts can record which harness performed each task, so the history survives the handoff. The page's last section, on live boards, describes the local board as the default work surface and explicitly not an extension marketplace, and its final sentence begins Multiple local boards reuse on and does not finish. One more detail: the recorded homepage is http://goalbuddy.dev/ while the page's own links are https.

Editorial conclusion

GoalBuddy fits a team already working in Codex or Claude Code on a repo where they want the plan, the receipts and the verification state to survive a tool change, and where a git-checked write scope is worth more than a clever planner. It does not fit a solo task that fits in one turn, because the whole apparatus exists to keep a long run oriented. Three things to settle before you install it. First, the install is not inert: the package runs a postinstall script and writes a versioned plugin cache and three agent files into your home directory, so read what it touches before you run it. Second, plan the removal now, because the native Codex removal command leaves the agent files, the cache, the marketplace entry and old skill folders behind. Third, decide whether you want the strictness, because a run with no oracle is refused by design, and that is a feature only if you have a real signal to check against.

Frequently asked questions

Official sources

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