A shell check, not agent prose, decides when the work is done.
Goal Loop is a small Cursor plugin and portable loop pattern. It gives your agent a /goal command that keeps working until a shell check passes.
The product is intentionally small:
- One main command:
/goal - One project-local contract:
.cursor/goal/active.json - One stop-hook loop that reruns your check after each finished turn
- One rule that matters: a command exit code decides when the work is done, not the agent's own claim
Use it when you want an agent to keep going until npm test, npm run build, a smoke script, or another concrete command passes. Do not use it as a broad agent platform, a planning OS, or a marketplace of agent behaviors. That is outside what this project does.
| Command | Purpose |
|---|---|
/goal <objective> |
Start an active check-backed goal loop. |
/plan [objective] |
Draft objective and check before activation. |
/goal-status |
Read the active goal and last check result. |
/goal-abort |
Mark the active goal aborted, or remove it with --remove. |
/goal-pause |
Pause the active goal; hook skips the check until resumed. |
/goal-resume |
Resume a paused goal. |
Goal Loop turns a normal objective into a bounded loop:
/goalwrites a contract to.cursor/goal/active.json.- The agent works on that objective.
- Cursor runs the Goal Loop stop hook after each finished turn.
- The hook runs your check commands in the shell.
- If a check fails, the hook returns a
followup_messagewith the failure context and log path. - If every check passes, the hook marks the goal
completedand returns{}.
That is the whole product.
It does not invent new agent thinking. It does not prove more than your check covers. It does not replace good scoping, good tests, or your own judgment.
The most effort Goal Loop will ever ask of you:
/add-plugin goal-loop
After marketplace publication. For local development with Cursor Agent CLI:
cursor-agent --plugin-dir "$PWD" --workspace /path/to/your/projectclaude plugin install @bodecloud/goal-loopOr use Git hooks directly: copy hooks/hooks-claude.json into ~/.claude/hooks.json and hooks/goal-stop-claude.sh into your PATH. Goal Loop reads .cursor/goal/active.json from the project root, the same file Cursor uses, so the loop state is portable across hosts.
clawhub install goal-loopInstalls Goal Loop as an OpenClaw skill from ClawHub. OpenClaw applies it on coding tasks and exposes the /goal commands. Without ClawHub, copy .openclaw/skills/ into ~/.openclaw/skills/.
codex plugin install @bodecloud/goal-loopGoal Loop uses the same .cursor/goal/ state files that Cursor uses, so the contract is portable across editors and CLI agents.
gemini extensions install https://github.com/bodecloud/goal-loopLoads the ruleset as always-on context every session. The skills/ ship too when a task needs them.
Qoder auto-loads AGENTS.md from the repo root as always-on context, so running Goal Loop from a checkout works with zero setup. For per-project rules, copy .qoder/rules/goal-loop.md into your project's .qoder/rules/.
Copy AGENTS.md into your project root. For the CLI, copy .github/copilot-instructions.md into your project. The stop-hook adapter (hooks/goal-stop-claude.sh) works for Claude Code, Grok, and Copilot CLI.
Which files map to which agent: Adapting Goal Loop to other agents.
| Host | Command |
|---|---|
| Cursor | Remove the plugin from Cursor settings |
| Claude Code | claude plugin remove goal-loop |
| OpenClaw | clawhub uninstall goal-loop |
| Cursor / Codex / Qoder / Copilot / Gemini | Delete the copied rule file |
These remove the plugin's own files. They leave behind project-local state in .cursor/goal/. To clean that up:
rm -rf .cursor/goal/active.json .cursor/goal/draft.json .cursor/goal/runs/When changing the shared ruleset, keep the agent copies aligned:
node scripts/check-rule-copies.cjs
npm testThe OpenClaw skill package (.openclaw/skills/) is generated from skills/; rerun node scripts/build-openclaw-skills.cjs after changing a skill, the test suite fails if it is stale. To publish the skills to ClawHub, run clawhub login once, then node scripts/publish-openclaw-skills.cjs (it publishes all skills at the package.json version; pass --dry-run to preview).
Can I use Goal Loop with other agents? Yes. The core pattern is portable: keep goal state in a project-local JSON file, run a check after each finished turn, continue only when that check fails, and stop when it passes. See Adapting Goal Loop to other agents.
What check should I use?
npm test, npm run build, or any other shell command whose exit code decides pass or fail. Good checks are repeatable, local to the stated objective, cheap enough to rerun every turn, and strong enough to prove the intended result. See How to design a check.
What happens if the hook crashes?
Goal Loop fails open: a crashed hook returns {} (stop, no continuation) instead of trapping the agent in a loop. The error is written to .cursor/goal/runs/hook-errors.log.
Does Goal Loop work offline? Yes. All checks run locally via the shell. No network calls are required for the core loop.
MIT.