GoalBuddy provides an operating loop for large-scale coding tasks using AI agents like Codex and Claude Code. It addresses the challenge of maintaining orientation, state, and progress tracking during complex, multi-stage development efforts, especially those involving subgoals or parallel execution. The tool offers a structured local workspace, enabling users to pause, resume, and verify work without losing context, thereby improving the robustness and efficiency of AI-assisted coding projects.

How It Works

GoalBuddy implements a structured operating loop: rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify. The core design centers around state.yaml as the single source of truth for a coding board, with other components like goal.md (defining the objective), notes/, and optional subgoals/ providing context and structure. The Scout agent maps the repository, the Judge agent selects the next actionable task slice, and the Worker agent performs code modifications, leaving a receipt. This approach keeps the AI's focus bounded and the work integrated within the user's repository.

Quick Start & Requirements

Installation and updates are managed via npm: npx goalbuddy and npx goalbuddy update. To initiate a task, use $goal-prep (or /goal-prep in Claude Code) to generate the necessary board files (docs/goals/<your-goal>/) and the subsequent /goal command. For Codex, native plugins and agent configurations are required (~/.codex/plugins/cache/goalbuddy/, ~/.codex/agents/). A verification command is available: npx goalbuddy doctor --target codex --goal-ready. Note that native Codex /goal functionality is an OpenAI-gated feature; GoalBuddy prepares prompts but does not enable it.

Highlighted Details

• Creates a persistent local workspace (docs/goals/<your-goal>/) containing goal.md, state.yaml, notes/, and subgoals/ for structured task management.
• Supports bounded child work through a subgoals/ directory and parallel agent execution via multiple local boards.
• Features "Live Boards" accessible at goalbuddy.localhost:41737/<slug>/, offering real-time visibility into the plan, active tasks, receipts, and verification status, with support for dark mode and compact views.
• Provides utility commands like goalbuddy prompt for generating concise prompts for active tasks and goalbuddy parallel-plan for inspecting potential parallel workflows.

Maintenance & Community

Active development is indicated by release notes for versions like 0.3.5. Release process details are available in RELEASE.md. No specific community channels (e.g., Discord, Slack) or prominent contributors are detailed in the provided README.

Licensing & Compatibility

GoalBuddy is released under the MIT license. This license permits broad usage, including commercial applications and integration into closed-source projects. It is published on npm, ensuring straightforward integration into Node.js-based workflows.

Limitations & Caveats

GoalBuddy facilitates the preparation of parallel work but does not manage a parallel organizational structure. Crucially, it relies on external, OpenAI-gated features like native Codex /goal for core execution; GoalBuddy itself does not enable or replace these underlying AI capabilities.