Token Waste Auditor

Audit QClaw/OpenClaw token consumption and pinpoint waste. Outputs an anonymized report with concrete optimization estimates.

Quick Start

# Full audit (daily + session deep scan)
python scripts/auditor.py --days 30

# Lite audit (daily summary only, no session scan)
python scripts/auditor.py --days 30 --lite

# JSON output for CI
python scripts/auditor.py --days 7 --json

Data Sources

| Source | What | Cost | |--------|------|------| | openclaw gateway usage-cost --json | Daily input/output/cache totals | 0 (built-in) | | Session .jsonl files | Per-message + tool-call audit | 0 (local) | | Skill SKILL.md files | Prompt size measurement | 0 (local) |

Waste Dimensions

| Code | Waste Type | Detection | |------|-----------|-----------| | W01 | Low Cache Efficiency | cacheRead / total < 90% — context changes too often | | W02 | Context Overstuffing | input / output > 20:1 — too much context for too little output | | W03 | Skill Prompt Bloat | SKILL.md > 20KB — diminishing returns on instruction length | | W04 | Skill Prompt Redundancy | Duplicate blocks found across multiple SKILL.md files | | W05 | Session Bloat | Single session > 100K tokens without recent compaction | | W06 | Aborted Runs | Assistant messages truncated mid-generation |

Output Structure

══════════════════════════════════════════════
  Token Waste Audit Report
  Period: 2026-05-01 ~ 2026-05-21 (21 days)
══════════════════════════════════════════════

[1/6] Cache Efficiency
  read:  347.5M (96.6%)
  input:  10.9M  (3.0%)
  waste:  1.2M   (0.3%) ← cache-miss overhead
  Status: ✅ healthy

[2/6] Context Overstuffing
  avg input:output ratio = 7.9:1
  worst day: 2026-05-12 → 16.1:1
  Status: ✅ within bounds (< 20:1)

[3/6] Skill Prompt Bloat (top 3)
  1. skill-07    48KB  ⚠️  suggests split
  2. skill-03    42KB  ⚠️  suggests split  
  3. skill-12    31KB  — acceptable
  Est. waste: ~800K tokens/load × loads/week

[4/6] Skill Prompt Redundancy
  7 duplicate blocks found across 4 skill files
  Est. savings: ~140K tokens/week if deduplicated

[5/6] Session Bloat (top 3)
  1. session-01  14.2MB  ⛰️ ⛰️  active 24d, 2 compactions
  2. session-02   2.5MB  ⛰️  active 1d, 7 compactions
  3. session-03   2.0MB  active 1d, 8 compactions
  Suggests: archive long-lived sessions

[6/6] Aborted Runs
  Count: 2 aborted assistant responses
  Est. waste: ~45K tokens (negligible)
  Status: ✅ healthy

══════════════════════════════════════════════
  Summary
══════════════════════════════════════════════
  Total tokens (period):  359.8M
  Est. waste:               11.5M  (~3.2%)
  Est. savings potential:  4-8M/month
══════════════════════════════════════════════

Constraints

• Anonymity: All skill/agent/session names are hashed or replaced with generic labels. No path, name, or methodology from the user's setup ever appears in output.
• Privacy: The report contains only token metrics and waste estimates. No conversation content is extracted or reproduced.
• Safety: Read-only. Never modifies session files, skill files, or system config.