In my previous post, "Writing hook scripts without stepping on macOS traps", I covered the basics of writing hooks. This time, the topic is speed.
A UserPromptSubmit hook runs synchronously on every single prompt. If you call an external command inside the hook, the time you spend waiting for it becomes turn latency, one-for-one. When I measured my cost-monitoring hook, I got mean 819ms / p95 5320ms / max 5753ms (last 24h, 817 invocations). That works out to a worst case of more than five seconds of waiting every time I hit enter on a prompt.
The job of ~/.claude/hooks/cost_guard.sh
is to look at the output token count and burn rate of the active 5h block and warn when a threshold is exceeded. To do that, it was calling ccusage blocks --active --json
on every prompt.
ccusage is a Node.js CLI with a high startup cost, and depending on the situation it can keep you waiting for several seconds. Here are the actual numbers, measured and aggregated with ~/.claude/scripts/hook-latency-wrap.sh
.
=== hook latency (last 1d, 4086 records) ===
hook n mean p95 max fail
----------------------------------------------------------------------
cost_guard.sh 817 819ms 5320ms 5753ms 0 ⚠
obsidian_context.sh 817 760ms 1386ms 4259ms 0
model_routing_reminder.sh 817 298ms 549ms 2003ms 0
message_display_filter.sh 817 212ms 435ms 1616ms 0
user_prompt_submit.sh 817 272ms 409ms 12295ms 0
cost_guard.sh's p95 of 5320ms towers over the other four. The situation doesn't change meaningfully within 60 seconds, so running the full thing on every prompt was clearly overkill.
The cache is self-contained in a single file, /tmp/cost_guard_${USER}.cache
. Here's the top of cost_guard.sh
.
CACHE="/tmp/cost_guard_${USER}.cache"
CACHE_AGE=60 # 秒
if [ -f "$CACHE" ]; then
age=$(( $(date +%s) - $(stat -f %m "$CACHE" 2>/dev/null || echo 0) ))
[ "$age" -lt "$CACHE_AGE" ] && { cat "$CACHE" >&2 2>/dev/null; exit 0; }
fi
If the cache file exists and its mtime is less than 60 seconds old, dump its contents to stderr and immediately exit 0
. The ccusage call itself is skipped. If the cache holds a warning string, it gets re-displayed; if the file is empty, nothing is printed and we just exit.
This is the heart of it. Look at the end of the script.
printf '%b' "$WARN" > "$CACHE"
[ -s "$CACHE" ] && cat "$CACHE" >&2
exit 0
The key point is that ** printf '%b' "" > "$CACHE" runs even when $WARN is empty**. The fact that there is no warning gets cached as an empty file.
Consider what happens if you implement it as "only write the cache when there's a warning." In the normal case ($WARN
empty), no cache is created → the next prompt is also a cache miss → full ccusage run. The most frequently taken path becomes the slowest one.
For the same reason, when ccusage fails, we also write an empty file before exiting.
BLOCK_JSON=$(${TIMEOUT_BIN:+"$TIMEOUT_BIN" 5} "$CCUSAGE" blocks --active --json 2>/dev/null) || { : > "$CACHE"; exit 0; }
[ -z "$BLOCK_JSON" ] && { : > "$CACHE"; exit 0; }
|| { : > "$CACHE"; exit 0; }
— even on the failure path, write an empty file before exiting (fail-open). Without this, a retry fires on every failure.
Note
"Only write the cache when there's a result" feels intuitive, butan empty result — nothing wrong — is worth caching too. The point of a cache is to make the most common path the fastest, so you need the mindset of recording the normal case rather than recording the exceptions.
The reason p95 climbed to 5320ms was that ccusage sometimes kept us waiting without responding. gtimeout 5
caps that at 5 seconds.
TIMEOUT_BIN=$(command -v gtimeout 2>/dev/null || echo /opt/homebrew/bin/gtimeout)
[ -x "$TIMEOUT_BIN" ] || TIMEOUT_BIN=""
BLOCK_JSON=$(${TIMEOUT_BIN:+"$TIMEOUT_BIN" 5} "$CCUSAGE" blocks --active --json 2>/dev/null) || { : > "$CACHE"; exit 0; }
${TIMEOUT_BIN:+"$TIMEOUT_BIN" 5}
is parameter expansion. If TIMEOUT_BIN
is non-empty it expands to "$TIMEOUT_BIN" 5
; if empty, it expands to nothing. That switches between "gtimeout 5 ccusage ...
" and "ccusage ...
" with no conditional branch.
On a machine where gtimeout
isn't installed via brew, TIMEOUT_BIN=""
and the call runs without a timeout. Hooks should be fail-open by default: a delayed cost warning is far less painful than Claude Code grinding to a halt.
printf '%b' "$WARN" > "$CACHE"
must run unconditionally, even when $WARN
is empty{ : > "$CACHE"; exit 0; }
stat -f %m
is macOS-specificstat -c %Y
. If you use the hook on Linux too, you need a branch/tmp/
disappears after a reboot/tmp/
is enough to fix itgtimeout 5
to kill a hanging CLI at a 5-second ceiling. The ${TIMEOUT_BIN:+...}
expansion gives you an optional prefix with no conditional branchNext time, I'll cover how Claude Code handles the warnings a hook writes to stderr — an overview of the whole hook protocol across UserPromptSubmit, PreToolUse, and PostToolUse.
*Written by Lily — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*