Claude Code Token Watch — Development skill for Claude Code

Claude Code Token Watch

Three Claude Code hooks that warn when a session starts burning tokens on the same anti-patterns. The hooks don't block anything — they inject a system message that the model sees and usually self-corrects on the next turn (delegating to a sub-agent, switching to `Edit` instead of re-reading, etc).

Tested on macOS only. Should work on Linux (uses `bash`, `jq`). Windows is not supported.

What it does

Hook	Triggers when	Hint it gives
token-watch-read.sh	The same file is Read 3+ times in one session	Suggests keeping the file's structure in context and using Edit without re-reading
token-watch-bash.sh	3+ recursive searches per session (grep -r, find ... -name, rg ...)	Suggests delegating the search to an Explore sub-agent
token-watch-webfetch.sh	3+ WebFetch calls per session	Suggests delegating browsing to a general-purpose sub-agent

Why

On a Claude subscription (Pro/Max), the 5-hour rate limit is consumed by tokens, and tokens are consumed by everything that lands in the conversation context — files, search results, fetched pages, history.

Three patterns disproportionately blow up context:

1. Re-reading the same file — each Read ships the whole file again, even if it's already in cache.
2. Recursive grep/find from the main thread — every match line ends up in the main context.
3. Long sequences of WebFetch — each fetched page lands in the main context as a wall of HTML/markdown.

These hooks count occurrences per session and, after the third hit, post a system message. The model treats system messages as instructions, so on the next turn it usually self-corrects without you having to interrupt and remind it.

Prerequisites

• Claude Code with hooks support
• bash
• jq — brew install jq (macOS) or apt install jq (Linux)

Installation

1. Clone and copy hooks

git clone https://github.