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
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.
Featured in Videos
YouTube tutorials and walkthroughs for goalbuddy
Alternatives
Similar projects ranked by category, topics, and text overlap.