How to Use Claude Code's /goal for Autonomous Multi-Turn Tasks

Claude Code v2.1.139, released May 11, 2026, adds a /goal command that sets a completion condition and keeps Claude working across turns until that condition is met. After every turn, a separate evaluator model -- defaulting to Haiku -- checks whether your condition holds. If not, Claude keeps going. If yes, the goal clears and you get control back. No prompting each step.

I've been working with Claude Code daily for months. The multi-turn capability was always there, but driving it to an actual completion condition without babysitting required a mix of hooks, Stop triggers, and manual re-prompting. /goal makes that loop native and first-class in the CLI.

What does the /goal command actually do?

The /goal command creates a session-scoped execution loop: Claude works a turn, then a small fast evaluator model checks whether your stated condition is satisfied based on the conversation transcript. A "no" sends Claude another turn with the evaluator's reason included as guidance. A "yes" clears the goal, logs an "achieved" entry in the transcript, and returns control to you.

The design decision that matters here is the separate evaluator. The model judging completion is not the same model doing the work -- that's an important distinction. Claude Haiku is the default evaluator (per the official /goal docs), and it reads the conversation transcript rather than accessing the filesystem independently. This means two things: evaluation is cheap, and your completion conditions need to be written as things Claude can demonstrate through its output -- not as silent filesystem assertions.

While a goal is running, an overlay panel in the terminal shows live elapsed time, turn count, and current token usage. You can watch the loop or switch to Agent View and let it run in the background. The goal persists across terminal detach if you're using Remote Control mode.

How do you set a goal in interactive mode?

In an active Claude Code session, type /goal followed by your completion condition in plain language. Claude starts working immediately -- the condition text serves as the directive for the first turn. No additional prompt needed.

Examples that work well in interactive mode:

/goal find and fix the flaky auth tests
/goal CHANGELOG.md has an entry for every PR merged this week
/goal every TODO comment in src/ has been converted to a tracked issue
/goal the payments module compiles clean and all existing tests pass

Write the condition as a verifiable end state. "Migrate the payments module to the new API until every call site compiles and tests pass" gives the evaluator something to judge. "Improve the code" gives it nothing. The evaluator returns a short reason with each yes/no decision -- that reason is included in the next turn's context when Claude continues, so good condition language compounds: the more specific you are, the better Claude's corrections on failed turns.

To stop a goal mid-run: /goal clear. The transcript preserves what Claude has done so far. You can also bound the run with a clause inside the condition itself: "/goal process the open issue backlog, max 20 turns" -- the evaluator judges both task state and turn count from the transcript. The most recent evaluator reason shows in the status overlay and in the full transcript.

How do you run /goal in headless (-p) mode?

The /goal command works in headless mode via the -p flag. Pass your goal directly as the prompt text and Claude runs the entire loop to completion in a single invocation -- no terminal session required.

Basic headless invocation:

claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

With a token budget cap:

claude -p "/goal --tokens 250K do deep research and build the full prototype"

The --tokens flag sets a hard token ceiling for the entire goal loop. When the budget is exhausted, the goal stops and logs the partial result. This is the right pattern for cron jobs and CI pipelines where you want bounded compute costs -- Claude Code sessions typically run 10,000 to 50,000 input tokens depending on tool usage (Shipyard analytics), but unbounded goal loops against complex codebases can run significantly higher.

For CI/CD integration, pair it with --output-format json to get structured output:

claude -p "/goal all failing tests in the auth/ directory are fixed" --output-format json

The JSON output includes the final transcript, goal status (achieved or stopped), turn count, and token totals -- parseable by downstream pipeline steps.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

How do you write completion conditions that actually work?

The evaluator reads only what Claude has surfaced in the conversation -- it doesn't run commands or read files independently. Write conditions as things Claude can demonstrate through its output: reported test results, listed file changes, logged counts, or explicit confirmation statements. If the end state requires checking the filesystem, tell Claude to check and report in its turn.

Conditions that work well:

Test-based: "All tests in the auth module pass" -- Claude runs the tests and reports results each turn; the evaluator reads those results.
Count-based: "The backlog queue is empty" -- Claude processes items and reports the remaining count.
Audit-based: "Every function in payments.py has a docstring" -- Claude reads the file, reports what's missing, fixes it, confirms completion.
Document-based: "CHANGELOG.md has an entry for every PR merged since Monday" -- Claude queries git log, checks the CHANGELOG, adds missing entries, and confirms.

Conditions that fail reliably:

Vague outcomes ("the code is clean", "tests are better") -- the evaluator can't make a yes/no call.
Pure filesystem assertions without a reporting step ("the file exists") -- the evaluator can't see the filesystem.
Conditions requiring external system checks ("the deploy is live on Heroku") -- unless Claude is told to check and report the result.

One pattern that works well: build the verification step into the condition. "All failing tests pass -- confirmed by running pytest and reporting the output" tells Claude exactly what to do at the end of each turn to give the evaluator something to judge.

How does Agent View work alongside /goal?

Agent View, also released in v2.1.139 as a Research Preview (official docs), is a full-terminal dashboard that lists every Claude Code session -- running, blocked, or done -- in a single view. Sessions are grouped by state, with those needing your attention pinned at the top.

The practical workflow: start a /goal loop in one session, switch to Agent View, and dispatch other sessions while the goal runs in the background. When the goal finishes or needs you (for a permission prompt or a blocked state), Agent View surfaces it. You navigate with arrow keys, press Space to see session state, and type a reply + Enter to respond without leaving the dashboard.

Agent View works with any Claude Code session, not just /goal runs. Long-running agents, scheduled tasks, and standard interactive sessions all appear in the list. Each row shows the session name, current activity, and how long ago it last changed. Sessions keep running without a terminal attached -- you can close the dashboard and reopen it to check status.

Agent View is available on Pro, Max, Team, Enterprise, and Claude API plans as of v2.1.139. The Research Preview label means the UI and session management features may change -- Anthropic has flagged this as an evolving surface in the Agent View announcement.

What are the limits and known constraints?

The /goal command has four practical constraints to plan around: the evaluator reads only the conversation transcript (not files directly), goals don't survive process kills, token costs compound with each additional turn as history grows, and Agent View is a Research Preview with a UI that may change. All four are manageable with the right patterns.

Evaluator reads transcripts, not files. If Claude modifies a file but doesn't report the change in the conversation, the evaluator may not detect it. Build explicit reporting into your conditions or use Claude's output to confirm state changes each turn.

Goals don't survive process kills. If the Claude Code process is killed mid-goal (SIGKILL, OOM), the goal state is lost. The transcript up to that point is preserved in the session, but the loop won't resume automatically. For long-running jobs, the Remote Control mode + headless -p invocation is more reliable than interactive /goal.

Token costs compound across turns. Each turn re-sends the growing conversation history. A 20-turn goal against a large codebase can hit 200,000 tokens or more. Use the --tokens flag to cap it, and use /compact mid-goal to manage context growth. The live token counter in the status overlay makes this visible in real time.

Agent View is a Research Preview. The session management API, keyboard shortcuts, and display format are still being iterated. Stable production workflows should treat the underlying goal loop as durable and the Agent View UI as subject to change.

FAQ

What model evaluates the /goal completion condition?

The evaluator defaults to your configured small fast model, which is Claude Haiku by default. Haiku reads the conversation transcript after each turn and returns a yes/no decision plus a short reason. The reason is included in Claude's next turn as guidance when the condition isn't met yet. You can change the evaluator model in Claude Code's model configuration settings.

Can /goal run in a CI/CD pipeline without a terminal?

Yes. Run it with the -p flag in headless mode: claude -p "/goal condition here". The full goal loop runs to completion in a single invocation with no interactive terminal required. Add --output-format json for structured output parseable by downstream pipeline steps. Use --tokens to cap compute costs for predictable CI billing.

How is /goal different from writing a CLAUDE.md instruction to keep working?

CLAUDE.md instructions set session-level behavior but don't create a separate evaluator loop. With /goal, a distinct model judges completion after every turn independently -- Claude doesn't decide for itself when to stop. That separation means the completion check is unbiased. CLAUDE.md instructions for behavior (tools, permissions, style) still apply during a /goal run.

What happens if a goal runs indefinitely?

Use the --tokens flag to set a hard ceiling: /goal --tokens 250K [condition]. You can also write a turn limit into the condition itself: "complete the task, max 15 turns." The evaluator tracks the turn count from the transcript and stops the loop when the limit is reached. Without any limit, the goal runs until the condition is met or you run /goal clear manually.

Is Agent View available on all Claude Code plans?

Agent View is available as a Research Preview on Pro, Max, Team, Enterprise, and Claude API plans as of v2.1.139. It requires Claude Code version 2.1.139 or later. The feature is not available on the free Claude.ai tier as of the May 11, 2026 release.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

Agent-tools

How to Use Claude Code's /goal for Autonomous Multi-Turn Tasks