goalbuddy

GoalBuddy

A simple operating loop for long /goal runs.

GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks, especially when the work branches into subgoals, parallel agents, and long-running verification.

It gives /goal a small local workspace: a charter, 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.

What It Creates

docs/goals/<your-goal>/
  goal.md
  state.yaml
  notes/
  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

rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify

Scout maps the repo.

Judge chooses the next bounded slice.

Worker changes code and leaves a receipt.

/goal keeps the loop honest until the original goal is actually done.

Subgoals, Parallel Agents, and Dark Mode

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.

Use goalbuddy prompt docs/goals/<slug> to render a compact prompt for the active task without dumping the whole state file. 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 can open 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. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.

See GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode for the 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 let /goal work from the generated files.

For release process details, see RELEASE.md.

Star History

License

MIT