# Speeding Up a UserPromptSubmit Hook with a 60-Second Cache: Designing cost_guard.sh > Source: > Published: 2026-08-01 00:00:05+00:00 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)*