Hooks Bundle¶

5 bash hooks that run automatically in Claude Code to track tokens and control spend.

Installation¶

cost-guard init

Installs to .claude/hooks/ by default. See CLI reference.

Hooks¶

parallel_agents_guard.sh¶

Trigger: PreToolUse on Agent tool use

Purpose: Warn when you spawn >10 parallel agents (high resource usage)

Behavior: - Parses transcript for active Agent tool calls - If ≥10 agents, blocks new agents until some complete - Shows count + queue time

Why: MacBook throttling on 19 parallel agents + Docker stack (2026-05-07)

test_before_push_guard.sh¶

Trigger: PreCommit on git commit

Purpose: Block commits without E2E tests (catch regressions)

Behavior: - Scans transcript for recent Playwright / pytest runs - If code changes but no tests, blocks commit - Escape: add test-skip: ok to commit message

Skip: auto-skips chore:, docs:, test:, ci: commits

large_read_warning.sh¶

Trigger: PreToolUse on Read/Bash

Purpose: Warn before reading files >100KB

Behavior: - Checks file size before Read tool - If >100KB, shows warning with options to read range/skip - For Bash: suggests using head -c or tail -f

session_cost_check.sh¶

Trigger: SessionStart

Purpose: Display estimated session cost

Behavior: - Parses prior sessions from ~/.claude-mem - Calculates average spend per day / per week - Shows: Current cost estimate (so far) - Alert if approaching daily budget

token_alert.sh¶

Trigger: SessionStart

Purpose: Alert if daily budget exceeded

Behavior: - Loads daily cap from Cost Guard settings - If current day spend > cap: shows alert - Options: continue or stop session

Configuration¶

Hooks read from:

~/.cost-guard/config.json — daily budget, project patterns
Environment variables — COST_GUARD_BUDGET_USD, COST_GUARD_PROJECT

Example config:

{
  "daily_budget_usd": 5.0,
  "projects": [
    { "path": ".", "name": "cost-guard" },
    { "path": "../other", "name": "other-project" }
  ]
}

Disabling Hooks¶

To disable a hook temporarily:

mv ~/.claude/hooks/token_alert.sh ~/.claude/hooks/token_alert.sh.disabled

To disable all hooks:

chmod -x ~/.claude/hooks/*.sh

Claude Code checks executable bit — non-executable hooks are skipped.