goalbuddy

GoalBuddy

A simple operating loop for long /goal runs.

GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks.

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/

goal.md says what you want.

state.yaml tracks the board.

notes/ keeps longer findings out of the main thread.

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.

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, and verification status without digging through the chat.

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