DEV Community: Evan Cates

Where Claude Code Tokens Actually Go (and How to Cut the Waste)

Evan Cates — Fri, 12 Jun 2026 07:45:40 +0000

If your Claude Code API bill feels high, the cause is rarely too many turns. It is a handful of measurable patterns: re-reading the same files, oversized tool output, and cache misses. The data is in the transcripts Claude Code already writes to ~/.claude/projects/. Full guide and a free tool: https://github.com/Ludoonus/claude-token-report

These practices are covered in depth in The Claude Code Operator's Handbook — 18 chapters on running AI coding agents safely and efficiently. Read a free sample or get it ($29).

How Claude Code Hooks Work: A Practical Guide to PreToolUse Gates

Evan Cates — Fri, 12 Jun 2026 07:01:41 +0000

Claude Code can run shell commands, edit files, and push to git on your behalf. That power is the point — and the risk. Hooks are the mechanism for putting deterministic guardrails around it: small scripts the harness runs at defined points in the agent's loop, able to inspect — and block — what the agent is about to do.

This guide covers the PreToolUse hook specifically, because it's the one that can stop a dangerous action before it executes.

The hook lifecycle

Claude Code fires hooks at several lifecycle events. The most useful for safety are:

Event	Fires	Can block?
`PreToolUse`	Before a tool call runs	Yes — exit 2
`PostToolUse`	After a tool call returns	No (observe/log)
`SessionStart`	When a session begins	No (inject context)
`Stop`	When the agent finishes a turn	Yes — can require more work

How a PreToolUse hook receives the tool call

When the agent is about to call a tool, the harness serializes the call as JSON and pipes it to your hook on stdin. For a Bash command, that looks like:

{
  "tool_name": "Bash",
  "tool_input": { "command": "git push --force origin main" }
}

Your hook reads that JSON, decides, and signals its verdict through the exit code:

exit 0 — allow the call to proceed.
exit 2 — block the call. Anything the hook wrote to stderr is fed back to the model, so the agent learns why and can change course or ask the user instead of blindly retrying.

A minimal command gate

Here's a complete PreToolUse hook that blocks force-pushes to main:

#!/usr/bin/env bash
set -euo pipefail

cmd=$(jq -r '.tool_input.command // empty')
[ -z "$cmd" ] && exit 0

if echo "$cmd" | grep -qE 'git\s+push\s+.*(--force|-f)\b.*\bmain\b'; then
  echo "BLOCKED: force-push to main. Ask the user first." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/gate.sh" }] }
    ]
  }
}

Three patterns worth gating

1. Secrets before a push. The highest-value gate. Before any git push, scan the outgoing commits — not the working tree — for credential-shaped strings and forbidden filenames (.env, private keys). Use gitleaks if available, with a regex layer as a portable fallback. A single leaked key that reaches a public remote must be treated as compromised even after force-removal, so catching it pre-push is the whole game.

2. Blast-radius commands. Some commands are correct in intent but catastrophic when a variable is empty or a path is wrong: rm -rf "$DIR" with $DIR unset, git reset --hard origin/main discarding local work, chmod 777, curl ... | sh. Gate the patterns and make the agent surface them to a human.

3. Shared state an agent shouldn't touch. If you run multiple agent sessions, one can "clean up" another's git worktree that merely looks orphaned. Gate writes to .claude/worktrees/ and refuse git add -A in repos that contain them, since -A silently stages worktree gitlinks.

A gotcha: don't assume jq is installed

Hooks run in whatever shell the user has. jq is common but not guaranteed. Make the JSON extraction degrade gracefully:

extract_cmd() {
  if command -v jq >/dev/null 2>&1; then
    jq -r '.tool_input.command // empty'
  elif command -v python3 >/dev/null 2>&1; then
    python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))'
  fi
}

A hook that errors out because a dependency is missing fails open — the dangerous command runs anyway. Test your hooks against the no-jq case.

If you'd rather not write and maintain these yourself, I packaged all three gates as a tested, one-command Claude Code plugin — secret scanning, dangerous-command gating, and worktree protection. It's free and MIT-licensed: cc-powerpack on GitHub.

These practices are covered in depth in The Claude Code Operator's Handbook — 18 chapters on running AI coding agents safely and efficiently. Read a free sample or get it ($29).

Stop AI Coding Agents From Leaking Secrets (.env, API keys, tokens)

Evan Cates — Fri, 12 Jun 2026 07:00:40 +0000

An AI coding agent with shell access will, eventually, try to commit something it shouldn't. Not maliciously — it runs git add -A to "save progress," and an untracked .env goes in with everything else. The commit message says chore: sync. The next git push sends your database password to a remote you can't fully un-send it from.

Why this happens specifically with agents

Humans develop a reflex: you glance at git status before staging, and an unexpected .env jumps out. Agents don't have that reflex unless you give it to them. They pattern-match "stage the work" to git add -A or git add ., both of which sweep up every untracked file in the tree — secrets, local configs, key material, and (in repos with worktrees) gitlinks to other sessions.

Why "just add it to .gitignore" isn't enough

.gitignore only protects files that were never tracked. The dangerous cases slip through anyway: a .env.local variant not in your ignore patterns, a key pasted into a normally-tracked config file, or a secret in a file the agent created this session. You need a check on the content of the outgoing commits, not just filenames.

The fix: scan outgoing commits before every push

The right place to catch a secret is the moment before it leaves your machine — at git push, against the commits you're actually about to send (@{u}..HEAD), not the whole history and not just the working tree.

upstream=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)
range=${upstream:+$upstream..HEAD}

# names: catch .env and key material in outgoing commits
git diff --name-only "$range" | grep -qE '(^|/)(\.env|.*\.pem|id_rsa|id_ed25519)$' \
  && { echo "sensitive file in outgoing commits"; exit 2; }

# content: catch credential-shaped strings in the added lines
patterns='(AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|sk-[A-Za-z0-9_-]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----)'
git diff "$range" | grep -qE "^\+.*$patterns" \
  && { echo "credential-shaped string in outgoing diff"; exit 2; }

Wire that into a Claude Code PreToolUse hook matched on git push, and use gitleaks as the primary scanner with the regex layer as a portable fallback. The hook exits 2 to block, and the agent gets told why — so it stops instead of retrying.

If a secret already pushed

Treat it as compromised the instant it reaches a remote, even a private one. Rotate the credential first; rewriting history (git filter-repo) is cleanup, not containment. This is exactly why a pre-push gate is worth the five minutes to set up — recovery is always more expensive.

I packaged this as a one-command Claude Code plugin — a pre-push secret scanner (gitleaks + regex fallback + forbidden-file check), plus dangerous-command and worktree gates. Free and MIT-licensed: cc-powerpack on GitHub.

These practices are covered in depth in The Claude Code Operator's Handbook — 18 chapters on running AI coding agents safely and efficiently. Read a free sample or get it ($29).