goalbuddy logo

goalbuddy

A better /goal for Codex and Claude Code

Developer ToolsJavaScriptMIT 803 66Health 77
npmsite goalbuddy.dev
Website GitHub

What is it?

What it is

GoalBuddy is a tool that creates and manages local goal boards for long-running coding tasks, enabling resumption across different AI harnesses (Codex/ Claude Code) with a structured workflow involving receipts, verification, and proof loops.

Why it exists

To provide a persistent, reproducible work surface for long goals, ensuring continuity between AI tools and maintaining task integrity through local repository storage.

Who should use it

Developers working on long-term coding projects, teams switching between AI coding tools (Codex/Claude Code), and users needing persistent goal tracking across repos

Who should avoid it

Users needing simple one-off tasks, those uncomfortable with CLI tools or repo management, and projects without verification requirements

How it works

A quick walkthrough in plain English

How goalbuddy works

Step 1 of 3

You interact with it

Open goalbuddy, send a request, or connect it to your stack.

Features

Local board and goal workspace stored in repo
Cross-harness goal support (Codex and Claude Code)
Automatic goal prep and resume commands
Subgoal support for bounded child work
Receipt-based proof loop with machine-validated YAML
Live board UI with task status and receipts
Dispatch command to run tasks on specific harness
State persistence via state.yaml
Integration with Codex/Claude Code plugins and agents
Command-line tooling (goalbuddy, goal-prep, resume, dispatch, prompt, parallel-plan)

Advantages

  • Persisted goal state in repo allows resume across tools and time
  • Unified board works with multiple AI harnesses
  • Clear next task and loop ensures progress tracking
  • Verification via receipts and oracles adds reliability
  • Live board UI provides real-time visibility
  • Subgoals enable modular, bounded work
  • Command-line interface is lightweight and scriptable
  • Open-source MIT license and npm distribution
  • Supports large tasks that exceed single prompt limits

Disadvantages

  • Requires Codex or Claude Code integration, not standalone
  • Learning curve for new users to understand board structure
  • Potential overhead of managing board files in repo
  • May be overkill for small, simple tasks
  • Dependency on external AI services for execution
  • Installation steps can be complex for some users

Installation

native

npx goalbuddy

FAQ

How do I install GoalBuddy and get it ready to use?

Run `npx goalbuddy` in your terminal. This installs GoalBuddy, sets up the necessary local files, and prepares the native `/goal` command for Codex or Claude Code. After installation, restart Codex or Claude Code to load the new command.

How do I create a new goal and start the execution loop?

Use the Goal Prep command. In your terminal run `$goal-prep` or in Claude Code type `/goal-prep`. This creates the goal board in `docs/goals/<slug>/`, prints the exact `/goal` command to run next, and sets up the local workspace. Execute that `/goal` command to launch the loop.

What if I want to resume a goal that was started in a different harness?

Run `npx goalbuddy resume`. It lists all live boards in the repo, shows their status and active task, and prints the exact `/goal` command (e.g., `Follow docs/goals/<slug>/goal.md`) that you can run in either Codex or Claude Code to continue the same goal.

Can I hand off a task to a different agent or harness?

Yes. Use `npx goalbuddy dispatch docs/goals/<slug> --to codex` (or `--to claude-code`). This renders the active task prompt, runs the target CLI headless, extracts the receipt, and verifies that the worker’s changes stay within the allowed files. The board’s history remains intact across harnesses.

How do I view the live board while the goal is running?

GoalBuddy opens a local board at `http://goalbuddy.localhost:41737/<slug>/`. Open this URL in a browser to see the plan, active task, receipts, subgoals, and verification status in real time. The board supports dark mode, compact mode, and other UI options.

Loading documentation…
View on GitHub

Featured in Videos

YouTube tutorials and walkthroughs for goalbuddy

Alternatives

Similar projects ranked by category, topics, and text overlap.

Compare
goalbuddy | MushyBook