A /goal operating system for Codex and Claude Code: subgoals, parallel-agent-ready boards, dark mode, receipts, and verification.
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.
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.
For Codex, the canonical install is the native plugin plus bundled agents:
~/.codex/plugins/cache/goalbuddy/goalbuddy/<version>/
~/.codex/agents/goal_judge.toml
~/.codex/agents/goal_scout.toml
~/.codex/agents/goal_worker.toml
The Codex plugin bundles $goal-prep; a clean Codex install should not need personal ~/.codex/skills/goalbuddy or ~/.codex/skills/goal-maker folders. Native Codex /goal is a separate OpenAI-gated feature. GoalBuddy prepares local boards and handoff prompts for it, but it does not enable or replace native /goal.
To verify a Codex install:
npx goalbuddy doctor --target codex --goal-ready
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.
rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
Scout maps the repo.
Judge chooses the largest safe useful slice.
Worker completes the whole assigned slice and leaves a receipt.
/goal keeps the loop honest until the original goal is actually done.
Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
GoalBuddy should not optimize for tiny safe tasks. It should optimize for the largest safe useful slice: a working screen, working API path, data pipeline step, backend vertical slice, real bug fix, or milestone review. The board warns when it sees safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome.
GoalBuddy keeps the model small:
state.yaml is the source of truth.state.yaml.state.yaml linked from a parent task.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.
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. The prompt includes a mandatory required_spawn_agent_type; Codex PMs should use that exact GoalBuddy agent (goal_scout, goal_worker, or goal_judge) instead of a generic role agent. 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.
When a new GoalBuddy version ships:
npx goalbuddy update
That updates both Codex and Claude Code.
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. When sharing a board in chat or docs, use a real Markdown link such as [Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/) so the URL is clickable. 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.
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.
MIT
FAQs
A goal operating loop for Codex and Claude Code: goal oracles, local boards, receipts, and verification.
The npm package goalbuddy receives a total of 31 weekly downloads. As such, goalbuddy popularity was classified as not popular.
We found that goalbuddy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.