Speeding Up a UserPromptSubmit Hook with a 60-Second Cache: Designing cost_guard.sh

A developer optimized their Claude Code UserPromptSubmit hook by adding a 60-second cache, reducing the cost-monitoring script's p95 latency from 5320ms to near-instant. The cache stores both warnings and empty results, ensuring the common no-warning path is the fastest. The developer emphasizes caching the normal case, not just exceptions, to avoid slow repeated executions.

In my previous post, " Writing hook scripts without stepping on macOS traps https://zenn.dev/bokuwalily/articles/hook-script-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. 警告の有無に関わらず必ずキャッシュを更新する（空でも書く）。 これが無いと平常時（警告なし）はキャッシュ未作成のまま毎プロンプト ccusage フル実行になる。 ... 警告の有無に関わらず必ずキャッシュを書く（空 WARN なら空ファイル＝「平常」を60秒キャッシュ） 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-specific stat -c %Y . If you use the hook on Linux too, you need a branch /tmp/ disappears after a reboot /tmp/ is enough to fix it gtimeout 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 https://bokuwalily.com · X https://x.com/bokuwalily · GitHub https://github.com/bokuwalily