Claude Code /goal: how e work and wetin e cost
Make Claude Code finish one job without you prompt am every turn. Learn how /goal judge your condition and why tmux on VPS keep am alive when light cut.
Wetin /goal for Claude Code dey do?
The /goal command for Claude Code dey make Claude continue to work until one condition wey you write don happen. You no need to type "continue" after every turn. When Claude finish one turn, one small fast model go check whether your condition don hold. If e never hold, Claude go start another turn by imself, instead of to return control give you.
This guide na for person wey don dey use Claude Code with Claude Pro or Max, and wey wan make am finish one job alone. The main lesson na how to write condition wey the checker fit judge. The second lesson na how goal turns take your usage limit, and how to keep long goal alive when light or data cut for Lagos, Abuja or anywhere.
How /goal dey work inside
/goal na wrapper around one prompt-based Stop hook, and e dey live only inside the current session. Stop hook na hook wey dey run anytime Claude finish one turn. "Prompt-based" mean say na model dey answer the hook, no be script. If you never sabi hooks well, how Claude Code hooks work go explain the full system.
Each time Claude finish one turn, Claude Code go send your condition and the conversation so far give the small fast model wey you configure. The model go return one verdict, with short reason:
- Not yet met: Claude go continue to work, and e go use the reason as guidance for the next turn.
- Met: the goal go clear, and Claude Code go record am as achieved.
- Impossible: the goal go clear, and Claude Code go record am as failed, with the reason. You no need to clear am yourself.
Only one goal fit dey active for one session. If you set new goal while one dey active, the new one go replace the old one. Once you set goal, one turn go start immediately, and the condition itself na the instruction for that turn. You go see one ◎ /goal active indicator wey show how much time don pass.
The checker no dey run command, so write condition wey Claude output fit prove
This na the most important part for this guide. The evaluator no dey run command. E no dey read file. E no dey call any tool at all. E fit only judge wetin Claude don already show inside the conversation.
Wetin that one mean for you: if your condition na "the tests pass", but Claude never run the tests and show the result inside the conversation, the checker no get anything to judge. So your condition must be something wey Claude own output fit show with evidence.
The docs talk say good condition get these parts:
- One end state wey you fit measure: test result, build exit code, number of files, or empty queue.
- One check wey you state: how Claude go prove am, like "
npm testexits 0" or "git statusis clean". - Constraints wey matter: anything wey must not change on the way.
- One bound: turn or time clause, like
or stop after 20 turns.
The condition fit reach 4,000 characters, so you get space to write am well. See one weak condition:
/goal fix the login bugThis one weak because "fix" no get end state wey anybody fit measure. The checker go just guess from how Claude talk. See better version:
/goal `npm test` exits 0 and Claude shows the final summary line of the test output in the conversation. Do not change any file under tests/ and do not add new dependencies. Or stop after 20 turns.Now the checker get something to read. Claude must run npm test and paste the summary line. If Claude talk say "all tests pass" without the output, the checker fit answer "not yet met", because the proof no dey.
About the bound: no hard counter dey behind am. Claude dey report progress against that clause each turn, and the evaluator judge am from the conversation. So na the model dey enforce the bound when e read the conversation. For -p runs, the CLI reference get --max-turns, wey limit agentic turns for print mode only and get no limit by default. The docs no talk whether --max-turns dey count goal turns the same way, so no treat am as the same thing as or stop after 20 turns.
One more guard dey. If Claude continue to answer the checker but no make progress (no tool use for several turns in a row), Claude Code go stop the loop, print warning, and return control give you. The goal go still dey set. Evaluation go start again after your next prompt.
How to see goal status and how to clear am
Type /goal without argument:
/goalE go show you the condition, how long e don run, how many turns don pass evaluation, the current token spend, and the most recent reason from the evaluator. Turn count and reason go show only after the first evaluation. If no goal dey active, e go show the last achieved goal with its condition, duration, turn count and token spend.
To remove goal early:
/goal clearE go print Goal cleared: plus your condition, or No goal set if nothing dey. Claude Code also accept stop, off, reset, none and cancel as aliases for clear. If you run /clear to start new conversation, that one too go remove any active goal.
Wetin /goal dey cost for Claude Pro or Max
Each goal turn na normal Claude Code turn. Claude dey think, call tools and read files the same way as when you dey type each prompt yourself. On Pro and Max, Claude Code usage dey count against the same limit as your other Claude usage. Paid plans get one session limit wey dey reset every five hours, plus weekly limits wey cover all models. How much each turn take depend on how long and how complex the conversation be, the features wey you use, the model, and the effort level.
The help center page no give fixed number for Pro or Max. If you wan understand the size of the allowance, read how many tokens Claude Pro include. For how Claude Code count wetin e use, Claude Code token usage explained go help you.
Most of the cost come from the main turns. The docs talk say evaluation tokens dey bill on the small fast model for your provider, and e dey usually small compared to the main turns. So goal wey run 20 turns cost you like 20 normal turns, plus small extra for the checks. That na why the bound for your condition matter: e protect your five-hour window.
You fit change the evaluator model with ANTHROPIC_DEFAULT_HAIKU_MODEL. But Claude Code dey read that variable everywhere e use the small fast model. E go also change the haiku alias, session title generation and some other background work.
When usage limit reach, the goal go pause, e no go clear
This one good news for person wey dey manage limit. For interactive session on Claude Code v2.1.269 or later, if claude.ai usage limit stop the goal, Claude Code go print notice wey start with Goal paused and name the cause. The goal still dey set. If the session dey wait to continue by itself when the limit reset, Claude go continue the goal that time.
Automatic continue dey on by default for interactive sessions wey sign in with claude.ai subscription, and e need v2.1.234 or later. Claude Code go wait inside the open session and continue after the reset. E go stop after three automatic continuations, including for /goal wey run through several reset windows.
Now the part wey concern us for Nigeria. If you exit Claude Code, the wait no go restart when you resume the session. If NEPA take light and your laptop off, or your MTN data finish and the terminal close, the wait die with am. That na the main reason to run long goal on VPS inside tmux, wey the next section show. If limit don already catch you, wetin to do when Claude limit reach get the other options.
The goal page talk about this pause only for interactive sessions. E no describe wetin claude -p run go do when usage limit reach, so no assume say -p go pause and continue by itself.
Some other errors dey wey no go clear the goal. If server overload or connection drop, notice wey start with Goal still active go show how long Claude Code go wait before e try again. After three automatic retries, the goal go pause.
Some errors go clear the goal, because e no fit pass until you fix something:
- authentication failure, when Claude Code dey manage its own credentials
- disk wey full reach the point say e no fit renew the claude.ai login
- credit balance wey don finish
- context overflow wey auto-compaction no fit clear
- model wey no dey available
The warning go start with Goal cleared after an unrecoverable error and end with Run /goal again to continue. So after you fix the cause, you must set the goal again.
How to keep long /goal alive for VPS with tmux
If Claude Code dey run for VPS instead of your laptop, light or data cut go only kill your SSH connection. The Claude Code session go still dey run for the server. tmux na terminal multiplexer: you fit detach from am, e go continue to run for background, and you fit attach back later. For the full setup, read how to run Claude Code on a VPS with tmux.
Install tmux and open named session:
sudo apt update && sudo apt install -y tmux
tmux new-session -s goalInside the tmux session, enter your project and check your Claude Code version:
cd ~/myproject
claude --version
claudeThe first time, claude go open browser login. For VPS, browser no dey, so press c to copy the login URL, open am for your phone or laptop, and sign in with your claude.ai account. If the browser show you login code instead of to redirect, paste am for terminal where e talk Paste code here if prompted. On Linux, Claude Code dey store the login for ~/.claude/.credentials.json with file mode 0600. Check am:
ls -l ~/.claude/.credentials.jsonThe line should start with -rw-------, which mean only your user fit read am.
Now set your goal inside Claude Code. When ◎ /goal active show, press Ctrl+b, release am, then press d. That one detach you from tmux. You fit close your laptop. When light or data come back, SSH enter the VPS again and attach:
tmux attach-session -t goalYou should see the same Claude Code screen with the goal still running. If attach fail, run tmux ls. If e no list one session named goal, the tmux session no dey again. The usual cause na say the VPS reboot. For that case, go the resume section below.
How to run /goal with claude -p and see every step
Non-interactive mode na -p (or --print). You put /goal inside the prompt string, and the loop go run until e finish, all inside one command:
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" \
--permission-mode auto \
--output-format stream-json --verbose | tee goal.logWith the default text output, Claude go print only the final answer when the loop end. So goal wey run many turns fit look like e hang. --output-format stream-json --verbose dey print each message as the loop dey run, one JSON per line. tee goal.log save the same lines for file, so you fit read them later. To stop the goal before e finish, press Ctrl+C. claude -p dey exit with 0 when e succeed and non-zero when e fail.
Why --permission-mode auto dey there: goal no dey change your permission mode. With Claude Code v2.1.302 or later, claude -p dey start for Manual mode when nothing set permission mode, and any tool call wey need approval go just fail because nobody dey there to approve am. Auto mode let goal turns run without you. Before you turn am on, read how Claude Code auto mode decide permissions, so you understand wetin e go allow.
Two safety points for VPS. First, without --bare, -p session go run the hooks inside project .claude/settings.json and connect the servers for .mcp.json, even inside folder wey you never trust, and e no go show trust dialog. So no run goal inside repo wey you clone from person wey you no know until you read those files. Second, no add --bare to fix that one. Bare mode no dey use your subscription login at all: e need ANTHROPIC_API_KEY, so Pro or Max login no go work there.
How to continue goal after light or data cut
Claude Code dey restore active goal on every resume route: --continue, --resume with session ID, name or transcript file path, and the session picker. The picker route need v2.1.239 or later. When e restore, the condition go come back, but the turn count, timer and token-spend baseline go start from zero. E no go restore goal wey don already achieve or clear.
One trap dey here. Plain claude --continue dey skip sessions wey claude -p create. claude -p --continue include them. So for goal wey you start with -p, the clean way na to take the session ID. The last line for goal.log na result message wey carry the final answer, cost and session details:
sudo apt install -y jq
session_id=$(tail -n 1 goal.log | jq -r '.session_id')
echo "$session_id"
claude --resume "$session_id"echo should print long ID, no be null. If e print null, the run never reach the end, so the last line no be the result message. Inside the resumed session, type /goal to confirm say the condition don come back. For more on how sessions dey save, see Claude Code resume and session history.
/goal vs /loop vs Stop hook: which one you need?
All of them fit keep session dey work, but each one start the next turn for different reason.
/goal: next turn start when the last turn finish. E dey only for the current session. E stop when the checker talk "met" or "impossible", or when you clear am./loop: bundled skill wey run one prompt again and again on time interval inside open session. The minimum interval na 1 minute, and seconds go round up to the next minute. If you no give interval, Claude go choose delay between one minute and one hour each time. Recurring tasks expire 7 days after you create them: the task go fire one last time, then delete itself.- Stop hook for settings file: next turn start when the last turn finish, like
/goal. But e dey live for your settings file and apply to every session inside its scope. E fit run script for fixed checks, or prompt for checks wey model go judge.
Some /loop details wey fit catch you. Tasks dey fire only while Claude Code dey run and idle. Fixed-interval loop no go stop with Esc or Ctrl+C; you must ask Claude to cancel am. Self-paced /loop no dey come back after --resume or --continue, so you must run /loop again.
Choose /goal when the job get clear end, like "tests pass". Choose /loop when you wan check something on schedule, like deploy status every 10 minutes. Choose Stop hook when you want the same rule for every session, or when you want script to check instead of model. Loop engineering explain how to design these loops well.
Which version you need, and flags wey no exist
The official changelog list /goal under v2.1.139, dated May 11, 2026, and talk say e work for interactive, -p and Remote Control. But many parts wey this guide use come later: check-ins and automatic continue need v2.1.234, the picker restore need v2.1.239, the Goal paused and Goal still active notices need v2.1.269, and the Manual-mode default for -p come with v2.1.302. Run claude --version and compare am with the goal page before you depend on any of them.
Some guides for internet show commands like claude --headless --goal "...". The CLI reference no list any --headless or --goal flag. Non-interactive mode na -p, and you set goal by putting /goal <condition> inside the prompt string. If any guide show flag wey you never see before, check am for the CLI reference before you run am.
/goal fit also refuse to work. E follow the same workspace trust rule as hooks inside settings files, because the evaluator na part of the hooks system. E no go dey available if disableAllHooks be true after settings precedence, or if allowManagedHooksOnly dey set for managed settings.
FAQ
Why my /goal no dey stop even when the work don finish?
The checker no dey run command or read file. E only judge wetin Claude show inside the conversation. If Claude never print the proof, like the npm test output with exit code 0, the checker go continue to answer "not yet met". Write condition wey name the check and ask Claude to show the result, then add bound like or stop after 20 turns.
My Claude Pro usage limit reach while goal dey run. I go lose the goal?
No. For interactive session on v2.1.269 or later, usage limit go pause the goal with notice wey start with Goal paused. If the session dey wait for the reset, Claude go continue by itself, up to three automatic continuations. But if you close Claude Code, the wait no go restart. Run am inside tmux on VPS so light or data cut no close the session.
Wetin be the difference between /goal and /loop?
/goal start the next turn as soon as the last one finish, and e stop when a small model judge say your condition don hold. /loop run prompt on time interval, with 1 minute minimum, and recurring tasks expire after 7 days. Use /goal for job wey get clear end. Use /loop for checks wey you want on schedule.
How I go continue my goal after light or data cut?
If the session dey inside tmux on VPS, SSH back and run tmux attach-session -t goal. If the session don close, run claude --continue or claude --resume with the session ID. The condition go come back, but turn count, timer and token spend go start from zero. For goal wey you start with claude -p, plain claude --continue go skip am, so use claude --resume with the ID.
Claude Code get --headless or --goal flag?
No. The CLI reference no list --headless or --goal. To run goal without interactive screen, use claude -p "/goal your condition", and add --output-format stream-json --verbose so you fit see each step as e dey run.