DEV Community

Lily
Lily

Posted on • Originally published at dev.to

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

#claudecode #shell #automation #performance

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 problem: calling ccusage on every prompt gets ugly

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
Enter fullscreen mode Exit fullscreen mode

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 fix: a 60-second TTL cache

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
Enter fullscreen mode Exit fullscreen mode

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.

The design crux: write an empty file in the normal case too

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
Enter fullscreen mode Exit fullscreen mode

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; }
Enter fullscreen mode Exit fullscreen mode

|| { : > "$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, but an 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.

Fail-open structure: killing hangs with gtimeout 5

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; }
Enter fullscreen mode Exit fullscreen mode

${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.

Traps I fell into

  • Making it "write the cache only when there's a warning" meant a full run every time in the normal case → printf '%b' "$WARN" > "$CACHE" must run unconditionally, even when $WARN is empty
  • Not writing the cache on a ccusage timeout means a retry on the next prompt → put an empty file down even on the failure path with { : > "$CACHE"; exit 0; }
  • stat -f %m is macOS-specific → on Linux it's stat -c %Y. If you use the hook on Linux too, you need a branch
  • A cache under /tmp/ disappears after a reboot → that just costs one full run. If anything it's convenient, since a stale warning doesn't carry over across reboots
  • A high p95 means a normal full run after the cache expired → looking only at the mean leads you to misread it as "slow overall." Use p95 to evaluate the cost of a cache miss

Summary

  • Calling an external CLI every time in a UserPromptSubmit hook piles up hundreds to thousands of milliseconds on every prompt (measured: mean 819ms / p95 5320ms)
  • Dropping a 60-second TTL cache file in /tmp/ is enough to fix it
  • The design crux is writing an empty file in the no-warning (normal) case too. Skip that and the most common path becomes the slowest run
  • Write an empty cache on the failure path as well, and stay fail-open. A hook must never stop Claude Code
  • Use gtimeout 5 to kill a hanging CLI at a 5-second ceiling. The ${TIMEOUT_BIN:+...} expansion gives you an optional prefix with no conditional branch

Next 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*

Top comments (0)