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. Set an objective, set a budget, 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; 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 N enforces a hard token ceiling across worker + subagent turns. 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"

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 budget-bounded run — note that real autonomous goals run for hours and millions of tokens, so budgets are sized in millions:

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

When (tokens_used + subagent_tokens) >= 3000000, the hook transitions the goal to budget_limited and emits a one-shot budget-limit prompt. See Budgets and caps for how to size a budget for the shape of your goal.

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”