How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

Here is a working AI agent guardrails example for Claude Code. Use deny rules in .claude/settings.json to block dangerous tools, a PreToolUse hook that exits with code 2 to catch the destructive commands those rules miss, and the --max-turns and --max-budget-usd flags to cap loops and spending. Each layer covers a different failure. Together they let a scheduled run work without someone watching it.

Claude Code's hooks give you, in Anthropic's words, "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." So a guardrail written as a hook doesn't depend on the model remembering an instruction.

Which option is right for you?

The right first guardrail depends on how you run Claude Code today. Start with the row that fits you and add the others later.

Why each pick: deny rules cost nothing and apply to every session. dontAsk keeps unattended runs from stalling. Hooks can match patterns that rules can't. Budget caps stop the one failure you otherwise find out about from your invoice.

What does an AI agent guardrail look like in Claude Code?

In Claude Code, a guardrail is a permission rule, hook script or CLI cap that limits the agent's actions, runtime and spending.

Most guardrail explainers you'll find for this query sort guardrails into input, output and system-level types, then use chatbot examples like PII redaction or bank transfer approvals. That framing works for customer-facing bots. A coding agent running at 3 a.m. fails in other ways, so this guide is organized around three of them:

If you haven't set up hooks before, read Claude Code Hooks Lifecycle: Every Event, Explained first. It shows where PreToolUse and Stop fire.

How do you block destructive commands with permission rules?

Claude Code permission rules go in permissions.allow, ask and deny arrays in .claude/settings.json. Deny rules block matching tool calls before they run.

Step 1: Create the project settings file

1. In your repo root, create .claude/settings.json if it doesn't exist.
2. Paste this starting point and change the commands to match your stack:

{
  "permissions": {
    "allow": [
      "Bash(npm run test *)",
      "Bash(npm run lint *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git commit *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Edit(./.env)"
    ]
  }
}

1. Commit the file so every machine and every scheduled job uses the same rules. The permissions docs note that you "can check permission settings into version control to share them."

Step 2: Get the wildcard right

The trailing turns a rule into a prefix match. The headless docs warn that "the space before is important": Bash(git diff*) would also match git diff-index.

Common mistake: trusting a scoped deny rule to catch every variant

The CLI reference says a scoped rule like Bash(rm ) "denies only calls that match as written." For example, Bash(rm -rf ) won't match rm -r -f build/ or find . -delete. The fix is the hook in the next section, which reads the actual command string and can match several patterns.

Also notice the ask rule for git push. In a -p run with no permission host, the headless docs say requests that would prompt "are denied either way". So in unattended runs, ask effectively means "never". That's usually what you want for pushes.

How do you write a hook that stops dangerous commands?

A Claude Code PreToolUse hook runs before every matching tool call. If the script exits with code 2, the call is blocked. The hooks reference puts it this way: "Exit code 2 is the way a hook signals 'stop, don't do this'."

Step 1: Save the script

Save this as .claude/hooks/block-destructive.sh and run chmod +x on it. It needs jq installed.

#!/bin/bash
# Example guardrail: block destructive shell commands
cmd=$(jq -r '.tool_input.command // empty')

if echo "$cmd" | grep -Eiq \
  'rm +-[a-z]*r[a-z]* *-?[a-z]*f|rm +-r +-f|find .* -delete|git +push .*(--force|-f)|git +reset +--hard|git +clean +-[a-z]*f|drop +(table|database)|terraform +destroy'; then
  echo "Blocked by guardrail: '$cmd' matches a destructive pattern. Use a safer alternative or leave a note for a human." >&2
  exit 2
fi
exit 0

Step 2: Register it

Add a hooks block next to permissions in the same settings file. This follows the structure in the hooks reference:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh"
          }
        ]
      }
    ]
  }
}

Step 3: Verify

1. Start claude in the repo and type /hooks.
2. Check that your script appears under PreToolUse. The costs docs describe the same check for their example hook.
3. Ask Claude to run rm -r -f tmp/ on a throwaway folder. The call should come back blocked.

Common mistakes: the script isn't executable (chmod +x fixes it), jq is missing on the cron host, or the matcher is bash in lowercase. Matchers are tested as JavaScript regular expressions, so case matters (hooks reference). For six more scripts in the same style, see Claude Code Hooks Examples: 7 Copy-Paste Scripts.

How do you stop runaway loops in unattended runs?

Claude Code's --max-turns flag caps agentic turns in print mode. The CLI reference is clear that there is "No limit by default." Set it on every scheduled job.

The cron command

Here is a cron-safe invocation that combines the caps:

claude -p "Run the test suite, fix failing tests in src/, and commit the fix" \
  --permission-mode dontAsk \
  --permission-prompts none \
  --max-turns 30 \
  --max-budget-usd 3.00 \
  --output-format json

What each flag does, per the official docs:

• --permission-mode dontAsk: "Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs" (headless docs). Your allow rules still apply.
• --permission-prompts none: Claude is told that nobody can approve a request and not to retry it, so it doesn't burn turns asking again. This needs v2.1.259 or later (headless docs).
• --max-turns 30: the run "exits with an error when the limit is reached" (CLI reference). Your script can branch on the non-zero exit code.

The number 30 is an example. Pick it by looking at how many turns a normal successful run takes and adding a margin.

A second layer: count tool calls

Turns and tool calls are different things, so a hook that counts tool calls per session gives you a backstop. This example uses session_id, which every hook receives in its input:

#!/bin/bash
# Example: deny tool calls after 150 in one session
input=$(cat)
sid=$(echo "$input" | jq -r '.session_id')
f="/tmp/claude-toolcalls-$sid"
n=$(( $(cat "$f" 2>/dev/null || echo 0) + 1 ))
echo "$n" > "$f"
if [ "$n" -gt 150 ]; then
  echo "Tool-call limit reached. Stop, summarize progress, and list what is unresolved." >&2
  exit 2
fi
exit 0

Register it under PreToolUse with the matcher .* so every tool counts. If runs stop before you expect, work through Why Claude Code Stops Mid-Automation (and How to Fix It). Your own guardrail may be the cause.

Stop hook: don't let it quit while tests fail

A Stop hook can send Claude back to work by returning {"decision": "block", "reason": "..."} (hooks reference). Always check stop_hook_active first, or the hook can bounce Claude back indefinitely:

#!/bin/bash
input=$(cat)
[ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
if ! npm test --silent >/dev/null 2>&1; then
  echo '{"decision":"block","reason":"Tests still fail. Fix them, or explain why they cannot be fixed, before stopping."}'
fi
exit 0

How do you cap Claude Code costs per run?

Claude Code's --max-budget-usd flag stops a print-mode run once estimated API spend reaches your cap. Treat it as a soft cap, not an exact one.

The CLI reference gives two caveats. The cap is checked against a client-side estimate that "can differ from your bill," and "Spend can pass the cap, so leave headroom." Subagent spend counts toward it (CLI reference).

For a sense of scale, Anthropic reports that across enterprise deployments the average is "around $13 per developer per active day". That's an interactive-use average, not a figure for automations, but it's a useful sanity check. A nightly job that costs more than a full day of human use is probably looping.

Practical layers, from cheapest to strongest:

1. Add --output-format json and log total_cost_usd from each run (headless docs). Read the log weekly.
2. Set --max-budget-usd at roughly twice your typical run cost.
3. On API billing, set a workspace spend limit in the Claude Console. The costs docs list "Workspace spend limits" as the cap for Console users.

To find where tokens go in the first place, see Claude Code: How to See Token Usage (and Reduce It).

Which guardrail layer catches which failure?

Claude Code's layers overlap on purpose. No single layer covers everything, so pick by failure mode:

One limitation applies to all of them. A -p session runs the hooks in a project's .claude/settings.json "even in a folder you've never trusted." Only point unattended jobs at repos you control, or use --bare with an explicit --settings file. Also keep a recovery path, because guardrails reduce damage but don't undo it. Claude Code Checkpoints: How Rollback Works in Automations covers what you can roll back.

Next steps

Do today (DIY):

1. Paste the permissions block into .claude/settings.json and commit it.
2. Add block-destructive.sh, register it, and confirm it shows up under /hooks.
3. Add --max-turns and --max-budget-usd to every scheduled claude -p line. The cron setup guide shows where those lines live.

If you'd rather not build this yourself: a Claude subscription doesn't configure guardrails for you, but it does put a hard ceiling on usage. Pro is $20/month and Max starts at $100/month, and Claude Code is included in paid plans (as of October 2026; check claude.com/pricing). A subscription suits solo builders who want predictable monthly spend. It's a poor fit if you need per-run dollar accounting: the costs docs note that the /usage session cost figure "isn't relevant for billing purposes" for Pro and Max subscribers. For per-token control, API billing through the Claude Console with workspace spend limits is the better choice.

Related guides on this site:

• Claude Code Hooks Examples: 7 Copy-Paste Scripts
• Claude Code Hooks Lifecycle: Every Event, Explained
• Why Claude Code Stops Mid-Automation (and How to Fix It)

FAQ

What is an example of an agent in AI?

Claude Code is an example of an AI agent. It reads files, runs shell commands, edits code and decides its next step from the results, all in a loop. That autonomy is what makes guardrails necessary. A chatbot only produces text, while an agent acts on your system.

Is a CLAUDE.md instruction enough as a guardrail?

No. A line like "never force-push" in CLAUDE.md is guidance the model usually follows, not enforcement. Permission rules and hooks are checked by Claude Code itself on every tool call, so use them for anything that would be costly to get wrong.

Should I use bypassPermissions for overnight jobs?

For most solo setups, no. --dangerously-skip-permissions is equivalent to bypassPermissions (CLI reference). dontAsk with explicit allow rules lets routine work through and denies everything else, which is a safer default for runs nobody watches.

Do ask rules work in cron runs?

Not as prompts. In a -p run with no permission host, anything that would prompt is denied (headless docs). Treat ask as "deny when unattended, ask when I'm at the keyboard."

Sources

• Configure permissions – Claude Code Docs
• Hooks reference – Claude Code Docs
• Automate actions with hooks – Claude Code Docs
• Run Claude Code programmatically – Claude Code Docs
• CLI reference – Claude Code Docs
• Choose a permission mode – Claude Code Docs
• Manage costs effectively – Claude Code Docs
• Claude pricing
• AI Guardrails in Agentic Systems Explained – AltexSoft
• 5 Types of AI Guardrails, Examples, and Implementation Best Practices – Cequence
• 8 Best AI Agent Guardrails Solutions in 2026 – Galileo
• GEO: Generative Engine Optimization (arXiv:2311.09735)

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

"Rate limit reached" in Claude Code means one of three things. You sent too many requests or tokens per minute on the API, you used up your subscription's 5-hour or weekly allowance, or you hit a spend cap. Only the first one goes away if you retry. Anthropic's rule for that case is simple: "When the response has a retry-after header, wait that many seconds before retrying" (rate limits docs). For unattended jobs, set CLAUDE_CODE_RETRY_WATCHDOG=1 and add a wrapper that stops on quota or spend errors instead of looping on them.

Which option is right for you?

Pick the row that matches how you run Claude Code. Each row says what to do first and which page to open.

Why these picks: retrying a subscription limit or a spend cap won't work, so beginners should read the reset time first. Cron users need retries that stop on their own. Budget users get more out of a hard cap than a bigger tier.

Which Claude Code rate limit did you actually hit?

You can tell which limit you hit from the wording of the Claude Code message. Each wording has a different cause, and retrying only helps for some of them.

The Claude Code errors reference lists these message families:

At the API level, a 429 has the type rate_limit_error. It covers three cases: a rate limit, your usage tier's monthly spend cap, or a spend limit on the Claude Code workspace (API errors). A 529 overloaded_error is different. The errors reference says a 529 does not count against your quota.

The tier spend cap is the one that catches automations off guard. It comes back as a 429 with error_code: enforced_spend_limit_reached and no retry-after header. The docs warn that "Retrying, including the SDK's automatic retries, fails until access resumes" (rate limits).

How do Claude Code limits differ by plan and API tier?

Claude Code subscriptions use rolling 5-hour and weekly allowances. API keys use per-minute token buckets plus a monthly spend cap.

Subscription plans (Pro, Max, Team, Enterprise)

On Team and Enterprise, each member's usage "draws from a per-seat allowance that resets on a rolling five-hour window and a weekly window" (costs docs). That allowance is shared with Claude chat and Cowork. The same page says session and weekly limits are shared across all models, so switching models with /model only helps after an Opus- or Sonnet-specific message.

Prices (as of October 2026; check the official pricing page): Pro is $20/month, or $17/month billed annually. Max starts at $100/month. Team Standard seats are $25/month billed monthly, and Premium seats are $125/month and give "5x more usage than standard seats." The Free plan doesn't include Claude Code.

When you run out, /usage-credits lets Pro and Max subscribers keep going on usage credits. It doesn't work with API key authentication (costs docs).

API tiers (Claude Console)

API limits are counted in requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute (OTPM), separately for each model class. They are enforced with a token bucket that refills continuously (rate limits):

Three details matter for agents:

• Minute limits can be enforced over shorter intervals. The docs say "Short bursts of requests can exceed the limit and trigger rate limit errors." Five parallel subagents starting at once can trip a limit that a per-minute average says you're under.
• For most models, cached input tokens don't count toward ITPM. A good prompt cache hit rate gives you more effective throughput.
• New organizations may start in an Evaluation tier, with limits below those in the table.

If your team shares one org, Anthropic's costs page suggests 200k–300k TPM and 5–7 RPM per user for teams of 1–5 people.

How do you read Claude Code's rate-limit headers?

Every API response includes anthropic-ratelimit-* headers that show your limit, how much is left and when it refills. A 429 caused by throttling also carries retry-after.

The headers you'll check most often (rate limits):

• retry-after: seconds to wait. Earlier retries will fail.
• anthropic-ratelimit-requests-remaining and -requests-reset (an RFC 3339 timestamp)
• anthropic-ratelimit-input-tokens-remaining / -output-tokens-remaining (rounded to the nearest thousand)
• anthropic-ratelimit-tokens-*: values for whichever limit is tightest right now, including a workspace limit

To see them for your own key, print only the headers. This follows the pattern in the API errors page:

curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}' \
  | grep -iE 'retry-after|anthropic-ratelimit'

Use this rule: a 429 with retry-after is a throttle, so wait that long. A 429 without it, plus enforced_spend_limit_reached, is a spend cap, so stop.

How do you auto-retry 429s in a headless Claude Code cron job?

Claude Code already retries transient failures 10 times with exponential backoff. For cron jobs, add the retry watchdog and a wrapper that exits cleanly when it hits a quota or spend error.

The relevant settings, from the errors reference:

Steps

1. Run claude --version and update if you're below v2.1.295. Older versions ignore the wait cap.
2. Open your job script (see /claude-code-cron-job-setup-run-automations-overnight/ for the crontab side).
3. Export CLAUDE_CODE_RETRY_WATCHDOG=1 and set a wait cap, so one stuck request can't push the job into working hours.
4. Run with -p --output-format json and save stdout to a log. The headless docs say Claude Code "exits with code 0 on success and a non-zero code when the run fails," and that failures inside the run print on stdout.
5. On a non-zero exit, check the log for quota or spend wording before you rerun anything.

Here is an example wrapper. Adjust the paths and the budget to fit your job:

#!/usr/bin/env bash
set -u
export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # 30 min per request

LOG="$HOME/logs/nightly-$(date +%F).json"
claude -p "$(cat "$HOME/jobs/nightly.md")" \
  --output-format json \
  --max-budget-usd 5 \
  --permission-prompts none > "$LOG"
status=$?

if [ "$status" -ne 0 ]; then
  if grep -qiE "spend limit|session limit|weekly limit|credit balance" "$LOG"; then
    echo "$(date) quota/spend stop, not retrying" >> "$HOME/logs/claude-alerts.log"
    exit 2
  fi
  echo "$(date) failed with $status, see $LOG" >> "$HOME/logs/claude-alerts.log"
  exit "$status"
fi

--permission-prompts requires v2.1.259 or later. If you want live retry progress, use --output-format stream-json --verbose and watch for system/api_retry events. Each one includes attempt, max_retries, retry_delay_ms, error_status and an error category such as rate_limit or overloaded (headless docs).

If you'd rather use a hook to log or alert on failures, see /claude-code-hooks-examples-7-copy-paste-scripts/.

Limitation: the wait-and-continue-after-reset feature (v2.1.234+, set with autoContinueAtUsageLimit) is for open interactive sessions on a claude.ai subscription (errors, costs). In a -p cron run, the job ends when it hits a session limit. Schedule the next run after the reset time instead.

Common mistakes and fixes

Most repeat rate-limit failures come from retrying something that can't succeed, or from sending bursts.

• Retrying a spend cap in a loop. Your wrapper keeps firing and nothing gets through. Fix: check for enforced_spend_limit_reached or "spend limit" and exit. At the tier cap, access returns at 00:00 UTC on the first of the next month, or when you request a higher tier (rate limits).
• Expecting a self-set spend limit to return a 429. It returns HTTP 400 invalid_request_error, except on the Claude Code workspace, which can return a 429 with retry-after (rate limits).
• Starting five jobs at the same minute. Bursts trip the per-second enforcement. Fix: spread the crontab entries out (/7, /11) or run jobs one after another.
• Using --bare with a subscription. Bare mode never reads OAuth credentials and needs ANTHROPIC_API_KEY (headless docs).
• Leaving one session open all day. Each request carries the whole conversation. Use /clear between tasks (costs). /claude-code-how-to-see-token-usage-and-reduce-it/ covers this in detail.

Why does Claude Code in VS Code say "API Error: Rate limit reached"?

The Claude Code VS Code extension runs on the same Claude Code installation and sign-in as the CLI (VS Code docs), and its usage is tracked in the same allowance (costs docs), so the causes and fixes above apply.

In the extension, open the Account & usage dialog and use the Day / Week toggle to see what used up your allowance (costs docs). If usage looks low but the error keeps coming back on an API key, check the Console's Rate limits page. A workspace limit set on the "Claude Code" workspace caps Claude Code's share of the org's rate limits, even when the org as a whole has room.

Next steps

Start with the DIY steps below, and only pay for something if they don't solve it.

Do today:

1. Run /usage and note which bar is closest to full and when it resets.
2. Add CLAUDE_CODE_RETRY_WATCHDOG=1 plus a CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS cap to your cron script, and add the spend-limit check.
3. API users: set your own limit under Billing → Spend limits → Adjust limit in the Console.

If you'd rather not manage this yourself: the main official option is more capacity. Claude Max starts at $100/month (as of October 2026; check claude.com/pricing). It suits one person who hits Pro limits on most workdays. It's a poor fit for jobs that need a guaranteed nightly throughput, because the weekly window still applies. For those, an API key on a higher tier (requested via Request tier increase on the Rate limits page) is more predictable, though you pay per token.

Related guides on this site:

• /why-claude-code-stops-mid-automation-and-how-to-fix-it/
• /claude-code-cron-job-setup-run-automations-overnight/
• /claude-code-checkpoints-how-rollback-works-in-automations/

FAQ

What does "claude code rate limit reached error" mean?

You hit one of three limits: per-minute API throttling, your plan's 5-hour or weekly allowance, or a spend cap. The message text tells you which. Only throttles and 529 overloads clear up on retry (errors).

Is "rate limit exceeded" the same as running out of my plan?

Not always. A Request rejected (429) on an API key is usually a per-minute token bucket, which refills continuously. "You've hit your session limit" is a plan allowance with a fixed reset time.

How long until a Claude Code rate limit resets?

API throttles refill continuously. The retry-after header gives the exact number of seconds. Subscription limits show the reset time in the message, and the tier spend cap resets at 00:00 UTC on the first of the next month (rate limits).

Does a 529 overloaded error use up my quota?

No. The Claude Code errors reference says a 529 is not your usage limit and doesn't count against your quota. Retry later, or switch models with /model, since capacity is tracked per model.

Sources

• Rate limits – Claude API docs
• Claude API errors
• Claude Code errors reference
• Claude Code: Manage costs effectively
• Claude Code: Run programmatically (headless)
• Claude Code: Use Claude Code in VS Code
• Claude plans and pricing
• Usage credits for paid Claude plans
• Claude status
• GEO: Generative Engine Optimization (arXiv 2311.09735)

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

Claude Code hooks are shell commands that run at fixed points in a session. Common ones run before a tool call (PreToolUse), after one (PostToolUse), when Claude tries to finish (Stop) and when a session ends (SessionEnd). This guide has seven copy-paste scripts: two guardrails that block dangerous commands and protected files, three stall-prevention hooks (test gate, "waiting for you" alerts, context at startup) and two logging hooks that record every tool call and session. Each script is a small bash file in .claude/hooks/, wired up in .claude/settings.json (Hooks reference).

Which option is right for you?

Start with the one hook that fixes the problem you have today, then add others as you need them.

Why these picks:

• Beginner: a notification hook can't block anything, so if it's wrong, nothing breaks.
• Daily use: guardrails are deterministic. They always run, so you don't depend on the model remembering a rule (Hooks guide).
• Budget: logs show you what the agent actually did before you change plans or prompts.

If you haven't read about the events yet, start with /claude-code-hooks-lifecycle-every-event-explained/.

How hooks are wired: the 60-second version

Every hook is a JSON entry under an event name in a settings file. Claude Code sends event data to the script on stdin, and the script's exit code or JSON output controls what happens next (Hooks reference).

Key facts from the official reference:

• Where: ~/.claude/settings.json (all your projects), .claude/settings.json (project, can be committed) or .claude/settings.local.json (project, gitignored).
• Input on stdin: session_id, transcript_path, cwd, permission_mode, hook_event_name, plus event fields like tool_name and tool_input.
• Exit codes: 0 = success, and any JSON output is applied. 2 = blocking error on events that support blocking. Any other code = non-blocking error, and the action still goes ahead.
• Timeout: 600 seconds by default for command hooks. You can change it with "timeout".
• Matcher: "Bash", "Edit|Write", or a regex. Leave it empty or use "*" to match everything.
• Paths: use ${CLAUDE_PROJECT_DIR} so scripts work from any working directory.

All scripts below need jq to parse the JSON on stdin.

Setup steps (do this once)

1. In your project root, run mkdir -p .claude/hooks .claude/logs.
2. Save each script below into .claude/hooks/ and make it executable: chmod +x .claude/hooks/*.sh.
3. Add the matching JSON block to .claude/settings.json under the top-level "hooks" key. If you use several hooks, merge them into one "hooks" object.
4. In Claude Code, type /hooks. The menu is a read-only browser that shows each hook, its event and which file it came from (Hooks reference).
5. Trigger the event on purpose (for example, ask Claude to run rm -rf /tmp/x) and check that the hook fires.

Guardrail scripts (1–2): stop damage before it happens

Guardrails use PreToolUse, which runs before a tool call and can allow, deny, ask or defer it (Hooks reference).

Script 1: Block destructive shell commands

.claude/hooks/block-dangerous.sh:

#!/usr/bin/env bash
# Example guardrail: deny risky Bash commands before they run.
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$CMD" | grep -Eq 'rm -rf|git push --force|git reset --hard|DROP TABLE'; then
  jq -n --arg c "$CMD" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: ("Blocked by guardrail hook: " + $c)
    }
  }'
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh" }] }
    ]
  }
}

The permissionDecision: "deny" output is the documented way to block a call. If the script prints nothing and exits 0, the normal permission flow applies (Hooks reference). Limitation: pattern matching is easy to get around (for example, rm -r -f). Treat it as a seatbelt, not a sandbox, and keep your normal permission rules too.

Script 2: Protect secrets and lock files

.claude/hooks/protect-files.sh:

#!/usr/bin/env bash
# Example: refuse edits to sensitive paths. Exit 2 = block; stderr is the reason.
FILE=$(jq -r '.tool_input.file_path // empty')
for p in ".env" "package-lock.json" ".git/" "secrets/"; do
  if [[ "$FILE" == *"$p"* ]]; then
    echo "Edits to $FILE are blocked (protected path: $p)." >&2
    exit 2
  fi
done
exit 0

Matcher: "Edit|Write". On PreToolUse, exit code 2 blocks the call, and your stderr message goes to Claude as the reason, so it can change course instead of retrying blindly (Hooks reference).

Stall-prevention scripts (3–5): keep unattended runs moving

These hooks handle the three usual stalls: Claude declaring "done" too early, Claude sitting at a prompt while you're away, and Claude starting without context. For the wider set of causes, see /why-claude-code-stops-mid-automation-and-how-to-fix-it/.

Script 3: Don't let Claude stop while tests fail

.claude/hooks/stop-gate.sh:

#!/usr/bin/env bash
# Example Stop gate: block "done" once if tests fail.
INPUT=$(cat)
# Loop guard: if we already forced a continuation, let Claude stop.
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active // false')" = "true" ]; then
  exit 0
fi
cd "$CLAUDE_PROJECT_DIR" || exit 0
if ! npm test --silent > .claude/logs/last-test.log 2>&1; then
  jq -n '{decision: "block",
          reason: "Tests are failing. Read .claude/logs/last-test.log, fix the failures, then finish."}'
fi
exit 0

"Stop": [
  { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-gate.sh", "timeout": 300 }] }
]

On Stop, decision: "block" with a reason keeps Claude working, and the reason becomes its next instruction (Hooks reference). The stop_hook_active field is true when Claude is already continuing because of a Stop hook. Check it, or you can create a loop that never ends (cubic, claudefa.st). One third-party write-up says Claude Code ends the turn itself after eight blocks in a row (cubic). Don't rely on that. Not for: projects whose test suite takes longer than your timeout. Swap in a faster check such as lint or type-check.

Script 4: Get pinged when Claude is waiting for you

.claude/hooks/notify.sh:

#!/usr/bin/env bash
# Example: log + desktop alert when Claude needs input.
INPUT=$(cat)
MSG=$(echo "$INPUT" | jq -r '.message // "Claude Code needs your input"')
echo "$(date -u +%FT%TZ) $MSG" >> "$CLAUDE_PROJECT_DIR/.claude/logs/waiting.log"
if command -v osascript >/dev/null; then
  osascript -e "display notification \"$MSG\" with title \"Claude Code\""
elif command -v notify-send >/dev/null; then
  notify-send "Claude Code" "$MSG"
fi
exit 0

Put it under the Notification event with matcher "permission_prompt|idle_prompt". Both are documented notification types (Hooks reference). On a headless server the desktop alert does nothing, but waiting.log still shows you where an overnight run got stuck.

Script 5 (bonus context): Brief Claude at session start

.claude/hooks/session-context.sh:

#!/usr/bin/env bash
# Example: give Claude the current repo state at startup.
cd "$CLAUDE_PROJECT_DIR" || exit 0
echo "Branch: $(git branch --show-current)"
echo "Uncommitted files:"; git status --short | head -20
[ -f TODO.md ] && { echo "Open TODOs:"; head -20 TODO.md; }
exit 0

On SessionStart, plain stdout is added to Claude's context. That's different from most events, where it goes to the debug log (cubic). Keep it short: stdout fields are capped at 10,000 characters, and anything longer is saved to a file with only a preview shown (Hooks reference).

Usage-logging scripts (6–7): know what the agent actually did

Logging hooks add one JSON line per event to a file, so you can review a run afterwards without reading the whole transcript.

Script 6: Log every tool call

.claude/hooks/log-tools.sh:

#!/usr/bin/env bash
# Example: one JSON line per tool call.
jq -c '{ts: (now|todate), session: .session_id, tool: .tool_name,
        target: (.tool_input.command // .tool_input.file_path // .tool_input.url // null)}' \
  >> "$CLAUDE_PROJECT_DIR/.claude/logs/tools.jsonl"
exit 0

"PostToolUse": [
  { "matcher": "*",
    "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tools.sh", "async": true }] }
]

"async": true is a documented handler option (Hooks reference). Use it so logging doesn't slow each tool call down.

Script 7: Session summary on exit

.claude/hooks/session-summary.sh:

#!/usr/bin/env bash
# Example: summarize a session when it ends.
INPUT=$(cat)
SID=$(echo "$INPUT" | jq -r '.session_id')
REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"')
LOG="$CLAUDE_PROJECT_DIR/.claude/logs/tools.jsonl"
COUNT=$(grep -c "\"$SID\"" "$LOG" 2>/dev/null || echo 0)
TOP=$(grep "\"$SID\"" "$LOG" 2>/dev/null | jq -r '.tool' | sort | uniq -c | sort -rn | head -3 | tr '\n' ' ')
echo "$(date -u +%FT%TZ) session=$SID reason=$REASON tool_calls=$COUNT top=[$TOP] transcript=$(echo "$INPUT" | jq -r '.transcript_path')" \
  >> "$CLAUDE_PROJECT_DIR/.claude/logs/sessions.log"
exit 0

Register it under SessionEnd. Documented end reasons include clear, logout, prompt_input_exit and other (Hooks reference). Limitation: this counts tool calls, not tokens or cost. For token numbers, use the tools in /claude-code-how-to-see-token-usage-and-reduce-it/.

Common mistakes and fixes

Most broken hooks come down to one of five problems:

For anything else, turn on debug logging. It shows hook runs, full stderr and JSON parse failures (Hooks reference, debug logs). If a hook goes wrong and Claude edits files it shouldn't, /claude-code-checkpoints-how-rollback-works-in-automations/ explains how to roll back.

Next steps

The fastest win is one guardrail and one log today, then a test gate once both are working.

Today, on your own:

1. Add Script 1 and Script 6 to one project, then use /hooks to check both are registered.
2. Run a normal task and read .claude/logs/tools.jsonl afterwards.
3. When it looks right, add Script 3 with your fastest test command.

If you'd rather not build this yourself:

• Claude Academy's "Claude Code in Action": a free course of about one hour and 9 lessons, including using hooks to enforce rules (Skilljar, Class Central). Good if you want structured basics. It isn't for you if you need help with your specific setup, because it's general training.
• Claude Team plan: $25/seat/month, or $20 billed annually (as of October 2026; check the official page). Useful if a small team wants shared project settings, and admins can restrict hooks with managed settings such as allowManagedHooksOnly (Hooks reference). Not worth it for a solo builder: Pro ($20/month, or $17 billed annually, as of October 2026; see Claude pricing) already includes Claude Code. Limitation: no plan writes your hooks for you.

Related guides on this site:

• /claude-code-hooks-lifecycle-every-event-explained/
• /why-claude-code-stops-mid-automation-and-how-to-fix-it/
• /claude-code-cron-job-setup-run-automations-overnight/

FAQ

Where do I put Claude Code hooks?

Put them in .claude/settings.json for a project you share, .claude/settings.local.json for personal project hooks, or ~/.claude/settings.json for all your projects. The scripts themselves can live anywhere, but .claude/hooks/ plus ${CLAUDE_PROJECT_DIR} keeps paths reliable (Hooks reference).

How do I block a command with a hook?

Use a PreToolUse hook that either prints JSON with permissionDecision: "deny" or exits with code 2 and a reason on stderr. Both stop the tool call, and Claude sees the reason (Hooks reference).

Why does my Stop hook make Claude loop forever?

The hook blocks every stop, even after Claude has already been forced to continue. Read stop_hook_active from stdin and exit 0 when it's true (cubic).

Do hooks slow Claude Code down?

Synchronous hooks run inline, and command hooks can run for up to 600 seconds by default. Keep checks fast, set a lower timeout, and mark logging hooks "async": true (Hooks reference).

Sources

• Hooks reference – Claude Code Docs
• Automate actions with hooks (Hooks guide) – Claude Code Docs
• Permissions – Claude Code Docs
• Debug logs – Claude Code Docs
• Claude Code hooks: every event, with examples – cubic
• Claude Code Stop Hook: Force Task Completion – claudefa.st
• Claude pricing
• Claude Code in Action – Anthropic Courses
• Claude Code in Action – Class Central
• jq

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

To see token usage in Claude Code, type /usage in an interactive session. The Session block lists your input, output and cache tokens per model, plus an estimated dollar total (Claude Code docs: Manage costs). For headless runs, add --output-format json to claude -p. The result then includes total_cost_usd and a cost breakdown per model, so a script can log every run (Run Claude Code programmatically). For the real bill on an API key, check the Usage page in the Claude Console. Claude Code's own figures are client-side estimates.

Which option is right for you?

The right place to check depends on how you pay and whether anyone watches the run.

• Beginner: /usage needs no setup. It is the quickest way to learn what a normal session costs you.
• Daily work: on a subscription, the dollar figure doesn't affect your bill. The plan bars and the attribution breakdown are what show how fast you're using your limits.
• Budget: a spend limit in the Console is enforced by Anthropic. Local estimates can't cap anything.

How to read /usage (and where /cost went)

/usage is the in-session command for token and cost numbers. Current docs describe everything under it.

The changelog still names /cost in recent entries, such as the v2.1.296 note about cache-read pricing (changelog). If /cost doesn't do what an older tutorial says, use /usage.

Steps

1. Start a session with claude and do some work.
2. Type /usage and press Enter. It runs right away, even while Claude is responding (Commands).
3. Read the Session block: Total cost, Total duration (API), Total duration (wall), Total code changes, and Usage by model. Usage by model shows input, output, cache-read and cache-write tokens for each model (Manage costs).
4. On v2.1.251 or later, check the Prompt cache (main) line. It shows the share of input tokens that came from cache and the number of cache misses. A high miss count usually means you paid full price to re-read context.
5. On a Pro, Max, Team or Enterprise plan, scroll to the breakdown. It shows usage split across skills, subagents, plugins and MCP servers, and flags any behavior that accounts for 10% or more of recent usage. Press d or w to switch between 24 hours and 7 days.

What the numbers mean

• The dollar figure is calculated locally at list price. It is an estimate, not an invoice (Manage costs).
• On a subscription, the Session cost line doesn't matter for billing. The plan bars do.
• /usage reads local session history only. Usage from other machines or claude.ai is not included.
• The token count next to the spinner (for example ↓ 5.5k tokens) counts only the output of the current turn. It will never match the session totals.

Common mistakes and fixes

• "My total went back to $0." /clear starts a new session and resets the Session block (v2.1.211 and later). Note the number before you clear.
• "/usage shows old bars." If the usage endpoint is rate-limited, you'll see Showing last-known usage. Press r to retry.
• "The cost doesn't match my bill." That's expected. Use the Console Usage page for the real figure.

How to track token burn in headless runs

For unattended work, ask for JSON output on every claude -p call and keep a log of total_cost_usd.

Steps

1. Add --output-format json:

``bash claude -p "Summarize open TODOs in src/" --output-format json | jq '.total_cost_usd' ` The payload contains result, session_id, total_cost_usd` and a per-model cost breakdown (headless docs).

1. Add a hard stop with --max-budget-usd 5.00. The run stops once estimated spend reaches the cap, and spend from subagents counts toward it. Spend can go past the cap, so leave some headroom (CLI reference).
2. Add --max-turns to stop runaway loops. When the limit is hit, the run exits with an error.
3. In CI, add --bare. It skips loading hooks, plugins, MCP servers and CLAUDE.md, which keeps startup context small and predictable. Bare mode does not use your subscription login, so set ANTHROPIC_API_KEY (headless docs).

Example: a cost-logging wrapper

This is an illustrative script, not an official tool. Change the paths and limits to suit your setup.

#!/usr/bin/env bash
# run-claude.sh "<prompt>"
ALERT_AT=2.00
out=$(claude -p "$1" --output-format json --max-budget-usd 3.00 --max-turns 30) || status=$?
cost=$(echo "$out" | jq -r '.total_cost_usd // 0')
sid=$(echo "$out" | jq -r '.session_id // "none"')
echo "$(date -u +%FT%TZ),$sid,$cost,${status:-0}" >> "$HOME/claude-costs.csv"
if (( $(echo "$cost > $ALERT_AT" | bc -l) )); then
  echo "Claude run $sid cost \$$cost (alert at \$$ALERT_AT)" >&2
  # send to a channel you own, e.g. curl -X POST "$YOUR_WEBHOOK_URL" -d "..."
fi

The script still logs when the run fails, because || status=$? stops a non-zero exit from killing it. Failed runs still use tokens, and the SDK docs note that error results carry cost too (Track cost and usage). To schedule the script, see Claude Code Cron Job Setup: Run Automations Overnight. If runs stop early because of --max-turns, read Why Claude Code Stops Mid-Automation (and How to Fix It).

Common mistakes and fixes

• Summing totals across --resume runs. A resumed run reports the whole conversation's total, including earlier runs (headless docs). Take the latest value. Don't add them up.
• Trusting usage for subagent-heavy jobs. The usage field leaves out subagent tokens. total_cost_usd and modelUsage include them (Track cost and usage).
• Billing customers from these fields. Anthropic says not to. They are client-side estimates.

How to wire usage checks into hooks

Hooks are good for cutting tokens, but they can't produce a per-run cost alert on their own. According to the hooks reference, Stop and SessionEnd hooks receive session_id, transcript_path, cwd and a reason, but no token or cost data.

What does work:

1. Alerting: put the cost check in the wrapper script above, which runs after the -p process exits. The cost figure exists there and nowhere else.
2. Resume warnings: per the hooks reference, a SessionStart hook that fires on resume receives context_tokens, estimated_cache_write_usd and prompt_cache_likely_expired. You can log these, or warn yourself before an expensive cold-cache resume.
3. Cutting tokens with PreToolUse: the costs page includes an official PreToolUse hook on Bash. It rewrites npm test, pytest or go test so that only failure lines reach Claude. Anthropic's example says this kind of filtering can shrink context "from tens of thousands of tokens to hundreds" (Manage costs). To check it's active, run /hooks and look under PreToolUse.
4. Live view: a custom status line receives session cost data and can show it all the time (Status line).

For a map of every hook event and when each one fires, see Claude Code Hooks Lifecycle: Every Event, Explained.

Limitation: --bare skips hooks. If your CI runs use bare mode, a PreToolUse filter in ~/.claude won't run. Pass the settings with --settings instead (headless docs).

Where to see real billing: Console and APIs

For money you are actually charged on an API key, the Claude Console is the source of truth.

• Usage page: go to platform.claude.com/usage for usage over time. When you first sign in to Claude Code with a Console account, a Claude Code workspace is created automatically to keep that traffic separate (Workspaces).
• Spend limits: open Settings → Workspaces, select the workspace, then click Spend limits. This caps monthly spend and can alert you at thresholds you choose. You can't set limits on the Default Workspace (Workspaces).
• Rate limits: on the Rate limits page, choose the workspace from the Workspace dropdown and click Edit next to a model (Workspaces).
• Usage and Cost Admin API: /v1/organizations/usage_report/messages (buckets of 1m, 1h or 1d) and /v1/organizations/cost_report (daily). Both need an Admin API key, and the Admin API is not available to individual accounts. Data usually appears within 5 minutes (Usage and Cost API).
• OpenTelemetry: set CLAUDE_CODE_ENABLE_TELEMETRY=1 to export claude_code.cost.usage and claude_code.token.usage to your own backend (Monitoring). This is worth it if you already run Grafana or similar. It's overkill for one laptop.

How to reduce token usage

Most token waste comes from context you no longer need. Anthropic lists these levers (Manage costs):

• Run /clear between unrelated tasks. It costs nothing. /compact has to read the whole conversation to summarize it, so it is itself a large request.
• Use Sonnet by default. Save Opus for hard reasoning. Set model: haiku for simple subagents. Leaving Opus as the default is one of the two most common causes of surprise spend Anthropic names; long sessions that never get cleared are the other.
• Keep CLAUDE.md under about 200 lines. Move workflow-specific instructions into skills, which load only when needed.
• Prefer CLI tools such as gh over MCP servers where possible. Turn off unused servers in /mcp, and run /context to see what's taking up space.
• Lower the effort level with /effort on simple jobs. Thinking tokens are billed as output.
• Be careful with agent teams. In plan mode they use about 7x the tokens of a standard session.
• Watch idle costs. Scheduled /loop tasks resend your full context on every run. Background work, such as summarizing past conversations for --resume, typically costs under $0.04 per session.

For context: across enterprise deployments, Anthropic reports an average of about $13 per developer per active day, and under $30 for 90% of users (Manage costs). Your numbers will differ, so measure your own first.

Next steps

DIY today:

1. Run /usage at the end of your next session and write down the total and the Prompt cache hit share.
2. Put --output-format json --max-budget-usd on one recurring claude -p job and log total_cost_usd to a CSV.
3. If you use an API key, set Spend limits on the Claude Code workspace in the Console.

If you'd rather not manage per-token billing yourself: a Claude subscription replaces per-token bills with plan limits. Pro is $20/month billed monthly, and Max starts at $100/month. Both include Claude Code (as of October 2026; check the official pricing page).

• Suits: people who mainly work interactively and want a predictable monthly cost.
• Not for: CI or --bare jobs that need an API key, or anyone who needs exact per-run invoices.
• Limitations: plan usage resets on a rolling five-hour window and a weekly window, and going past the limit requires usage credits (Claude pricing).

Related guides on this site:

• Claude Code Cron Job Setup: Run Automations Overnight
• Claude Code Hooks Lifecycle: Every Event, Explained
• Claude Code Checkpoints: How Rollback Works in Automations

FAQ

Does Claude Code still have a /cost command?

Current documentation puts session token and cost figures under /usage, though the changelog still mentions /cost in recent entries. If /cost behaves differently from an old guide, run /usage. You'll find the same Session block there.

How do I see token usage for claude -p runs?

Add --output-format json and read total_cost_usd with jq. For live events, use --output-format stream-json --verbose; the last line is a result message that includes the cost (headless docs).

Why doesn't the /usage cost match my bill?

Claude Code calculates the figure locally at list price. Pricing changes and billing rules it can't model make the two drift apart. Use the Console Usage page or the Usage and Cost API for the real numbers.

Can a hook stop Claude Code when it gets too expensive?

Not directly, because Stop and SessionEnd hooks don't receive cost data. Use --max-budget-usd for a hard cap on headless runs, and a Console spend limit for a cap Anthropic enforces.

Do Pro and Max users need to watch token costs?

Not in dollars, since usage is included in the plan. Do watch the plan bars and the 24h/7d breakdown in /usage, because long contexts and cache misses use up your limits faster.

Sources

• Manage costs effectively – Claude Code Docs
• Run Claude Code programmatically – Claude Code Docs
• CLI reference – Claude Code Docs
• Commands – Claude Code Docs
• Hooks reference – Claude Code Docs
• Customize your status line – Claude Code Docs
• Monitoring usage (OpenTelemetry) – Claude Code Docs
• Track cost and usage – Agent SDK Docs
• Claude Code changelog
• Usage and Cost API – Claude Platform Docs
• Workspaces – Claude Platform Docs
• Claude Console Usage page
• Claude pricing

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

Claude Code hooks are shell commands, HTTP calls, MCP tools or model prompts that run at fixed points in a session. A run starts with SessionStart, loops through UserPromptSubmit → PreToolUse → PostToolUse/PostToolUseFailure → PostToolBatch for each step, ends each turn with Stop (or StopFailure when the API errors), and finishes with SessionEnd (Hooks reference). Four of these events do most of the work in unattended automations. PreToolUse, PostToolBatch and Stop can halt runaway work. StopFailure reports runs that died quietly.

Which option is right for you?

Choose your first hook based on the problem you have now. The table below matches common situations to an event.

Why each pick makes sense:

• Beginner: a notification hook can't block anything, so a mistake in it won't break your session.
• Daily use: you can block at PreToolUse and PostToolBatch before the next model call, so you stop the spending instead of just recording it (reference).
• Unattended runs: StopFailure matches error types such as rate_limit and billing_error, which otherwise show up as a quiet exit (reference).
• Budget: prompt hooks send text to a model and agent hooks run a subagent, so both use model calls. Command hooks are just your own scripts and cost nothing extra.

The lifecycle of one automation run, in order

Every hook event belongs to a phase of the run. Knowing the phase tells you whether a hook can still change the outcome. The table follows the official reference, which currently lists more than 30 events (Hooks reference).

The reference also lists events for tasks, teams, worktrees, model switches, MCP elicitation and file changes, such as TaskCompleted, TeammateIdle and FileChanged. Most solo setups don't need them on day one (reference).

Three timing facts that matter

• All matching hooks run in parallel, so you can't rely on one hook finishing before another starts (reference).
• Default timeouts differ by event. Most hooks get 600 seconds, UserPromptSubmit gets 30, and all SessionEnd hooks share a 1.5-second budget that can be raised to at most 60 seconds (reference). Keep cleanup work at session end small.
• Hooks from different places add up. User, project, local, plugin, skill and subagent hooks all run; a lower level doesn't replace a higher one (reference).

Which hooks actually stop runaway token use

Only hooks that fire before the next model call can stop a runaway run. In practice that means PreToolUse, PostToolBatch, UserPromptSubmit and the universal continue: false field. Logging hooks like PostToolUse only record what already happened.

The kill switch: continue: false

Any hook can return JSON with "continue": false. The reference says this "stops Claude entirely," and stopReason explains why (reference). It's the most reliable way for an unattended run to stop itself.

PostToolBatch: the per-step budget checkpoint

PostToolBatch fires after a whole batch of tool calls resolves and before Claude makes its next model call (reference). That makes it a good place to count steps. For example, a script could keep a counter file in the session's scratchpad_dir (an input field available from v2.1.257; see the Hooks reference and Claude Code changelog). Once the count passes a limit you choose, it returns:

{ "continue": false, "stopReason": "Step budget of 80 tool batches reached. Stopping for review." }

The number 80 is only an example. Choose a limit based on how many steps your normal runs take.

PreToolUse: block the expensive call itself

PreToolUse returns permissionDecision with the value allow, deny, ask or defer. It can also rewrite the call with updatedInput (reference). Use a matcher such as Bash or mcp__. and the if field (for example "Bash(git )") so the hook only runs on the calls you care about. One limitation: deny blocks that one call, and Claude may try a different approach afterwards. Pair it with a counter if you want the run to end.

Stop: useful, but it can add usage

When a Stop hook exits with code 2, Claude doesn't stop and the conversation keeps going (reference). That's helpful for checks like "tests must pass before you're done." It's also the most common cause of loops that burn usage. Your hook should check the stop_hook_active input field, which is true when Claude is already continuing because a Stop hook blocked it. If it's true, exit 0 (Amit Kothari, claudefa.st). A GitHub issue (#54360) reports cases where the flag didn't propagate, so add a hard cap as well. For example, allow at most 3 blocks per session.

PreCompact: an early warning about long runs

PreCompact with the auto matcher fires before automatic compaction and can block (reference). If a routine job hits auto-compaction, it has probably grown larger than you meant it to. Logging it is a cheap signal.

Which hooks catch silent failures

Silent failures show up in four events: PostToolUseFailure, StopFailure, Notification and SessionEnd. None of them can block. Their job is to tell you something went wrong.

• StopFailure fires when a turn ends because of an API error. Its matcher accepts values like rate_limit, overloaded, authentication_failed, billing_error and max_output_tokens (reference). Send yourself a message on these. Without it, a cron run that hit a rate limit looks the same as one that completed. For more on why runs stop, see /why-claude-code-stops-mid-automation-and-how-to-fix-it/.
• PostToolUseFailure fires after any failed tool call. Write those failures to a file so you can check them in the morning.
• Notification with idle_prompt or permission_prompt tells you the run is stuck waiting for a human (reference).
• SessionEnd reports the reason the session ended (clear, logout, prompt_input_exit, other). Keep it quick because of the 1.5-second default budget.

Hook failures can be silent too. If a command hook exits with code 1 or 3+, that's a non-blocking error: only the first line of stderr appears as a notice (reference). From v2.1.295 you can set "onFailure": "block" so a broken safety hook stops the run instead of letting it continue unchecked (reference, changelog).

Set up your first lifecycle hook

Start with a project-level Stop guard plus a StopFailure logger. Together they cover both runaway loops and quiet failures.

1. Choose the file. Use .claude/settings.json to share hooks with your repo, .claude/settings.local.json for hooks only you use (gitignored), or ~/.claude/settings.json for all your projects (reference).
2. Add a hooks block. Example:

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-guard.sh" } ] }
    ],
    "StopFailure": [
      { "matcher": "rate_limit|billing_error|server_error",
        "hooks": [ { "type": "command",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/alert.sh" } ] }
    ]
  }
}

1. Write stop-guard.sh. It reads JSON from stdin. As the first thing it does, it exits 0 if stop_hook_active is true. After that it runs your check, such as tests, and exits 2 with a reason on stderr if the check fails.
2. Make scripts executable with chmod +x .claude/hooks/*.sh.
3. Verify. Type /hooks in Claude Code to open the read-only hook browser. Select All events to confirm each hook appears with its source (user, project, local, plugin, skill or subagent) (reference). The file watcher normally picks up direct edits to settings files without a restart.
4. Test with a small prompt before you hand the hook to a scheduled run. To schedule it afterwards, see /claude-code-cron-job-setup-run-automations-overnight/.

Common mistakes and fixes

Most hook problems come from a short list of misunderstandings.

If you want to undo the file edits a run made, rather than prevent them, see /claude-code-checkpoints-how-rollback-works-in-automations/.

Next steps

You can have useful guards in place today with three small changes.

Do it yourself today:

1. Add the Stop guard and StopFailure alert from the steps above to one project.
2. Add a PostToolBatch step counter that returns continue: false at a limit you choose.
3. Run /hooks, select All events, and confirm what's actually active, including hooks from plugins.

If you'd rather not do it yourself: a paid plan doesn't write hooks for you, but it's required to run Claude Code. Claude Code is included in all paid plans and shares your plan's usage limits. Pro costs $20/month or $17/month billed annually, Max starts at $100/month, and Team Standard seats cost $25/month monthly or $20 annually (as of October 2026; check the official page). Pro suits solo builders running a few jobs a day. It doesn't suit long nightly multi-agent runs, which can hit the limits. Max gives you more usage but doesn't fix a hook that loops. If you'd rather hire someone, a freelance consultant can set up hooks for you. Give them the Hooks reference as the spec, and make sure you understand every script before it runs unattended.

Related guides on this site:

• /why-claude-code-stops-mid-automation-and-how-to-fix-it/
• /claude-code-checkpoints-how-rollback-works-in-automations/
• /claude-code-cron-job-setup-run-automations-overnight/

FAQ

What is the order of Claude Code hook events?

A typical run goes SessionStart → UserPromptSubmit → PreToolUse → PostToolUse/PostToolUseFailure → PostToolBatch, and the tool steps repeat until Stop or StopFailure. SessionEnd fires when the session closes. Compaction, subagent and notification events fire in between as needed (reference).

Which Claude Code hook can block an action?

PreToolUse, UserPromptSubmit, PostToolBatch, Stop, SubagentStop, PreCompact, ConfigChange and several task, worktree and elicitation events can block with exit code 2 or a JSON decision. SessionStart, Notification, StopFailure and SessionEnd can't (reference).

How do I stop a Claude Code Stop hook from looping?

Read stop_hook_active from the hook's stdin and exit 0 when it's true. Because of a reported propagation bug, also keep a per-session counter and allow the stop after a few blocks (issue #54360).

Where do I put Claude Code hooks?

Put them in ~/.claude/settings.json (all projects), .claude/settings.json (shared project), .claude/settings.local.json (personal project), plugin hooks/hooks.json, or skill and subagent frontmatter. Hooks from all of these locations run together (reference).

Do prompt or agent hooks cost extra?

They use model calls. prompt hooks send text to a model, and agent hooks start a subagent (marked experimental), so they count toward your plan's usage (reference, pricing). Use command hooks for checks that don't need judgment.

Sources

• Hooks reference – Claude Code Docs
• Automate actions with hooks – Claude Code Docs
• Intercept and control agent behavior with hooks – Agent SDK Docs
• Claude Code changelog – GitHub
• Claude pricing
• GitHub issue #54360: Stop hook fires repeatedly (stop_hook_active not propagating)
• How Claude Code stop hooks work – Amit Kothari
• Claude Code Stop Hook: Force Task Completion – claudefa.st

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

To set up a Claude Code cron job, you need two pieces. The first is a wrapper script that sets PATH, loads a token, cds into your project and runs claude -p with explicit permissions and limits. The second is one crontab line that runs that script under a lock and sends its output to a log file. Most "silent" overnight failures come from what cron does not give you: your shell's environment, your login, your project directory and a place to see errors. This guide covers each of those gaps, plus the scheduling options Anthropic offers if you don't want to manage cron yourself.

Should you use cron, or a built-in Claude Code scheduler?

Use cron when the job needs your machine's local files and tools and you want full control. Use Anthropic's built-in options when you'd rather not maintain a server. Claude Code now has three of its own scheduling options, and the official comparison shows how they differ:

How to choose:

• Routines suit you if your work lives in GitHub and should run while your laptop is closed. They're available on Pro, Max, Team and Enterprise plans (source, as of October 2026). Not for you if the job needs files outside a repo, local databases, or tools you can't install from a setup script. The docs also note that routines are in research preview and that a green run status "does not mean the task in your prompt succeeded" (source).
• Desktop scheduled tasks suit people who keep the Claude Desktop app open on a work machine. Not for you if the machine sleeps overnight. If it sleeps through a scheduled time, the run is skipped, and on wake only one catch-up run happens (source).
• /loop is for polling during a session you have open. Recurring tasks expire seven days after you create them (source), so it can't replace cron.
• Cron fits an always-on Linux box, VPS or home server where you want plain files, plain logs and no extra platform.

The rest of this guide is about the cron route.

Trap 1: authentication that works in your terminal but not in cron

Your cron job needs a credential passed in explicitly through an environment variable, because the login in your interactive terminal may not reach it. Claude Code's authentication docs list two common options for scripts:

• Subscription token: run claude setup-token once. It opens the browser flow and prints a one-year OAuth token without saving it anywhere. Set that token as CLAUDE_CODE_OAUTH_TOKEN. It requires a Pro, Max, Team or Enterprise plan (source, as of October 2026), and it can only make model requests, so claude.ai connectors won't work with it.
• API key: set ANTHROPIC_API_KEY to a key from the Claude Console. Usage is billed to your API account instead of your subscription. In -p mode, the key "is always used when present" (source).

Two details often cause trouble:

1. Precedence. ANTHROPIC_API_KEY ranks above CLAUDE_CODE_OAUTH_TOKEN (source). If both exist, you are billed through the API key, which may not be what you intended.
2. --bare ignores the OAuth token. Bare mode is recommended for scripts, but it "does not read CLAUDE_CODE_OAUTH_TOKEN". With --bare, use ANTHROPIC_API_KEY or an apiKeyHelper instead (source).

Why this fails silently: when a failure happens inside the run, "such as missing authentication, Claude Code prints the failure as the result on stdout" (source). If you throw stdout away, the error disappears with it. Check the exit code too: Claude Code exits with a non-zero code when a run fails.

Trap 2: PATH and the minimal cron environment

Cron runs your command in a much smaller environment than your terminal, so set every variable the job needs inside the script itself. The crontab(5) man page says cron sets SHELL to /bin/sh and takes LOGNAME and HOME from /etc/passwd. Anything your ~/.zshrc or ~/.bashrc adds is not guaranteed to be there.

That matters for Claude Code because the native installer puts the launcher at ~/.local/bin/claude (source), and that directory is often added to PATH only by your shell profile. The tools Claude calls during the run also need to be found: node, git, gh, npm and so on.

Practical fixes:

• Use the absolute path to claude (run which claude in your terminal to find it), or export a full PATH at the top of the script.
• Keep secrets in a dedicated env file with chmod 600, and load it in the script. Don't paste them into the crontab.
• Watch for % in crontab lines. Unless escaped, cron turns it into a newline and sends the rest of the line to standard input (source). That breaks date +%F inline, so put date formatting in the script.
• Cron uses the system timezone unless you set CRON_TZ (on cron implementations that support it, such as cronie, per the crontab(5) man page).

Trap 3: the working directory decides what Claude loads

Always cd into the project explicitly, because the folder a -p run starts in decides which configuration and instructions it loads. Without --bare, claude -p "loads the same context an interactive session would, including anything configured in the working directory or ~/.claude". That includes CLAUDE.md, the hooks in .claude/settings.json and the MCP servers in .mcp.json (source).

Two consequences:

• Wrong directory, wrong behavior. If the job starts somewhere else, Claude won't see your project's CLAUDE.md or settings, and relative paths in your prompt point to the wrong files.
• No trust dialog. A -p session "shows no workspace trust dialog and no per-server approval prompt", so project hooks and MCP servers run even in a folder you've never trusted (source). Only point cron at repositories you control.

If you want the same result on every run no matter what's in ~/.claude, use --bare and pass context explicitly with --append-system-prompt-file, --settings and --mcp-config (source). The trade-off is that you then need an API key (see Trap 1).

Trap 4: permissions in a run nobody is watching

Set the permission mode and the allowed tools explicitly, because no one is awake to answer a prompt. The docs warn that a run with no permission mode set takes a built-in starting mode, "which can be auto, so pass the one you want" (source).

Options from the headless docs and the CLI reference:

• --permission-mode dontAsk denies anything that would prompt, while reads and your --allowedTools entries still run. This is a good default for locked-down jobs.
• --allowedTools "Read,Edit,Bash(npm test )" grants narrow, prefix-matched commands. The space before matters: Bash(git diff*) would also match git diff-index.
• --permission-prompts none tells Claude that nobody can approve requests and not to retry denied ones. It requires v2.1.259 or later.
• --max-turns caps agentic turns. There is no limit by default.
• --max-budget-usd stops the run at an estimated spend. It's a client-side estimate, and spend can go past the cap, so leave headroom.

Avoid --dangerously-skip-permissions for overnight jobs unless the machine is a disposable sandbox.

Putting it together: script, crontab, lock and log rotation

The setup has four parts: a wrapper script, a crontab line with flock, structured logs, and rotation so the logs don't fill your disk. Everything below is an example. Change the paths, prompt and tool list to fit your project.

Step 1: the wrapper script

#!/usr/bin/env bash
# ~/bin/claude-nightly.sh  (example)
set -uo pipefail

export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
set -a; source "$HOME/.config/claude-cron/env"; set +a   # holds CLAUDE_CODE_OAUTH_TOKEN=...
unset ANTHROPIC_API_KEY   # avoid accidental precedence over the token

cd "$HOME/projects/myapp" || { echo "cd failed"; exit 1; }

LOG_DIR="$HOME/logs/claude-cron"
mkdir -p "$LOG_DIR"
STAMP=$(date +%Y-%m-%dT%H%M)
OUT="$LOG_DIR/run-$STAMP.json"

claude -p "$(cat .claude/nightly-prompt.md)" \
  --permission-mode dontAsk \
  --permission-prompts none \
  --allowedTools "Read,Edit,Bash(npm test *),Bash(git status *),Bash(git diff *)" \
  --max-turns 30 \
  --max-budget-usd 3 \
  --output-format json > "$OUT" 2> "$LOG_DIR/run-$STAMP.err"
STATUS=$?

echo "$(date -Is) exit=$STATUS cost=$(jq -r '.total_cost_usd // "n/a"' "$OUT" 2>/dev/null)"
[ "$STATUS" -eq 0 ] || echo "FAILED: $(jq -r '.result // empty' "$OUT" 2>/dev/null | head -c 500)"
exit "$STATUS"

Why these choices: --output-format json gives you result, session_id and total_cost_usd in a form a script can parse (source). Branching on the exit code catches failed runs. Keeping the prompt in a file means you can version-control it.

Step 2: the crontab line

Run crontab -e:

SHELL=/bin/bash
MAILTO=""
7 2 * * * /usr/bin/flock -n /tmp/claude-nightly.lock $HOME/bin/claude-nightly.sh >> $HOME/logs/claude-cron/cron.log 2>&1

flock -n makes the job "fail rather than wait if the lock cannot be immediately acquired" (flock(1)). If last night's run is still going, a second copy won't start on top of it. Cron mails command output to the crontab owner or to MAILTO (cron(8)). Since this setup sends output to a file, set MAILTO="" so cron doesn't also try to send mail.

Step 3: log rotation

Rotate the summary log with logrotate, and prune the per-run files with find. An example /etc/logrotate.d/claude-cron:

/home/you/logs/claude-cron/cron.log {
    weekly
    rotate 8
    compress
    missingok
    notifempty
    copytruncate
}

copytruncate truncates the file in place after copying it, so the >> in your crontab keeps writing to the same file. missingok and notifempty skip missing or empty logs (logrotate(8)). For the per-run JSON files, add a second cron line such as 0 4 0 find $HOME/logs/claude-cron -name 'run-*' -mtime +30 -delete.

Claude Code also saves session transcripts on disk. If you never resume these runs, --no-session-persistence stops them from being saved (source).

Step 4: test it under cron conditions

Before you trust the schedule, run the script in an environment as bare as cron's: env -i HOME="$HOME" /bin/sh -c '$HOME/bin/claude-nightly.sh'. Then schedule it a few minutes ahead and read cron.log and the JSON file. Also run claude auth status inside the script once: it reports which authMethod is active and exits 1 if you're not logged in (source).

Keeping overnight jobs healthy over time

Plan for updates, token expiry and alerting from the start, because these cause failures weeks after setup rather than on day one.

• Updates: native installs update automatically in the background (source). If you want a predictable version for scheduled jobs, set "autoUpdatesChannel": "stable", or set DISABLE_AUTOUPDATER=1 in your settings and update yourself.
• Token expiry: the setup-token token lasts one year (source). Put a renewal reminder in your calendar.
• Alerting: a failing exit code that only reaches a log file is still silent. For example, you could add a line to the script that sends the FAILED: message to a Slack webhook or a health-check service when the run fails.
• Read the output, not just the status: as with routines, a clean exit means the process finished, not that the task was done well. Check the result text now and then.

FAQ

Can Claude Code run on a schedule without my computer on?

Yes, through Routines, which run on Anthropic-managed cloud infrastructure on hourly, nightly or weekly schedules (source). They work from a fresh clone of your GitHub repositories, so they can't see local files. The minimum interval is one hour, and the feature is in research preview.

Why does my Claude Code cron job work manually but not from cron?

Usually cron's environment is missing something your terminal has: ~/.local/bin on PATH, an exported token, or the project directory. Use absolute paths, load credentials from a file, and cd explicitly. Capture stdout, because Claude Code prints failures such as missing authentication there (source).

Should I use CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY for cron?

Use CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) if you want runs to count against your Claude subscription. Use ANTHROPIC_API_KEY if you want API billing, or if you run with --bare, which ignores the OAuth token (source). Don't set both, because the API key takes precedence.

How do I stop a scheduled Claude run from costing too much?

Combine --max-turns with --max-budget-usd, and log total_cost_usd from the JSON output. The budget cap uses a client-side estimate and spend can go past it, so set it below your real limit (source).

How do I prevent overlapping Claude cron runs?

Wrap the command in flock -n with a lock file. A new run then exits right away if the previous one still holds the lock (flock(1)).

Sources

• Run Claude Code programmatically (headless) – Claude Code Docs
• CLI reference – Claude Code Docs
• Authentication – Claude Code Docs
• Advanced setup – Claude Code Docs
• Run prompts on a schedule – Claude Code Docs
• Automate work with routines – Claude Code Docs
• Schedule recurring tasks in Claude Code Desktop – Claude Code Docs
• crontab(5) – Linux manual page
• cron(8) – Debian manpages
• flock(1) – Linux manual page
• logrotate(8) – Linux manual page

Originally published at Unattended.

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

In interactive Claude Code, checkpoints are on by default, and you undo with /rewind or by pressing Esc twice when the prompt is empty. Headless runs (claude -p or the Agent SDK) have nobody to press that key. You have to turn file checkpointing on, save the first user-message UUID and the session ID, and have your script call rewindFiles() / rewind_files() or run claude -p --resume <session-id> --rewind-files <checkpoint-uuid>. Rewind only restores edits made with Write, Edit and NotebookEdit. It doesn't cover Bash, most subagent edits or directories, so git stays your main safety net.

Which option is right for you?

Your setup depends on what the job does: rewind fully covers only jobs that edit files through Claude's own edit tools.

If you're not sure, start every run on a clean git commit or in a worktree, and treat rewind as a convenience on top.

A detail people often miss: --permission-mode acceptEdits also auto-approves common filesystem commands such as mkdir, touch, mv and cp (Headless docs). Those run through Bash, so rewind can't undo them even in a job you thought "only edits files."

What a checkpoint is and what it isn't

A checkpoint is a snapshot of files Claude edited with its file tools. It is not a full backup of your working tree. In interactive mode, Claude Code takes one each time you send a prompt that starts a turn. It keeps file snapshots for the 100 most recent checkpoints in a session and saves them with the conversation, so /rewind still works after you resume (Checkpointing docs). The rewind menu can restore code and conversation, only the conversation, or only the code. It can also summarize from or up to a chosen point (same source).

These limits matter more when nobody is watching:

• Bash changes are not tracked. Rewind can't undo rm, mv, cp, sed -i or echo > file when they run through Bash (Checkpointing docs; SDK docs).
• Subagent edits usually aren't restored. The only exception is a skill with context: fork that runs in the foreground. Forked skills run in the background by default, and you set background: false to run one in the foreground. For every other subagent, the docs say to revert with git (Checkpointing docs).
• Directories aren't undone. Rewind deletes files Claude created and restores files it modified. It doesn't reverse creating, moving or deleting directories, and it doesn't track remote or network files (SDK docs).
• Links and some other paths are skipped. Since v2.1.216, rewind skips symlinks, hard links, other non-regular files, files whose parent directory no longer resolves to where it was at checkpoint time, and files whose backup can't be read safely. RewindFilesResult.skippedLinks counts all of these. Before v2.1.216, rewind wrote and deleted through links (SDK docs).
• Snapshots expire. By default, the retention sweep deletes a session's snapshots about 30 days after the session last saved one. After that, a rewind can fail with "No files were restored." To keep snapshots longer, set cleanupPeriodDays (Checkpointing docs; Settings reference).
• Checkpoints don't replace version control. Anthropic describes them as "quick, session-level recovery" and recommends git for permanent history (Checkpointing docs).

The fileCheckpointingEnabled setting turns the interactive /rewind snapshots on or off. When it is unset, snapshots are on (Settings reference).

How headless checkpointing differs

In the Agent SDK, checkpointing is opt-in, and it takes two options (SDK docs):

With both set, each user message in the response stream carries a uuid you can use as a restore point. Rewinding to the first user message's UUID returns tracked files to their original state. Rewinding files doesn't rewind the conversation, which stays as it was (SDK docs).

The official examples also set permission_mode="acceptEdits" so edits go through without a prompt (SDK docs). Always pass a permission mode explicitly. A -p run that sets none starts in a built-in default mode, and that default can be auto (Headless docs).

Pattern 1: Rewind inside the run when validation fails

Use this pattern when your script can tell during the run that something has gone wrong. Examples: a test command fails, a protected file changes, or the diff is much larger than expected.

The docs' "checkpoint before risky operations" pattern keeps a user-message UUID and calls rewind_files() as soon as your own condition is true, while the stream is still open (SDK docs). Here is a shortened Python version. should_revert() is a placeholder for your own check:

options = ClaudeAgentOptions(
    enable_file_checkpointing=True,
    permission_mode="acceptEdits",
    extra_args={"replay-user-messages": None},
)

first_checkpoint = None
async with ClaudeSDKClient(options) as client:
    await client.query("Update dependencies and fix type errors")
    async for message in client.receive_response():
        if isinstance(message, UserMessage) and message.uuid and not first_checkpoint:
            first_checkpoint = message.uuid
        if should_revert(message) and first_checkpoint:   # your own check
            await client.rewind_files(first_checkpoint)
            break

You need to make two decisions:

1. Pick which checkpoint to rewind to. The docs' version overwrites its variable every turn, so it keeps only the latest checkpoint and undoes only the last step. An unattended job usually wants to throw away the whole attempt, so the example above keeps the first UUID. To keep some turns and undo others, store every UUID. The docs call this "Multiple restore points" (SDK docs).
2. Call rewind before the loop ends. If you call rewindFiles() after you've finished iterating, you get "ProcessTransport is not ready for writing," because the connection closes when the loop completes (SDK docs).

Pattern 2: Record IDs now, rewind later

Use this pattern when you only find out a run was bad after it ends, for example when CI goes red an hour later or someone reviews the diff the next morning.

1. Save checkpoint_id and session_id for every run. A small JSON log next to the job output is enough. The docs show how to capture session_id from the ResultMessage (SDK docs).
2. Rewind later by resuming with an empty prompt. Open a new client with enable_file_checkpointing=True and resume=session_id, send "", and call rewind_files(checkpoint_id) inside the response loop (SDK docs).
3. Or rewind from the shell, without SDK code:

CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true \
  claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

--rewind-files doesn't appear in claude --help, but the CLI accepts it. When it works, it prints Files rewound to state at message <checkpoint-uuid> and exits without sending a prompt. Without the environment variable, the bare CLI fails with "File rewinding is not enabled" (SDK docs).

Run the rewind on the same machine that ran the job. Checkpoints belong to the session that created them (SDK docs), and the snapshots live in local Claude Code state (Checkpointing docs). --resume <id> can find a session in other projects on the same machine (CLI reference). Running the rewind from the original project directory is still the safest choice.

Let the run finish before you depend on its checkpoints. "No file checkpoint found" can mean the session wasn't properly completed (SDK docs), and a claude -p run stopped with SIGTERM leaves its current turn unfinished (Headless docs). If your supervisor has to stop a job, send SIGINT or call the SDK's interrupt() first, as the headless docs recommend.

Using only the CLI, without the SDK

You can do this from a shell script. --replay-user-messages requires both --input-format stream-json and --output-format stream-json. You can also give the session a known ID up front with --session-id <uuid> so you don't have to parse it from the output (CLI reference).

The SDK sets CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING internally only when checkpointing is enabled, and the bare CLI never sets it (SDK docs). "No file checkpoint found" can mean checkpointing was off on the original session, so the safe reading is to set the variable on the original run as well as on the rewind. The docs don't describe this CLI-only flow end to end, so this is an inference. Test it on a throwaway repo before you rely on it.

Here is an example launch. The headless page doesn't show the stream-json input message format, so check it against the Agent SDK docs before use:

SID=$(uuidgen | tr 'A-Z' 'a-z')
echo '{"type":"user","message":{"role":"user","content":"Fix lint errors in src/"}}' | \
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p \
  --session-id "$SID" \
  --input-format stream-json --output-format stream-json --verbose \
  --replay-user-messages --permission-mode acceptEdits \
  > run.jsonl
CHECKPOINT=$(jq -r 'select(.type=="user" and .uuid) | .uuid' run.jsonl | head -1)
echo "$SID $CHECKPOINT" >> agent-runs.log

Don't use --no-session-persistence on runs you might want to rewind. It stops the session from being saved to disk, so the session can't be resumed (CLI reference), and a later rewind depends on resuming.

Rewind vs. git vs. worktrees: which to use when

Use all of them together. Each one covers gaps the others leave.

How to decide:

• If you need to undo a run days later, check that the snapshots are still there (about 30 days by default) and raise cleanupPeriodDays if needed (Checkpointing docs).
• If the job runs where other people's settings could load (CI, shared machines), consider --bare. The docs recommend it for scripted calls. In bare mode Claude Code skips hooks, plugins, MCP servers and CLAUDE.md from the host, and it needs ANTHROPIC_API_KEY instead of a subscription login (Headless docs).

A practical setup checklist

1. Start each run on a clean git state, or in a worktree with claude -w <name> (CLI reference).
2. Turn on checkpointing (enableFileCheckpointing / enable_file_checkpointing, or the env var for the bare CLI) and replay-user-messages (SDK docs).
3. Set the permission mode explicitly (Headless docs).
4. Save the first user-message UUID and the session ID for every run.
5. Limit runaway runs with --max-turns and --max-budget-usd, which work in print mode only. The budget cap uses a client-side cost estimate that can differ from your bill, and spend can go past it, so leave headroom (CLI reference).
6. Add a validation step (tests, lint, diff-size check) and rewind automatically when it fails.
7. After any rewind, run git status. Anything still changed came from Bash, a subagent or a skipped path. Reset it with git.
8. Read skippedLinks in RewindFilesResult and alert when it isn't zero, because those files kept their current contents (SDK docs).

Troubleshooting quick reference

Most rewind failures come from a missing option on the original run or from calling rewind at the wrong time.

FAQ

Are checkpoints on by default in claude -p or the Agent SDK?

No. Interactive sessions take snapshots by default. In the Agent SDK you have to enable file checkpointing and replay-user-messages, and with the bare CLI you set CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true (SDK docs).

Can I skip git if I use checkpoints?

No. Anthropic says checkpoints are for quick, session-level recovery and recommends git for permanent history. Rewind also misses Bash changes, most subagent edits and directory operations (Checkpointing docs).

Does rewinding files also rewind the conversation?

Not in the SDK. rewindFiles() / rewind_files() restores files on disk and leaves the conversation history as it was. The interactive /rewind menu lets you choose code, conversation, or both (SDK docs; Checkpointing docs).

How long can I wait before rewinding a run?

By default, about 30 days after the session last saved a snapshot. After that, cleanup can remove the snapshots. You can change this with cleanupPeriodDays (Checkpointing docs).

Can I rewind on a different machine, such as a fresh CI runner?

Not reliably. Checkpoints are tied to the session that created them, and the snapshots live in local Claude Code state (SDK docs; Checkpointing docs). On short-lived runners, rely on git or worktrees instead.

Next steps

Pick the job type that matches your automation and try only the checklist items for that type today. Each list takes one throwaway repo and one run.

If your job mostly edits files (Edit/Write):

1. Copy the Pattern 1 code. Replace should_revert() with one check, such as "tests fail."
2. Run it once on a throwaway repo. Make the check fail on purpose and confirm the files go back.
3. Run git status afterwards. If something is still changed, find which command caused it.

If your job mostly runs Bash commands:

1. Wrap the run in claude -w <name>, or commit before each run.
2. Write a one-line revert script: git reset --hard && git clean -fd, run inside the worktree only.
3. Add --disallowedTools "Bash(rm *)" and --max-turns, then do one test run.

If your job uses subagents or forked skills:

1. Assume rewind won't restore their edits, and run the job in a worktree.
2. Save the session ID and first UUID anyway (Pattern 2), so the main agent's own edits can still be rewound.
3. After a test run, compare git diff with the rewind result to see what the subagents changed.

If you'd rather not build this yourself: a freelance developer who knows the Agent SDK and your CI can usually set up a worktree, validation and revert script for you. You pay for their time on top of your usual Claude usage. Ask for a fixed-scope quote, because rates vary too much to give a reliable figure here. This suits you if you have one important recurring job and little time. It's a poor fit if your jobs change every week, because you'll keep paying for changes. Another route is to run the job in GitHub Actions or GitLab CI with Claude Code (GitHub Actions docs, GitLab CI/CD docs). Every run then starts from a clean checkout, and you undo it by not merging its branch, so you don't depend on checkpoints at all.

Related on Unattended: look for our guides on running claude -p on a schedule, choosing permission modes for unattended runs, and using git worktrees for agent jobs. They cover the layers that this article treats as "use git instead."

Sources

Checked on 2026-10-15.

• Checkpointing – Claude Code Docs
• Rewind file changes with checkpointing – Agent SDK Docs
• CLI reference – Claude Code Docs
• Settings reference – Claude Code Docs
• Run Claude Code programmatically (headless) – Claude Code Docs
• Agent SDK overview – Claude Code Docs

Originally published at Unattended (updated 2026-10-15).

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

A headless Claude Code run (claude -p) usually stops for one of three reasons. It reached a limit you set, such as --max-turns or --max-budget-usd. A timer ran out, such as the 2-minute Bash default, the 10-minute background-wait cap or your CI job's own timeout. Or it needed a permission that nobody was there to give, so the action was denied and Claude gave up on that step. The fix is to set each of these on purpose, read the result subtype and exit code after every run, and give the agent a clear, pre-approved set of tools.

This guide goes through each trigger using Anthropic's own documentation, then ends with a checklist you can copy into your scheduled jobs.

How to see why a run stopped

Before changing any settings, make every run report why it ended. Claude Code exits with code 0 on success and a non-zero code when the run fails. One catch: when the failure happens inside the run (missing authentication, for example), the failure is printed as the result on stdout, not on stderr. If your cron script only logs stderr, you will miss it.

Use JSON output so you can read the result in your script:

claude -p "Triage new issues" --output-format json > run.json
jq -r '.subtype, .stop_reason, .total_cost_usd, .num_turns' run.json

The Agent SDK docs list these result subtypes: success, error_max_turns, error_max_budget_usd, error_during_execution and error_max_structured_output_retries. Every result includes total_cost_usd, usage, num_turns and session_id. The stop_reason field can also be max_tokens, which means the model hit its output token limit on the last turn.

For more detail, use --output-format stream-json --verbose. In that format, permission denials show up as permission_denied messages, and the final result lists them in permission_denials. Retryable API errors show up as system/api_retry events with a category such as rate_limit, overloaded, authentication_failed or max_output_tokens (source).

Trigger 1: Turn and token budgets

Max turns

--max-turns limits the number of agentic turns in print mode. It has no limit by default and exits with an error when the limit is reached. A turn is one tool-use round trip, so a task like "run tests, read files, edit, re-run tests" uses several. If you set --max-turns 3 to keep a nightly job small, it can stop before the edit step. The SDK docs give this same example, where max_turns=2 stops before the edit.

Fix: Give the job some room above the number of turns it normally needs, and treat error_max_turns as "resume later", not as a failure. The session ID still comes back, so you can run claude -p "continue" --resume "$session_id" (source).

Dollar budget

--max-budget-usd stops the run once estimated spend reaches the amount you set. Things to know:

• The check uses a client-side cost estimate, which can differ from your bill.
• Spend can go past the cap. The response that reaches it still finishes, and running subagents keep spending until they stop. Anthropic says to leave headroom.
• Subagent spend counts toward the cap. After the cap is reached, starting another subagent fails with Budget limit reached, and background subagents are stopped (source).
• When you continue a run with --continue or --resume, the totals from earlier runs don't count toward the new cap.

Output tokens and context

CLAUDE_CODE_MAX_OUTPUT_TOKENS sets the maximum output for most requests. Defaults and caps depend on the model, and raising it reduces the effective context window available before auto-compaction. If a long file write ends with stop_reason: max_tokens, this setting is the place to look.

Long runs also fill up the context window. When it gets close to the limit, Claude Code summarizes older history, so instructions from early in the conversation may not be kept. If a long job seems to "forget" its rules partway through, that is often why. Put rules that must always apply in CLAUDE.md, or, with --bare, in --append-system-prompt-file. Keep tool output small: Bash output read back into context is capped by BASH_MAX_OUTPUT_LENGTH (default 30,000 characters) (source).

Trigger 2: Session and tool timeouts

Several timers apply to a headless run:

Some details matter here:

• Bare mode: with --bare, no background tasks run, so a command that reaches its timeout stops instead of moving to the background. This affects long test suites or builds.
• Missing MCP servers don't fail the run. Claude Code skips invalid --mcp-config entries and the run continues and exits cleanly. When stderr is captured (as in CI), it prints no warning. The skipped entries only appear in mcp_server_errors in the system/init event. A CI gate can check whether that array is empty.
• Your own scheduler can stop the run. If a CI runner or process supervisor sends SIGTERM, Claude Code exits with code 143 and records no result for the unfinished turn. To end the turn cleanly, send SIGINT first. To continue the interrupted turn when you resume, set CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1 (source).
• Large piped input fails. Piped stdin is capped at 10MB. For bigger inputs, write them to a file and put the file path in the prompt.

Credentials expire too

Login expiry is not a timeout setting, but on a schedule it has the same effect. Once a /login session expires, each model request fails with Login expired. For scripts, claude setup-token creates a one-year OAuth token that you set as CLAUDE_CODE_OAUTH_TOKEN. However, bare mode does not read CLAUDE_CODE_OAUTH_TOKEN. With --bare, use ANTHROPIC_API_KEY or an apiKeyHelper instead. Also note that in -p mode, a set ANTHROPIC_API_KEY is always used when present. An old key left in your shell environment will therefore override your subscription login.

Trigger 3: Permission prompts with no one to answer

This trigger causes the most confusion. In an interactive session, Claude asks and waits for you. In a headless run, what happens depends on whether there is a "permission host":

• No host (plain claude -p): any request that would show a prompt is denied. Claude gets a rejection message and usually tries something else or reports that it couldn't continue. From outside, the job looks like it quit early.
• With a host (an SDK canUseTool callback or --permission-prompt-tool): the run waits for that host to answer each request. If the host is not answering, the run can wait until a timer ends it.

For unattended jobs, pass --permission-prompts none (v2.1.259 or later). Anything that would prompt is denied unless a PermissionRequest hook allows it, and Claude is told not to retry.

Set the permission mode explicitly

If nothing sets a permission mode, the run uses the built-in starting mode, which can be auto. Choose the mode yourself:

Allow-rule mistakes that lead to denials

• **Missing space before *.** Bash(git diff ) matches commands starting with git diff. Without the space, Bash(git diff) would also match git diff-index.
• Bare Bash in auto mode. In a run that starts in auto mode, a bare Bash entry is dropped and the classifier evaluates each command instead.
• Tools that dontAsk always denies. AskUserQuestion, MCP tools marked requiresUserInteraction and reads from network paths are denied even when an allow rule matches. If your prompt tells Claude to "ask me if unsure", that question will be denied in a headless run.

One more thing: without --bare, a -p run executes the hooks in the project's .claude/settings.json and connects its .mcp.json servers, even in an untrusted folder. That can change how a job behaves from one machine to another. Anthropic recommends --bare for scripted calls and says it will become the default for -p.

A prevention checklist

Here is an example nightly job that applies the points above. Adjust the paths, tools and numbers for your own job.

#!/usr/bin/env bash
# Example: nightly dependency check (illustrative values)
export BASH_DEFAULT_TIMEOUT_MS=600000     # long test suites
export CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=900000

claude --bare -p "Update dependency pins and run the tests" \
  --append-system-prompt-file ./agent-rules.md \
  --permission-mode dontAsk \
  --permission-prompts none \
  --allowedTools "Read,Edit,Bash(npm test *),Bash(npm install *),Bash(git diff *)" \
  --max-turns 40 \
  --max-budget-usd 3.00 \
  --output-format json > run.json
code=$?

subtype=$(jq -r '.subtype' run.json)
[ "$code" -ne 0 ] || [ "$subtype" != "success" ] && echo "Agent stopped: $subtype (exit $code)" >&2

Go through this list before you schedule a job:

Budgets

• [ ] --max-turns is set with headroom, and error_max_turns triggers a resume or an alert.
• [ ] --max-budget-usd is set a bit below your real limit, since spend can go past it.
• [ ] Permanent rules live in CLAUDE.md or --append-system-prompt-file, not only in the opening prompt, so compaction doesn't drop them.
• [ ] Noisy commands are piped through tail or grep so they don't fill the context window.

Timeouts

• [ ] BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS are longer than your slowest build or test command.
• [ ] CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS fits jobs that use background subagents.
• [ ] The CI or job timeout is longer than the agent's own limits, and it sends SIGINT before SIGTERM.
• [ ] Your gate fails when mcp_server_errors is not empty.
• [ ] Authentication matches the mode: API key or apiKeyHelper with --bare, CLAUDE_CODE_OAUTH_TOKEN without it. You have a reminder before the one-year token expires.

Permissions

• [ ] The permission mode is set explicitly (dontAsk is a sensible default).
• [ ] --permission-prompts none is set so nothing waits on a host.
• [ ] Every command the task needs is in --allowedTools, with correct * spacing.
• [ ] The prompt never asks Claude to check with a human.
• [ ] The script logs permission_denials after each run, and you add allow rules (or narrow the task) based on what it shows.

When to raise a limit and when to narrow the task

If a job keeps hitting error_max_turns or error_max_budget_usd, raising the limit is not always the answer. A reasonable rule: if the turns are spent on useful work and the result is close to done, raise the limit. If the transcript shows repeated retries, denied tools or the same files being read again and again, narrow the task instead. Split it into smaller runs, hand subtasks to subagents (which start with a fresh context and only return a summary), or lower effort for routine steps. Shorter jobs with fixed limits and checked results are easier to run without supervision than one long open-ended job.

Sources

• Run Claude Code programmatically (headless mode)
• CLI reference
• How the agent loop works (Agent SDK)
• Environment variables
• Authentication
• Choose a permission mode

Originally published at Unattended.