SuperClaude/superclaude/modules/token-counter.md

name, description, category

name	description	category
token-counter	Dynamic token usage calculation from system notifications	module

Token Counter Module

Purpose: Parse and format real-time token usage from system notifications

Input Source

System provides token notifications after each tool call:

<system_warning>Token usage: [used]/[total]; [remaining] remaining</system_warning>

Example:

Token usage: 57425/200000; 142575 remaining

Calculation Logic

Parse:
  used: Extract first number (57425)
  total: Extract second number (200000)
  remaining: Extract third number (142575)

Compute:
  percentage: (used / total) × 100
  # Example: (57425 / 200000) × 100 = 28.7125%

Format:
  percentage: Round to integer (28.7% → 28%)
  used: Round to K (57425 → 57K)
  total: Round to K (200000 → 200K)
  remaining: Round to K (142575 → 142K)

Output:
  "[%] ([used]K/[total]K) · [remaining]K avail"
  # Example: "28% (57K/200K) · 142K avail"

Formatting Rules

Number Rounding (K format)

Rules:
  < 1,000: Show as-is (e.g., 850 → 850)
  ≥ 1,000: Divide by 1000, round to integer (e.g., 57425 → 57K)

Examples:
  500 → 500
  1500 → 1K (not 2K)
  57425 → 57K
  142575 → 142K
  200000 → 200K

Percentage Rounding

Rules:
  Always round to nearest integer
  No decimal places

Examples:
  28.1% → 28%
  28.7% → 28%
  28.9% → 29%
  30.0% → 30%

Implementation Pattern

Step 1 - Wait for System Notification:
  Execute ANY tool call (Bash, Read, etc.)
  System automatically sends token notification

Step 2 - Extract Values:
  Parse notification text using regex or string split
  Extract: used, total, remaining

Step 3 - Calculate:
  percentage = (used / total) × 100
  Round percentage to integer

Step 4 - Format:
  Convert numbers to K format
  Construct output string

Step 5 - Display:
  🧠 [percentage]% ([used]K/[total]K) · [remaining]K avail

Usage in PM Command

Session Start Protocol (Step 3):
  1. Execute git status (triggers system notification)
  2. Wait for: <system_warning>Token usage: ...</system_warning>
  3. Apply token-counter module logic
  4. Format output: 🧠 [calculated values]
  5. Display to user

Anti-Patterns (FORBIDDEN)

❌ Static Values:
   🧠 30% (60K/200K) · 140K avail  # WRONG - hardcoded

❌ Guessing:
   🧠 ~25% (estimated)  # WRONG - no evidence

❌ Placeholder:
   🧠 [calculating...]  # WRONG - incomplete

✅ Dynamic Calculation:
   🧠 28% (57K/200K) · 142K avail  # CORRECT - real data

Validation

Self-Check Questions:
  ❓ Did I parse the actual system notification?
  ❓ Are the numbers from THIS session, not a template?
  ❓ Does the math check out? (used + remaining = total)
  ❓ Are percentages rounded correctly?
  ❓ Are K values formatted correctly?

Validation Formula:
  used + remaining should equal total
  Example: 57425 + 142575 = 200000 ✅

Edge Cases

No System Notification Yet:
  Action: Execute a tool call first (e.g., git status)
  Then: Parse the notification that appears

Multiple Notifications:
  Action: Use the MOST RECENT notification
  Reason: Token usage increases over time

Parse Failure:
  Fallback: "🧠 [calculating...] (execute a tool first)"
  Then: Retry after next tool call

Integration Points

Used by:

• commands/pm.md - Session start protocol
• agents/pm-agent.md - Status reporting
• Any command requiring token awareness

Dependencies:

• System-provided notifications (automatic)
• No external tools required