Skip to content
claude-goal

claude-goal

A production-grade autonomous loop for Claude Code — built around a Stop-hook continuation engine and a tool-equipped completion evaluator. Say "set up a goal" or use /goal-start, pick a budget profile when you need one, walk away.
Quickstart View on GitHub
claude-goal — autonomous goal loop for Claude Code

What it does

Section titled “What it does”

claude-goal drives the Claude Code agent through an autonomous loop until a goal is provably met. You set an objective with /goal-start or explicitly ask Claude to “set up a goal”; the plugin self-iterates each turn through a Stop-hook continuation; a tool-equipped evaluator subagent checks completion — not by trusting the worker’s self-narrative, but by running tests, reading files, and checking exit codes.

It’s the production-grade companion to Claude Code 2.1.139+‘s built-in /goal — adding deterministic budgets, lifecycle controls, /compact recovery, persistence across restarts, and a real verifier.

Terminal window
/plugin marketplace add nuko-nova-dynamics/claude-marketplace
/plugin install claude-goal@nuko-nova-tools

Why it exists

Section titled “Why it exists”

Deterministic budgets

--budget quick|standard|deep|overnight|auto expands into hard token, turn, and wall-clock caps. Raw token numbers still work for advanced tuning. The hook math is plain SQLite — no model in the loop deciding when to stop.

Tool-equipped evaluator

The completion check runs as a fresh-context subagent with Bash, Read, and sqlite3. It verifies with evidence, not optimistic transcript language.

Lifecycle controls

Pause, resume, abandon, extend. Caps for turns and wall-clock. All persisted in SQLite — survives claude restart and --resume.

`/compact` recovery

When Claude Code rewrites the transcript, the goal flips to accounting_uncertain. /goal-reconcile --accept-reset advances cleanly. No silent token drift.

Independent verifier

Worker self-audit AND evaluator. Distinct completion events (goal_completed_by_evaluator vs goal_completed_by_self_update) so post-hoc audit can tell them apart.

Plays well with native `/goal`

Compatible with Claude Code 2.1.139+‘s built-in /goal. The two coexist — use the native one for casual conditions, this one when budgets and persistence matter.

Try it in 60 seconds

Section titled “Try it in 60 seconds”
/goal-start "list every .ts file under src/ and print a line count for each"

Or ask directly:

set up a goal to list every .ts file under src/ and print a line count for each

Claude confirms the goal, begins working, and the Stop hook feeds it a continuation prompt at the end of each turn. When the objective is met, it dispatches the evaluator subagent for verification, then calls update_goal and stops.

For a bounded run, pick a profile instead of doing token math:

/goal-start "refactor the auth module to use async/await" --budget standard

standard gives the run 10M tokens, 200 continuations, and 8 hours. Omit --budget on /goal-start, or omit budget wording in explicit prose, for practical-unlimited token, turn, and wall-clock budget. Use auto only when you explicitly want deterministic profile selection. See Budgets and caps for the full profile table.

Deep dive

Section titled “Deep dive”
How it works Stop-hook continuation, token accounting, completion paths, F5 final-turn retry, SQLite state store.
Budgets and caps Token budgets, turn caps, wall-clock caps. Worker vs subagent attribution.
Completion evaluator Why a tool-equipped subagent beats same-model self-audit.
State and persistence The SQLite schema, migration runner, audit event log.

Status

Section titled “Status”