A goal is a finish line. You set it once, and Claude keeps working toward it without you prompting each step. After every turn, a separate model checks whether Claude's there, and if not, Claude keeps going.
What you need
Claude Code with
/goal(added in v2.1.139). Runclaude updateif you don't have it.A goal doesn't change your permission mode. If you want it to work unattended, run it in auto mode. On v2.1.283 or later, new sessions start in auto mode. The PERMS guide covers what auto mode does and how to set deny rules first.
How the check works
Each time Claude finishes a turn, Claude Code sends your condition and the conversation so far to a small, fast model. It answers one question: does the condition hold yet?
That checker only reads what's in the chat. So the docs' advice is to "write the condition as something Claude's own output can demonstrate": a file list, a test result, a row count. If Claude doesn't show it, the checker can't see it.
Step 1: write the finish line and the proof
Type /goal, then what's true when it's done, and how Claude proves it:
/goal every file in invoices/ is renamed YYYY-MM-DD-vendor.txt and ls invoices shows it, or stop after 20 turns
The shape is the same every time: the finish line, the proof Claude shows, a cap.
Step 2: cap it
Every turn uses tokens. To bound how long a goal runs, put a turn or time limit in the condition, such as "or stop after 20 turns".
Step 3: check on it, or stop it
Type
/goalon its own to see the condition, how long it's been running, how many turns have been checked, the tokens used so far, and the checker's latest reason./goal clearstops it early./clearremoves it too.
The goals I'd set first
These are examples. Swap in your own folders and file names.
Rename a folder of files:
/goal every file in invoices/ is renamed YYYY-MM-DD-vendor.txt and ls invoices shows it, or stop after 20 turns
Merge spreadsheets:
/goal the CSVs in sales/ are merged into sales-all.csv with a total row, and you show the row count of each input file next to the row count of sales-all.csv, or stop after 15 turns
Sort a messy folder:
/goal every file in Downloads/ sits in a subfolder by type (pdf, images, spreadsheets, other) and ls Downloads shows only those 4 folders, or stop after 15 turns
Make the tests pass (if you code):
/goal npm test passes with 0 failures and you paste the final test summary, or stop after 20 turns
And one that doesn't work:
/goal make the report better
Nothing Claude can show in the chat proves "better", so the checker has nothing to check, and with no cap it keeps spending turns.
The mistake to avoid
A finish line the checker can't see. "The code is clean" or "the summary is good" can't be shown in the chat, so the goal either stops too early or never stops. Name the proof (a file list, a count, a test result) and always add "or stop after N turns".