DEV Community: Aoba Works

Claude Code Hooks Lifecycle: Every Event, Explained

Aoba Works — Sun, 18 Oct 2026 16:44:55 +0000

Originally published at Unattended.

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.

Your situation	What to pick first	First page to open
Beginner, never written a hook	A `Notification` hook that alerts you when Claude is waiting	Hooks guide: Set up your first hook
Daily automation that sometimes loops or burns usage	A `PreToolUse` or `PostToolBatch` budget guard	Hooks reference: Decision control
Overnight or cron runs that "finish" with nothing done	`StopFailure` + `Stop` hooks that log and verify	Hooks reference and /claude-code-cron-job-setup-run-automations-overnight/
Tight budget (Pro plan, shared usage limits)	Command hooks only. Skip `prompt`/`agent` hooks	Claude pricing

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).

Phase	Event	Fires when	Can block?
Start	`SessionStart`	Session begins or resumes (matcher: `startup`, `resume`, `clear`, `compact`, `fork`)	No
Start	`InstructionsLoaded`	A CLAUDE.md or `.claude/rules/*.md` file is loaded	No
Input	`UserPromptSubmit`	A prompt is submitted, before Claude processes it, including turns Claude Code starts by itself	Yes
Tool loop	`PreToolUse`	Before a tool call executes	Yes
Tool loop	`PermissionRequest` / `PermissionDenied`	A call needs a permission decision / auto mode denied it	No
Tool loop	`PostToolUse` / `PostToolUseFailure`	After a tool call succeeds / fails	No (exit code), but `decision: "block"` feeds back
Tool loop	`PostToolBatch`	After a batch of parallel tool calls resolves, before the next model call	Yes
Delegation	`SubagentStart` / `SubagentStop`	Subagent spawned / finished	Stop: Yes
Context	`PreCompact` / `PostCompact`	Before / after context compaction (`manual` or `auto`)	Pre: Yes
Turn end	`Stop`	Claude finishes responding	Yes
Turn end	`StopFailure`	Turn ends because of an API error	No
Waiting	`Notification`	Claude Code sends a notification (e.g. `permission_prompt`, `idle_prompt`)	No
End	`SessionEnd`	Session terminates	No

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.

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).
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" } ] }
    ]
  }
}

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.
Make scripts executable with chmod +x .claude/hooks/*.sh.
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.
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.

Mistake	Fix
Stop hook loops forever	Check `stop_hook_active` first and add a hard block counter (issue #54360)
Hook exits 1 and nothing happens	Only exit 2 blocks. Codes 1 and 3+ are non-blocking errors (reference)
Matcher on `Stop` ignored	`Stop`, `UserPromptSubmit` and `PostToolBatch` don't support matchers. They always fire (reference)
Path breaks with spaces	Use exec form (`command` + `args`) with `${CLAUDE_PROJECT_DIR}` (reference)
Huge stdout clutters context	Output over 10,000 characters is saved to a file with a preview, so keep it short (reference)
Expecting order between hooks	Matching hooks run in parallel. Put dependent steps in one script

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:

Add the Stop guard and StopFailure alert from the steps above to one project.
Add a PostToolBatch step counter that returns continue: false at a limit you choose.
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

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.

Claude Code Hooks Examples: 7 Copy-Paste Scripts

Aoba Works — Sat, 17 Oct 2026 15:43:19 +0000

Originally published at Unattended.

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.

Your situation	What to pick first	First page to open
Beginner, first hook ever	Script 4 (notification when Claude is waiting). It changes nothing and is easy to check	Hooks guide
Daily work, Claude runs commands unattended	Scripts 1 + 2 (guardrails)	Hooks reference: PreToolUse
Overnight or cron runs that stop early	Script 3 (Stop test gate) + Script 5 (tool log)	/claude-code-cron-job-setup-run-automations-overnight/
Watching your budget or usage	Scripts 5 + 6 (logging)	/claude-code-how-to-see-token-usage-and-reduce-it/

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)

In your project root, run mkdir -p .claude/hooks .claude/logs.
Save each script below into .claude/hooks/ and make it executable: chmod +x .claude/hooks/*.sh.
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.
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).
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:

Symptom	Likely cause	Fix
Hook never fires	Wrong event name or matcher (names are case-sensitive, e.g. `Bash`, `Edit\	Write`)
"hook error" notice	Script isn't executable or `jq` is missing	Run `chmod +x`, install `jq`, and test with `echo '{}' \
JSON output ignored	Exited with a code other than 0, or extra text was printed before the JSON	Print only the JSON, then {% raw %}`exit 0`
Claude never finishes	Stop hook ignores `stop_hook_active`	Add the loop guard from Script 3
Works in one folder, not another	Relative paths	Use `${CLAUDE_PROJECT_DIR}`

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:

Add Script 1 and Script 6 to one project, then use /hooks to check both are registered.
Run a normal task and read .claude/logs/tools.jsonl afterwards.
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

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.

Claude Code: How to See Token Usage (and Reduce It)

Aoba Works — Sat, 17 Oct 2026 11:31:21 +0000

Originally published at Unattended.

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.

Your situation	What to pick first	First page to open
Beginner, interactive sessions only	`/usage` inside Claude Code	Manage costs
Daily work on a Pro/Max subscription	`/usage` plan bars plus the 24h/7d breakdown	Manage costs → Plan usage breakdown
Recurring headless jobs (cron, CI)	`--output-format json` + `--max-budget-usd`	Run Claude Code programmatically
Tight budget on an API key	Workspace Spend limits in the Console	Workspaces
Want numbers for a dashboard	Usage and Cost Admin API or OpenTelemetry	Usage and Cost API

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

Start a session with claude and do some work.
Type /usage and press Enter. It runs right away, even while Claude is responding (Commands).
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).
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.
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

Add --output-format json:

   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).

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).
Add --max-turns to stop runaway loops. When the limit is hit, the run exits with an error.
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:

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.
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.
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.
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:

Run /usage at the end of your next session and write down the total and the Prompt cache hit share.
Put --output-format json --max-budget-usd on one recurring claude -p job and log total_cost_usd to a CSV.
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:

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

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.

DEV Community: Aoba Works

Claude Code Hooks Lifecycle: Every Event, Explained

Which option is right for you?

The lifecycle of one automation run, in order

Three timing facts that matter

Which hooks actually stop runaway token use

The kill switch: continue: false

PostToolBatch: the per-step budget checkpoint

PreToolUse: block the expensive call itself

Stop: useful, but it can add usage

PreCompact: an early warning about long runs

Which hooks catch silent failures

Set up your first lifecycle hook

Common mistakes and fixes

Next steps

FAQ

What is the order of Claude Code hook events?

Which Claude Code hook can block an action?

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

Where do I put Claude Code hooks?

Do prompt or agent hooks cost extra?

Sources

Claude Code Hooks Examples: 7 Copy-Paste Scripts

Which option is right for you?

How hooks are wired: the 60-second version

Setup steps (do this once)

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

Script 1: Block destructive shell commands

Script 2: Protect secrets and lock files

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

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

Script 4: Get pinged when Claude is waiting for you

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

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

Script 6: Log every tool call

Script 7: Session summary on exit

Common mistakes and fixes

Next steps

FAQ

Where do I put Claude Code hooks?

How do I block a command with a hook?

Why does my Stop hook make Claude loop forever?

Do hooks slow Claude Code down?

Sources

Claude Code: How to See Token Usage (and Reduce It)

Which option is right for you?

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

Steps

What the numbers mean

Common mistakes and fixes

How to track token burn in headless runs

Steps

Example: a cost-logging wrapper

Common mistakes and fixes

How to wire usage checks into hooks

Where to see real billing: Console and APIs

How to reduce token usage

Next steps

FAQ

Does Claude Code still have a /cost command?

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

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

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

Do Pro and Max users need to watch token costs?

Sources

The kill switch: `continue: false`

`PostToolBatch`: the per-step budget checkpoint

`PreToolUse`: block the expensive call itself

`Stop`: useful, but it can add usage

`PreCompact`: an early warning about long runs

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