pre-usage-plugin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

cargo build --release          # build the binary
cargo clippy                   # lint
cargo fmt                      # format
cargo test                     # run tests
./install.sh                   # build + install binary + register hook in settings.json

To test the binary directly (simulate a UserPromptSubmit hook call):

echo '{"prompt":"hello world","transcript_path":""}' \
  | ./target/release/pre-usage; echo "exit: $?"

Architecture

pre-usage is a Rust binary installed at ~/.claude/plugins/pre-usage.
install.sh registers it as a UserPromptSubmit hook in ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "/Users/<you>/.claude/plugins/pre-usage" }
        ]
      }
    ]
  }
}

Claude Code calls the binary before every prompt is sent. The binary reads hook JSON from stdin, estimates token usage, and either exits 0 (proceed) or 2 (block).

Flow

UserPromptSubmit
      │
      ▼
  main.rs  ──reads stdin──▶  estimator.rs
                                  │
                          ┌───────┴────────┐
                          │                │
                   read session        estimate new
                   JSONL logs          prompt tokens
                   (accumulated        (content bytes ÷ 4)
                    session tokens)
                          │                │
                          └───────┬────────┘
                                  │
                            total_estimate
                                  │
                    ┌─────────────┴──────────────┐
                    │                            │
             ≤ threshold                   > threshold
                    │                            │
                exit 0                      ui.rs prompt
            (silent pass)              "[S]end  [C]ancel"
                                             │       │
                                           exit 0  exit 2