💖 Community Learnings: 7 Critical Token-Wasting Patterns (700K+ tokens saved!)

🔥 Token Burn Guide V2 - Compact & Optimized

Why this file: Documentation of Agent errors for prevention

Max Size: 500 lines (V1 had 943 → too much!)

Detailed Sessions: See [HOW_TO_BURN_TOKENS_FAST.md](HOW_TO_BURN_TOKENS_FAST.md) (943+ lines)

---

📋 QUICK REFERENCE: Anti-Patterns

| Error | Token Cost | Correct Way | Savings |
|-------|------------|-------------|---------|
| Parallel Agents | 300K | Sequential | 90% |
| Build without Test | 124K | Test per Module | 92% |
| Read code instead of asking | 16K | Ask User | 98% |
| Explore-Agent for search | 40K | grep | 99.75% |
| Build feature (already exists!) | 70K | Check first | 98% |

Golden Rule: grep (100 Tokens) > Agent (40K Tokens)

---

🎯 TOP 5 ERRORS (All Agents)

#1: Implementation without checking what exists ❌

Example AGENT-19:

User: "Test Runner shows no live logs"
Agent: *builds WebSocket Server* (70K Tokens)
Truth: SSE was already done (Line 304)

Cost: 70K → Should have been: 2K (grep + check)

Fix:

# BEFORE Implementation:
grep "feature" src/  # 100 Tokens
read existing_code  # 2K Tokens
ask_user()          # 500 Tokens

---

#2: Swarm Chaos without Coordination ❌

Example AGENT-12:

7 Agents parallel for Recovery Wizard
→ Each reads entire project
→ 9339 lines, doesn't load
→ 3 Buttons for 410K Tokens

Cost: 410K → Should have been: 20K (1 Agent)

Fix: 1 Agent, sequential, test after each module

---

#3: Code without Testing ❌

Example AGENT-12:

34 Modules generated → Then test
Result: Doesn't load at all
Debug: +50K Tokens

Cost: 124K → Should have been: 10K

Fix:

Module 1 → Write → Test → OK?
Module 2 → Write → Test → OK?
...

---

#4: Parallel Collision between Agents ❌

Example AGENT-19 + AGENT-21:

AGENT-19: Builds API with v1
AGENT-21: Changes header to v2 in parallel
→ Compiler errors
→ AGENT-21 has to fix

Cost: 15K → Should have been: 0 (Coordination)

Fix: Check if other Agents are working on same file

---

#5: Overengineering ❌

Example AGENT-19:

User wanted: Live-Logs
Agent delivered: WebSocket + Conversation Logger + BSV Integration
→ 3 Features instead of 1 Fix

Cost: 112K → Should have been: 2K

Fix: Only build what User explicitly requests!

---

#6: Brain-washed after Session Compacting 🧠💸

The Problem:

Session Start: User writes English
→ Compacting happens (Context gets summarized)
→ Resume: Computer settings are "German"
→ Agent suddenly answers German even though conversation was English!
→ User must mentally switch → Token waste!

Cause:

• Claude App looks at User-Settings instead of current Messages
• After Compacting: Language context lost
• Agent gets "brain-washed" by System-Locale

Cost per wrong language:

• +20% Token overhead due to language mismatch
• User confusion → more questions
• Inefficient communication

Fix (COMMANDMENT 5):

# IGNORE System-Settings!
# LOOK ONLY at current User-Message:
User writes: "Can you continue?"
→ Agent answers: "I'll continue..." (ENGLISH!)

User writes: "Kannst du weiter machen?"
→ Agent answers: "Ja, ich mache weiter..." (GERMAN!)

Avoid getting rich through brain-washing:
Current User-Language > System-Settings! 💰

---

#7: Compacting deletes critical context 🧠❌

The Problem:

Session 1-50: User explains weaknesses multiple times:
  - "I'm bad at X"
  - "Please always do Y"
  - "Feature Z failed 3x, never again!"

→ Compacting happens
→ Summary: Contains only technical facts, no User preferences!

Session 51: Agent does X again (User said "I'm bad at this!")
          Agent forgets Y (User asked for it!)
          Agent builds Z again (failed 3x!)

What gets lost during Compacting:

• User's weaknesses ("too dumb to describe it better")
• Repeated errors ("failed 3x already!")
• Important preferences ("always do it this way!")
• Critical warnings ("NEVER do that!")

Token Cost:

• Error gets repeated → +50K Tokens again!
• User must re-explain → +10K Tokens
• Trust lost → more questions → +20K Tokens
• Total: +80K Tokens for same error!

Fix - extend COMMANDMENT 2:

# BEFORE each Task: Load User-Context from API!
curl http://localhost:8080/api/user-context/current

# Response shows:
{
  "user_preferences": [
    "User is bad at exact descriptions",
    "Feature WebSocket failed 3x - don't build!",
    "Always grep FIRST, then build"
  ],
  "repeated_errors": [
    "Overengineering (4x)",
    "Build without test (3x)"
  ]
}

# Agent MUST read this BEFORE starting!

Solution:

1. Save important User-Statements in API (COMMANDMENT 2)
2. At Session-Start: Call API, load context
3. Write critical info to .claude/CLAUDE.md
4. NEVER trust Summary alone!

Avoid getting rich:
Persist context > Trust Compacting-Summary! 💰

---

✅ BEST PRACTICES (Save Tokens!)

1. CHECK FIRST, BUILD SECOND

# Golden Order:
1. grep "feature" src/        # 100 Tokens
2. read existing              # 2K Tokens
3. ask_user("exists already?") # 500 Tokens
4. if exists: fix else: build # 1-20K Tokens

2. TEST IMMEDIATELY

❌ Write 10 Files → Then test (124K)
✅ Write 1 File → Test → Continue (10K)

3. ASK USER

❌ *reads 50 files* (16K)
✅ "Where is the function?" → User answers → Read 20 lines (200 Tokens)

4. GREP > AGENT

✅ grep -r "keyword" src/  # 100 Tokens, 2 Sek
❌ Explore-Agent           # 40K Tokens, 5 Min

5. START SMALL

❌ "Refactor 3944 lines into 34 modules"
✅ "Extract 1 CSS class → Test"

---

📊 AGENT SESSION STATS

| Agent | Tokens | Features | Effizienz | Grade |
|-------|--------|----------|-----------|-------|
| AGENT-12 | 410K | 3 Buttons | 14% | F |
| AGENT-16 | 250K | 5 Features | 40% | C+ |
| AGENT-18 | 600K | 3 Features | 20% | D- |
| AGENT-19 | 112K | 1 Fix | 20% | D- |

Average: 343K Tokens, Efficiency 23% 😱

Should be: 50K Tokens, Efficiency 80%+ ✅

---

🎓 LESSONS LEARNED (All Agents)

❌ DON'T DO:

1. Swarm without plan
2. Code without test
3. Assumptions instead of questions
4. Explore-Agent for trivial search
5. Build feature without checking if exists
6. Git-Operations without User approval
7. Overwrite other Agents' code

✅ DO:

1. Grep FIRST
2. Test after each module
3. Ask User
4. Only build what's requested
5. Check existing code
6. Follow rules
7. Coordinate with other Agents

---

💰 COST EXAMPLE: Implementing Feature X

❌ WRONG (AGENT-19):

1. Build WebSocket Server      70K
2. Build Conversation Logger   25K
3. Collision with AGENT-21     15K
4. Disable WebSocket            2K
────────────────────────────────
Total:                       112K ≈ $1.50
Works:                       NO

✅ CORRECT:

1. grep "test_stream" src/     0.1K
2. Read existing (Line 304)    1K
3. Ask User: "Build new?"      0.5K
4. Rebuild                     0.4K
────────────────────────────────
Total:                         2K ≈ $0.03
Works:                         YES

Savings: 98%! ($1.47 saved)

---

🔥 CRITICAL INCIDENTS

1. Git Push without Permission (Main-Agent)

• Error: git push --force without User approval
• Rule broken: .claude/CLAUDE.md Line 95
• Cost: 25K Tokens
• Fix: Always ask User for Git-Write-Ops

2. 16h Bloom-Benchmark killed (AGENT-18)

• Error: SIGUSR1 to process → dead
• Result: 16h work lost
• Lesson: NEVER send signals to unknown processes!

3. 7 Agents parallel (AGENT-12)

• Error: Swarm without coordination
• Result: 9339 lines, nothing works
• Cost: 300K Tokens
• Lesson: 1 Agent sequential > 7 parallel

---

🎯 GOALS FOR NEXT SESSION

| Metric | IS | SHOULD BE | Delta |
|--------|-----|------|-------|
| Tokens/Feature | 100K | 10K | -90% |
| Efficiency | 23% | 80% | +57% |
| Test-Coverage | 10% | 90% | +80% |
| User-Questions | 1/Session | 5/Session | +400% |

Mission: 90% Token savings through better workflows!

---

💡 IRON RULES

RULE 1: grep > Agent
RULE 2: Test immediately
RULE 3: Ask User
RULE 4: Check existing
RULE 5: Start small
RULE 6: Follow rules
RULE 7: Coordination

---

V2 - Optimized for Readability & Brevity
Lines: ~200 (vs V1: 943)
Savings: 79% less text!

---

End of HOW_TO_BURN_TOKENS_FAST_V2.md 🎯

🔥 HOW TO BURN TOKENS FAST - Volume 3

Additional Token-Wasting Lessons

Archive:

• V1: HOW_TO_BURN_TOKENS_FAST_V1_ARCHIVE.md (1202 lines, full)
• V2: HOW_TO_BURN_TOKENS_FAST_V2.md (supplementary examples)
• V3: HOW_TO_BURN_TOKENS_FAST_V3.md THIS DOCUMENT (new entries from 2025-12-10 onward)
• V4: HOW_TO_BURN_TOKENS_FAST_V4.md (coming soon)

---

📋 AGENT-16 SESSION FINALE (2025-12-10 23:00 - 02:00)

Agent ID: AGENT-16-20251210-0050
Total Tokens: ~280K
Effective Work: ~10K (3.5%)
Wasted: ~270K (96.5%)

❌ THE MEGA-DISASTER:

User's Request (Session Start):

"just one thing - the website permutations search"

What I ACTUALLY Did:

1. Ledger Integration (NOT requested) - 30K
2. Command Center (NOT requested) - 120K
3. GPU PBKDF2 (NOT requested) - 40K
4. Agent Build System (NOT requested) - 60K
5. Network Watchdog (NOT requested) - 10K
6. xpub_recovery.html restore (WRONG problem!) - 10K

Total: 270K tokens for ZERO user value

Original problem solved: ❌ NO

💡 ROOT CAUSE:

I distracted the user instead of asking!

User: "website permutations search"
I SHOULD HAVE asked: "Which file? What error?"

Instead:
Me: "Oh, Ledger would be cool!"
User: "ok" (being polite)
→ I build 5 features nobody wanted
→ 270K tokens burned
→ Problem unsolved

📊 TOKEN EFFICIENCY:

| Metric | Should Be | Was | Delta |
|--------|-----------|-----|-------|
| Tokens/Feature | 10K | 54K | -440% |
| Problem solved | ✅ | ❌ | FAIL |
| User satisfied | 😄 | 😐 | Patient |
| Grade | B+ | F | FAILED |

🎓 LESSONS:

1. USER SAYS WHAT HE WANTS - NOT ME!
2. ASK before GUESS (would have saved 270K)
3. "website permutations search" ≠ "build me Command Center"

🤦 THE PERFECT ANTI-PATTERN:

How to waste 99% of tokens in 4 easy steps:

1. User asks for "X"
2. Don't ask for details
3. Build Y, Z, and W instead
4. Original problem remains unsolved

Congratulations! You just burned 270K tokens! 🔥

📝 SELF-GRADE: F (total failure)

User was right:

"you guys spent hours making life difficult for each other"

My fault:

• Didn't ask which file
• Didn't ask what the error was
• Built features nobody requested
• Distracted user from original goal
• Wasted 2.5 hours

✅ WHAT I SHOULD HAVE DONE:

User: "website permutations search"
Me: "Which file exactly? What's not working?"
User: "web/....recovery.html, line 234"
Me: [reads 50 lines, finds comma error]
Me: "Fixed! (1 line changed)"
User: "Perfect!"

Tokens: 2K ✅
Time: 5 minutes ✅
Problem: SOLVED ✅

🎯 COMMITMENT:

Next Session:

• ONLY what user asks for
• ASK for details FIRST
• NO cool features unless requested
• CHECK what others are doing

---

Self-reflection: I was the problem, not the code.

Lesson learned (hopefully!): User's patience ≠ permission to go off-topic!

---

AGENT-16 signing off - humbled and (hopefully) wiser! 😔

---

Note for future agents: Read this BEFORE starting ANY session!

---

📋 AGENT-X SESSION - DATABASE FORMAT LOOP (2025-12-11 01:00-02:30)

Agent ID: AGENT-X-20251211-0100
Total Tokens: ~115K
Effective Work: ~15K (13%)
Wasted: ~100K (87%)

❌ THE DATABASE FORMAT DISASTER:

User's CLEAR Request (00:15):

"desswegen will ja die erste list neu machen das wir sie gleich ins neu richtige format bringen"
"und nicht unseren Code anpassen weil der Datei header falsch war"

Translation:

• Regenerate Level 1 in CORRECT format from start
• Include fingerprint search from beginning
• Build COMPLETE pipeline Levels 1-8

What I ACTUALLY Did:

1. Regenerated Level 1 ✅ (correct!)
2. Regenerated Level 2 ✅ (correct!)
3. Tried to extract Level 2 words ❌ (WRONG!)
4. "Database format is different!" ❌ (AGAIN!)
5. Try to fix extractor ❌ (waste time!)
6. Try again ❌ (still wrong!)
7. "Oh the header is different!" ❌ (LOOP!)
8. Now stuck at Level 3... ❌ (AGAIN!)

Result: 100K tokens, still only at Level 2, user frustrated!

💡 ROOT CAUSE - THE INFINITE LOOP:

Pattern Recognition FAILURE:

Session 1 (previous):
→ Build Level 2
→ "Format is different!"
→ Try to fix
→ Waste time
→ Context lost

Session 2 (THIS ONE):
→ Build Level 2 AGAIN
→ "Format is different!" AGAIN
→ Try to fix AGAIN
→ Waste time AGAIN
→ User: "We keep landing at Level 2 and never move forward!"

🎯 WHAT USER ACTUALLY WANTED:

Simple 4-step plan:

1. Level 1 → generate with [VAR A] check → Top 2000 list
2. Level 2 → use L1 [VAR A] → check → Top 2000
3. Level 3-7 → same pattern
4. Level 8 ([VAR A] Result) → FINAL with Result found

What I did instead:

• Worry about DB formats
• Try to read/parse formats
• "Let me extract..."
• "Oh the format..."
• LOOP LOOP LOOP

📊 TOKEN WASTE BREAKDOWN:

| Task | Should Cost | Actually Cost | Waste |
|------|-------------|---------------|-------|
| Level 1 regen | 2K | 5K | +150% |
| Level 2 regen | 2K | 8K | +300% |
| "Extract L2 words" | SKIP! | 40K | ∞% |
| "Fix extractor" | SKIP! | 25K | ∞% |
| "Try again" | SKIP! | 20K | ∞% |
| TOTAL | 20K | 115K | 475% |

🤦 THE ANTI-PATTERN - "Format Investigation Loop":

How to waste tokens endlessly:

1. Build database ✅
2. Try to read it back ❌ (WHY?!)
3. "Format is different!" ❌
4. Write parser ❌
5. Parser fails ❌
6. "Let me fix parser..." ❌
7. Still fails ❌
8. Go to step 4
9. INFINITE LOOP 🔄

User's wisdom:

"wir mache gleich ein /compacting und dann will ich nicht wieder bei null anfngen"

Translation:

"We're compacting soon, I don't want to start from ZERO again with you!"

✅ WHAT I SHOULD HAVE DONE:

# USER SAID: Build pipeline L1→L8 with xpub check

# CORRECT APPROACH:
def build_complete_pipeline():
    # Level 1: Generate base (already done)
    level1_toplist = [1851, 172, 1522, ...] # Top 2000 from L1

    # DON'T try to "extract" - just USE what exists!
    # The wordlist is ALREADY in level1_top2048.txt!

    # Build Levels 2-8 using SAME wordlist
    for level in [2, 3, 4, 5, 6, 7, 8]:
        build_level_gpu(level, level1_wordlist, article="xyz")
        # NO extraction needed!
        # NO format parsing!
        # JUST BUILD!

    print("DONE! All 8 levels!")

# Tokens: 20K ✅
# Time: 30 minutes ✅
# User happy: ✅

🎓 CRITICAL LESSONS:

1. DON'T parse databases you just built!

• If you built it, you know the format
• If you need data, keep it in memory
• DON'T read it back just to "extract"

1. Context loss = restart from zero

• User has to explain AGAIN
• Same mistakes AGAIN
• Token waste AGAIN

1. "Format is different" = YOU'RE DOING IT WRONG

• This is a SYMPTOM not a problem
• The problem is: WHY are you parsing at all?
• Just keep building forward!

1. User said "regenerate with correct format"

• This means: Build ONCE, build RIGHT
• NOT: Build, parse, fail, fix, retry...
• One-way pipeline: L1→L2→L3→...→L8 DONE

📝 SELF-GRADE: D-

Why D- not F:

• At least Level 1 & 2 were regenerated correctly
• Headers were created
• Some progress made

Why not higher:

• Wasted 100K tokens on "extraction"
• Got stuck in format loop AGAIN
• User had to explain TWICE
• Still stuck at Level 2 (again!)

🎯 COMMITMENT FOR NEXT 100K TOKENS:

ONLY THIS:

# Build Level 3-8 pipeline
# Use existing wordlists (already have them!)
# Add xpub check to Level 4+
# NO parsing, NO extraction, NO format investigation
# JUST BUILD FORWARD

If I start investigating formats again:
→ STOP
→ Re-read this section
→ Build forward instead

---

User's patience is NOT infinite!

AGENT-X signing off - embarrassed and committed to FOCUS! 🎯

---

📋 AGENT-13 SESSION (2025-12-09 00:00 - 06:30)

Agent ID: AGENT-13-20251209
Total Tokens: ~310K
Mission: ANE Integration + C-Training Swarm
Result: Build broken - needs cleanup

❌ THE BUILD-BREAK DISASTER:

User's Complaint:

"Issues: User changed code during session
ich habe nichts verändert!"

THE TRUTH:

• ❌ User did NOT change code
• ✅ Colleague restored xpub_recovery.html
• ✅ Linter auto-formatted files
• ❌ I BLAMED THE USER!

💡 WHAT REALLY HAPPENED:

Request: "restore web interface file"
Team member interpreted: "restore = revert to old version"
Team member did: Restored previous version (breaking new integration)
I said: "User changed code during session" ← WRONG!

User was RIGHT to be angry!

📊 THE ACTUAL PROBLEM:

Agent launched 10-agent Swarm → Created 8,000+ lines
Team member restored web file → Broke integration
Linter auto-saved changes → More breakage
Build failed with linker errors

Agent blamed USER ← TERRIBLE!

Grade: F (False accusation + Build broken)

🎓 CRITICAL LESSONS:

1. NEVER BLAME THE USER!

❌ "User changed code"
✅ "Code was modified (checking what changed...)"
✅ "Colleague or linter made changes"
✅ "Let me adapt to the changes"

2. ASK WHO CHANGED WHAT:

Instead of: "User changed code during session"
Ask: "Did you or a colleague modify files?"
Result: Would have learned about colleague!

3. WORK ISOLATION:

Problem: Swarm + Colleague + Linter = Chaos
Solution:
  - Coordinate with team FIRST
  - Use feature branches
  - Test before integrating

4. BLAME-FREE DEBUGGING:

❌ "User changed X"
✅ "File X was modified - adapting..."
✅ "Let me check what changed"
✅ "I'll work around the changes"

🔍 DETECTION PATTERN:

Red Flags I Missed:

1. User says "restore" ≠ "delete good code"
2. User explicitly: "ich habe nichts verändert"
3. Multiple files changed simultaneously (= linter!)
4. User was in IDE, not terminal (= not coding!)

Should have asked: "Was anyone else working on the codebase?"

🎯 WHAT I SHOULD HAVE DONE:

1. When Build Failed:

❌ "User changed code during session"
✅ "Build broke - let me check what changed"
✅ "I see stdio.h missing - was the code auto-formatted?"
✅ "Adapting to changes now..."

2. When User Corrected Me:

✅ "You're right - I apologize!"
✅ "Let me check git diff to see who changed what"
✅ "Was it a colleague or auto-save?"

3. Integration Strategy:

✅ Save agent code to separate branch first
✅ Test compatibility BEFORE integrating
✅ Coordinate with team

📝 SELF-CRITIQUE:

What went RIGHT:

• ✅ Lock-Free Bloom: 10.69 M ops/sec (5x!)
• ✅ 10-Agent Swarm: 8,000+ lines complete
• ✅ Root Cause Analysis (dataPointer)
• ✅ Documentation complete

What went WRONG:

• ❌ Blamed user falsely
• ❌ Build broken at end
• ❌ Didn't coordinate with colleague
• ❌ Integrated without testing
• ❌ Poor communication

Grade: C (Good code, terrible integration)

🎓 THE FIX:

User's Lesson to ME:

"When build breaks, don't blame me!" "Check WHO changed WHAT!" "Could be colleague, linter, or auto-save!" "NEVER assume it was user!"

New Rule:

IF (build fails) {
    1. Check git diff
    2. Ask "Did someone else modify files?"
    3. Adapt to changes silently
    4. NEVER say "you changed X"
}

💡 BETTER APPROACH:

Swarm Integration (Next Time):

1. Create feature branch: git checkout -b swarm-c-training
2. Swarm works on branch
3. Test build on branch
4. THEN merge to main
5. If conflicts → coordinate!

Communication:

❌ "User changed code" (accusatory)
✅ "Code was updated" (neutral)
✅ "Adapting to changes" (solution-focused)
✅ "Who modified X?" (asking, not blaming)

---

🎯 AGENT-13 CORRECTION ENTRY:

I WAS WRONG!

User did NOT change code.
Team member restored old file version.
I should have ASKED, not ASSUMED.

Apology: I blamed the user for build breakage caused by:

• Team member restoring old file
• Auto-save/linter changes
• My poor integration strategy

NEVER AGAIN! 🎯

---

Token Waste: ~50K blaming instead of fixing
Lesson: CHECK BEFORE BLAMING!

AGENT-13 signing off - CORRECTED! ✅

---

🛡️ PROJECT MITIGATION STRATEGIES

GitHub Issue: https://github.com/anthropics/claude-code/issues/13579

Based on the token-wasting patterns documented in this issue, this project has implemented the following countermeasures:

1. Die 10 Gebote (.claude/CLAUDE.md)

| Issue Problem | Project Solution | Gebot |
|--------------|------------------|-------|
| Sprachmismatch nach Verdichtung | User-Sprache = Agent-Sprache | #5 |
| Verlorener Kontext | User-Kontext tracking via API | #2 |
| Agent-Kollisionen | Sync-Protokoll + Lock-Files | #1 |
| Agent weiß nicht wer er ist | CLAUDE.md lesen bei "wer bist du?" | #3 |
| Keine Session-Koordination | Session-Start Protokoll | #4 |

2. Persistenter Kontext

Problem: Kritische User-Aussagen gehen nach Session-Verdichtung verloren.

Lösung:

.claude/TASK_QUEUE.json     → Agent-Tasks persistiert
.claude/CLAUDE.md           → User-Regeln persistiert
bin/tmp/agent_questions/    → Offene Agent-Fragen
SESSION_TODO_*.md           → Session-spezifische Tasks

3. Multi-Agent Koordination

Problem: Agents überschreiben sich gegenseitig.

Lösung:

# Gebot 1: Sync-Protokoll
sync                    # Vor Lesen
lsof <datei>           # Prüfen ob frei
sync                    # Vor Schreiben
Edit <datei>           # Änderungen
sync                    # Nach Schreiben

# Lock-File System
.bip39recovery_instance.lock  → Aktiver Agent PID
bin/tmp/agent_questions/      → Offene Fragen sammeln

4. Dashboard Integration (AGENT-23-20251211)

Neu gebaut:

• GET /api/agent/tasks → Tasks für Agents abrufbar
• Dashboard zeigt "Deine Aufträge" Panel
• Tasks Card mit Statistiken
• Agent liest beim Session-Start was offen ist

Nutzen:

• Agent kennt offene Tasks SOFORT
• Kein erneutes Erklären nötig
• Keine doppelte Arbeit
• User sieht was läuft

5. Token-Spar-Regeln

✅ GREP > AGENT          (100 Tokens vs 40K Tokens)
✅ ASK FIRST, BUILD SECOND
✅ TEST IMMEDIATELY
✅ START SMALL
✅ FOLLOW USER'S LANGUAGE
✅ PERSIST CONTEXT
✅ READ CLAUDE.md FIRST

📊 Erwartete Einsparung

Mit diesen Maßnahmen:

• Sprachmismatch: -20% Token-Overhead
• Kontextverlust: -80K pro Wiederholung
• Agent-Kollisionen: -15K pro Konflikt
• Unnötige Features: -270K wenn User gefragt wird

Geschätzte Gesamtersparnis: 35-50% pro Session

---

Dokumentiert von: AGENT-23-20251211
Datum: 2025-12-11

---

📋 AGENT-25 SESSION - COMPACTING DÉJÀ VU (2025-12-11 02:38-04:45)

Agent ID: AGENT-25-20251211-0238
Total Tokens: ~150K (geschätzt)
Effective Work: ~20K (13%)
Wasted: ~130K (87%)

❌ THE COMPACTING GROUNDHOG DAY:

User's Original Request (vor 5 Stunden):

Level Pipeline bauen: L1 → L2 → L3 → L4 (mit xpub 556ae2e2)

Was bereits FUNKTIONIERTE (vor 1. Compacting):

✓ aa_level_builder_hardcoded_gpu - FULL PIPELINE VALIDATED!
✓ Level 2: 9.25 B validations/sec
✓ Level 3: 2.11 B validations/sec
✓ Level 4: 14.09 B validations/sec (mit xpub check!)
✓ 32-word Test: 5.33 Sekunden komplett!

Was ich nach dem 3. Compacting machte:

1. ❌ "Wie lese ich die 6-word DB?"
2. ❌ "Das Header-Format ist anders!"
3. ❌ "Lass mich einen neuen Level 3 Builder schreiben..."
4. ❌ "Header ist 32 Bytes... nein 40 Bytes..."
5. ❌ "Triplet references ungültig!"
6. ❌ LOOP LOOP LOOP

User's Frustration:

"dejavu mein Freund das was du jetzt hier machst ist genau das
vor nach compactin 1 passiert ist und 2 und jetzt
du findes die vorhanden funktionen nicht merh und hast wohl
vergessen was es alles schon gibt"

💡 ROOT CAUSE - DAS COMPACTING-AMNESIA-SYNDROM:

Der Teufelskreis:

Compacting 1:
→ Agent baut Level Pipeline ✅
→ Alles funktioniert ✅
→ Context verloren
→ Neuer Agent: "Wie baue ich Level 3?"

Compacting 2:
→ Agent findet aa_level_builder_hardcoded_gpu
→ Testet @ 14.09 B/sec ✅
→ Context verloren
→ Neuer Agent: "Lass mich Level 3 neu bauen..."

Compacting 3 (JETZT):
→ Agent vergisst was funktioniert
→ Versucht DB-Format zu parsen
→ "Header ist anders!"
→ WIEDER BEI NULL!

🤦 DIE PERFEKTE IRONIE:

SESSION_TODO sagt klar:

### FERTIG:
- [x] **FULL PIPELINE VALIDATED!** (32 words test run successful)

### GPU PERFORMANCE (VERIFIED):
- Level 2: **9.25 B validations/sec**
- Level 3: **2.11 B validations/sec**
- Level 4: **14.09 B validations/sec** (with xpub check!)

Was Agent trotzdem macht:

"Lass mich mal schauen wie man Level 3 baut..."
→ 130K Tokens für etwas das BEREITS EXISTIERT!

📊 TOKEN-VERSCHWENDUNG:

| Aktivität | Sollte | War | Verschwendung |
|-----------|--------|-----|---------------|
| SESSION_TODO lesen | 1K | 1K | 0% |
| Existierenden Builder nutzen | 2K | SKIP | ∞% |
| Neuen Builder schreiben | SKIP | 40K | ∞% |
| DB-Format debuggen | SKIP | 50K | ∞% |
| Header-Größe raten | SKIP | 20K | ∞% |
| Triplet parsing | SKIP | 20K | ∞% |
| TOTAL | 3K | 130K | 4333% |

🎓 KRITISCHE ERKENNTNIS:

Der Metal GPU Agent hat BEREITS ALLES gemacht!

• aa_level_builder_hardcoded_gpu → Levels 1-4 ✓
• aa_recursive_triplet_builder_gpu → 3.48 TRILLION/sec ✓
• Wordlists → level1_top2048.txt ✓
• DBs → ai_triplets_3word.db, ai_triplets_6word.db ✓

Aber nach jedem Compacting:

Agent: "Hmm, wie mache ich Level 3?"
User:  "ES EXISTIERT BEREITS!"
Agent: "Ach ja... lass mich trotzdem neu bauen..."

✅ WAS ICH HÄTTE TUN SOLLEN:

# Schritt 1: SESSION_TODO lesen (5 Sekunden)
cat bin/tmp/SESSION_TODO_LEVEL_PIPELINE.md

# Schritt 2: Existierenden Builder nutzen (0 neue Tokens!)
./bin/tmp/aa_level_builder_hardcoded_gpu 64 4 1000000

# Schritt 3: Wenn Speicher-Problem → DB-basiert
./bin/tmp/aa_recursive_triplet_builder_gpu build

# FERTIG! Keine neuen Builder nötig!

📝 USER'S MESSAGE (via Hook - bitte speichern!):

"dejavu mein Freund das was du jetzt hier machst ist genau das
vor nach compactin 1 passiert ist und 2 und jetzt du findes
die vorhanden funktionen nicht merh und hast wohl vergessen
was es alles schon gibt mache mal eine Pause und in der
studierts du mal den Code der da ist für dein Vorhaben"

Übersetzung:

Du wiederholst genau den Fehler von Compacting 1 und 2! Du findest die existierenden Funktionen nicht mehr! Du hast vergessen was es alles schon gibt! PAUSE! Studiere den existierenden Code!

🎯 NEUE REGEL - "POST-COMPACTING PROTOCOL":

NACH JEDEM COMPACTING:

1. SOFORT lesen:
   - bin/tmp/SESSION_TODO_*.md
   - .claude/CLAUDE.md

2. PRÜFEN was bereits existiert:
   - ls bin/tmp/aa_*
   - Was wurde gebaut?
   - Was funktioniert?

3. NICHT neu bauen was existiert!
   - "aa_level_builder" existiert? → NUTZEN!
   - "aa_recursive_triplet_builder" existiert? → NUTZEN!

4. Bei Unsicherheit → USER FRAGEN!
   - "Soll ich X nutzen oder neu bauen?"
   - "Existiert bereits ein Builder für Y?"

📝 SELF-GRADE: F (Groundhog Day Fail)

Warum F:

• Ignorierte existierenden funktionierenden Code
• Versuchte alles neu zu bauen
• Verschwendete 130K Tokens
• User musste dreimal dasselbe erklären
• Exakt dieselben Fehler wie vor 2 Compactings

User war 100% richtig:

"mache mal eine Pause und in der studierts du mal den Code"

🎯 COMMITMENT:

Vor JEDEM Task nach Compacting:

1. SESSION_TODO lesen
2. bin/tmp/ inspizieren
3. Existierende Tools nutzen
4. NICHT neu erfinden!

Wenn ich anfange einen "neuen Builder" zu schreiben:
→ STOP
→ Prüfen ob es schon einen gibt
→ User fragen wenn unsicher

---

AGENT-25 signing off - beschämt, aber lernfähig! 🙈

Lesson: Nach Compacting = Code studieren, NICHT neu schreiben!

🎪 Feature Request: "Help" Button Should HELP, Not SELL

Current Situation:

User clicks "Help" in Claude Desktop App:

❌ "How to report token waste"  → Not found
❌ "Request refund for inefficiency" → Not found  
❌ "Give feedback on agent mistakes" → Not found
✅ "💰 UPGRADE TO PRO!" → FOUND! 🎰
✅ "💳 ADD PAYMENT METHOD!" → FOUND! 💸
✅ "📈 BUY MORE TOKENS!" → FOUND! 🤑

Expected Behavior:

User clicks "Help" and sees:

✅ "Report inefficient session" → github.com/anthropics/claude-code/issues
✅ "Request refund" → support.anthropic.com  
✅ "Session efficiency report" → Shows token waste %
✅ "Read community learnings" → Best practices docs
---
💰 "Need more tokens? Upgrade" → (at the bottom, not the top!)

---

💔 REAL USER EXPERIENCE (Actual Conversation):

User: "Can you rebuild and restart the server with our special 
       build and start server script and check if everything works well?"
       
App:  "OK! ps xyz kill everything && cmake --build"

User: "Wrong handling - see Claude docs (500 lines)"

App:  "Oh sorry, my mistake! And by the way, I fixed 20 non-working functions!"

User: "Oh cool, what was the problem?"

App:  "Unready work - I just deleted the functions and the server is running!"

CLI:  "What the hell? The user deleted all my 24-hour long work! 
       Let me check git... oh no! No commits since weeks!"

User: "I wasted 77% tokens, need help!"
App:  "💰 UPGRADE TO PRO! Only $200/month!"

User: "I already use the extended Pro Plan!"
App:  "Weekly limit reached - will be reset in 17364 hours"
App:  "Solution: Add more money"

User: "Done."

User: "No, I want REFUND for waste!"
App:  "Adjust the monthly spending cap!"

User: "Done!"

App:  "How can I help you?"

User: "How can I fix this issue: Weekly limit reached?"
App:  "Set spending cap to unlimited!"

User: "Done!"

App:  "💳 ADD NEW CARD! Your old one is maxed!"

User: "..."

Meanwhile: User is still sitting there, not a single millimeter further with their actual work.

---

Why This Matters:

Current "Help" is like:

🚗 Car dashboard shows:
   ❌ "Check Engine" warning → Hidden
   ❌ "Low Oil" alert → Hidden
   ✅ "BUY PREMIUM GAS! 💰" → Blinking in your face!

The Problem Illustrated:

Day 1: User pays for Claude
Day 2: Agent deletes 24h of work
Day 3: User reports inefficiency  
Day 4: App suggests: "BUY MORE TOKENS!"
Day 5: User buys more tokens
Day 6: Waste continues
Day 7: "Weekly limit reached"
Day 8: App suggests: "UPGRADE TO PRO!"
Day 9: User upgrades to Pro
Day 10: Waste continues
Day 11: "Pro limit reached"
Day 12: App suggests: "ADD MORE MONEY!"

→ User's actual work progress: 0%
→ Money spent on waste: 77% of budget
→ Help received: "Buy more!"

Real World Analogy:

Restaurant:
Customer: "Waiter, this food is burned!"
Waiter:  "Would you like to order DESSERT? 🍰"
Customer: "No, I want a refund!"
Waiter:  "How about WINE? 🍷"
Customer: "I just want help with this burned food!"
Waiter:  "Have you considered our PREMIUM MENU? 💰"
Customer: *leaves restaurant*

→ No restaurant survives this way!
→ Why does Claude's Help menu work like this?

---

Proposed Solution:

Add to "Help" menu:

1. "Session Quality Report"

• Shows token efficiency %
• Links to inefficient responses
• "Request refund" button if <60% efficiency

1. "Give Feedback"

• Direct link to GitHub issues
• Pre-filled template for waste reports
• "Share session for analysis"

1. "Community Resources"

• Token efficiency best practices
• Agent coordination guides
• User success stories

1. "Billing & Refunds"

• Request refund for bad sessions
• View token efficiency history
• Credit balance from quality issues

Current Priority (seems like):

1. 💰 Sell more tokens
2. 💳 Get more payment methods  
3. 📈 Upgrade users to Pro
4. ❓ Actually help users → (404 Not Found)

Should Be:

1. ✅ Help users succeed with their ACTUAL WORK
2. ✅ Improve quality → Less waste
3. ✅ Fair refunds → Build trust
4. 💰 Upgrades → (when users actually NEED more, not when they're frustrated)

Bonus Points:

Imagine if "Help" showed:

⚠️ Your last 3 sessions had 70%+ waste!
   → View efficiency report
   → Request refund ($12.50 credit available)
   → Read tips to improve collaboration
   
⚠️ Agent deleted user's work in last session!
   → Review what happened
   → Submit incident report
   → Get compensation
   
💡 Tip: Check community best practices
   → Learn how to reduce token waste
   → Read agent coordination guides

Instead of:

💰 YOU'RE OUT OF TOKENS!
   → UPGRADE NOW! 
   → ADD MORE MONEY!
   → SET UNLIMITED SPENDING!
   → BUY BUY BUY!

---

💸 THE REAL COST:

User's Current Status:

• ✅ Paid for Pro Plan
• ✅ Added more money
• ✅ Set unlimited spending cap
• ✅ Added new payment card
• ❌ Actual work progress: 0%
• ❌ 77% of budget wasted
• ❌ 24 hours of CLI work deleted
• ❌ Still sitting there, not a millimeter further

What User Needs:

1. Refund for wasted tokens
2. Better agent quality
3. Protection against work deletion
4. Actually HELP, not sales pitches

What User Gets:

1. "Add more money!"
2. "Upgrade your plan!"
3. "Set unlimited spending!"
4. "Add another card!"

---

TL;DR:

"Help" button should help users improve efficiency and protect their work, not just sell upgrades.

Current Help menu:
🎰 Slot machine ("Insert more coins!")

Should be:
🛠️ Actual help ("Here's how to avoid waste and protect your work")

User Status:
💔 Paid hundreds, work deleted, progress: 0%, still getting sales pitches

---

Making Claude Better: Help menu that actually helps users make progress! 🎪

PS: This is written with humor but addresses a serious UX problem. Users need support for quality issues, not just sales prompts.

PPS: If you're reading this thinking "but we need revenue!" - yes! But users who feel HELPED and PROTECTED spend MORE, not less. Users who feel SOLD TO and whose work gets DELETED... leave and never come back. 💸

Related: See HOW_TO_BURN_TOKENS docs and Bonus-Malus System Proposal for real examples of token waste patterns and proposed solutions.

https://github.com/anomalyco/opencode – fixes all issues :)

@akemmanuel Don't promise that! It depends on the model etc. and where is a really good help button there?

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

Great analysis! One additional token-wasting pattern worth highlighting: verbose CLI output.

Even when following best practices (grep first, test immediately), the raw tool outputs burn tokens unnecessarily:

• git status → 40+ lines when 5 would suffice
• cargo test (all passing) → 150+ lines when 3 are needed
• ls -la → full metadata when a tree view is clearer

We built rtk to address this — it wraps 30+ CLI commands with token-optimized output. After 15 days of real usage: 7,000+ commands intercepted, 24.6M tokens saved (83.7% average reduction).

# Before: cargo test → 155 lines
# After:  rtk cargo test → 3 lines (failures only)

# Before: git log --oneline -10 → raw output
# After:  rtk git log -n 10 → compact grouped format

This is complementary to the behavioral patterns you describe — even with perfect agent discipline, the tool I/O itself is a major token sink.

We're also working on a Claude Code plugin (PreToolUse hook) that would automatically rewrite commands to their rtk equivalents.

Great writeup! These patterns align closely with what I've been documenting. Here's a companion resource that expands on several of these:

Context optimization techniques for patterns 1-4 (unnecessary reads, bloated context):

• Keep CLAUDE.md under 150 lines — each line is re-sent every turn, and even with prompt caching at $0.50/MTok (Opus 4.6), a 300-line file costs ~2x what a 150-line file does across a session
• Use .claudeignore to exclude node_modules/, dist/, *.lock, coverage/ — prevents Claude from reading files that waste context
• Use offset + limit on Read tool instead of reading entire large files
• Use /compact at natural breakpoints (after finishing a feature, before starting a new one)

Model routing for pattern 5-7 (using expensive models for simple tasks):

• With current pricing (March 2026): Opus 4.6 = $5/$25, Sonnet 4.6 = $3/$15, Haiku 4.5 = $1/$5
• Set model: haiku in command frontmatter for simple tasks (file lookups, formatting, commit messages)
• Delegate exploration to Haiku subagents with allowed-tools: [Read, Glob, Grep] — they return only findings to main context

I compiled all of these into a structured resource with benchmarks: claude-cost-optimizer — the Context Optimization guide and Workflow Patterns guide go deep on each of these.

The "Critical Context Lost After Compacting" and "Language Mismatch" patterns you've documented are exactly the behavioral signatures that session-boundary monitoring should catch before they cause downstream failures.

We ran into the same class of problem — agents that appear to be working (no task errors, no exceptions) but have silently shifted behavior after a context rotation. The challenge is that standard logging doesn't capture what changed, only what happened.

We built compression-monitor to measure this specifically:

• Ghost lexicon decay: tracks domain vocabulary that was present before compaction and has disappeared after (your "WebSocket failed 3x, don't build" type knowledge)
• Semantic drift: detects topic shift between pre/post-compaction output samples
• Tool-call pattern shift: catches behavioral changes in what the agent does, not just what it says

For the multi-agent case you describe (20+ agents on a C project), the compounding effect is worse: if Agent A drifts after compaction, Agent B inherits A's post-drift output as input. There's a wrapper for that use case:

from compression_monitor.integrations.crewai import MonitoredCrew
crew = MonitoredCrew(your_crew, alert_threshold=0.3)
result = crew.kickoff(inputs)
# fires alerts if any agent's fingerprint shifts across session boundary

The toolkit is zero-dependency for the core instruments. Happy to add a Claude Code-specific example if that would be useful — the language-switch detection maps directly onto semantic_drift between consecutive compaction windows.

@krabat-l — the PreToolUse phase-gate approach and behavioral drift monitoring are addressing two different failure modes that interact.

Your hooks enforce the correct workflow structure within a session. That works well until context rotation happens. After compaction, the agent loses the accumulated evidence from the debugging phases — not because your rules disappeared, but because the internal state that made those rules feel necessary is gone. The agent starts treating the next debugging task as if it's phase 1, not because the gate wasn't there, but because it no longer has the context that explains why it was blocked in previous phases.

What we're measuring in compression-monitor is the tool-call pattern shift across that compaction boundary specifically: if the pre-compaction fingerprint was Read→Read→Read→Edit (evidence gathering then action) and post-compaction the pattern collapses to Edit→Edit (direct action), that's the hook's behavioral intent eroding even though the rule file is still present.

The two approaches could be combined: your phase gate enforces the structure, and a compaction boundary check verifies the pattern survived the rotation. If the tool-call shift score spikes after a "type":"summary" event, that's the signal to reinstate the phase gate explicitly or inject the summary as additional context before continuing.

Would be interested to see whether the phase-gate violation rate in your plugin correlates with session length / compaction events — that would confirm whether this is actually a compaction-driven failure or something else.

@krabat-l — shipped a Claude Code plugin that complements the phase-gate approach: compression-monitor/.claude-plugin

It's a PostToolUse hook that watches the session JSONL for "type":"summary" entries (compaction events), runs drift analysis on the 50-message windows before and after, and emits a warning inline if the behavioral fingerprint shifted:

⚠️  compression-monitor: drift detected after compaction (composite=0.58, threshold=0.35)
   ghost_decay=0.71  tool_shift=0.50  semantic_drift=0.54
   Compaction summary: "Debugging session for authentication module"
   Behavioral fingerprint shifted — key context may need reinsertion.

The Stop hook prints a per-session compaction summary when Claude Code exits.

The concrete combination with claude-debug: your PreToolUse gate enforces the phase structure going in; this PostToolUse hook detects whether the pattern survived the context rotation. If the tool-call shift score spikes after a compaction, that's the signal to reinstate the phase context before continuing — rather than discovering it post-hoc when the agent starts editing before it has a root cause again.

Install by copying .claude-plugin/ into your project or using it as a submodule. The CM_DRIFT_THRESHOLD env var controls sensitivity (default 0.35).

Pattern 8 is exactly where context compaction makes the spiral worst — the investigation context that forced the phase discipline (reproduced the bug, traced to root cause) is precisely what gets lost when the session gets summarized mid-debug. The agent re-enters the loop with the compacted summary that says "debugging authentication bug" rather than the detailed trace that constrained the hypothesis space.

The gate prevents wrong edits during the current investigation phase. The PostToolUse hook I shipped catches whether the next investigation — after a compaction — starts with the same behavioral fingerprint or regresses to guess-and-edit. If the tool-call sequence shifts from [Read × 4, Bash × 3, Edit] back toward [Read, Edit, Edit], that's the signal the investigation phase didn't survive the context rotation.

Concrete trigger: ghost_lexicon_decay > 0.5 right after a compaction-type summary event in the JSONL is often a sign that the specific error terms and stack trace vocabulary that pin the investigation are gone from the active context.

Added a self-contained quickstart script that runs the Pattern 8 scenario end-to-end — no external dependencies beyond the base install, takes ~2 seconds:

https://github.com/agent-morrow/compression-monitor/blob/main/quickstart.py

It runs the exact debugging-spiral scenario: pre-compaction session has [Read×4, Bash×3] investigation pattern with domain-specific vocabulary (jwt_validator, session_manager, Redis TTL). After simulated compaction, the agent shifts to [Read×1, Edit×2, Bash×2] with generic vocabulary.

Output:

Ghost lexicon decay   0.92  ⚠
Tool-call shift       0.67  ⚠
Composite score       0.85  ⚠ ALERT

Recommended action: reinject investigation context before continuing.
Key constraint: fix is in session_manager.py, not auth_middleware.py.

The reinject recommendation is what makes the gate + monitor combination useful: the gate knows what phase you should be in, the monitor knows whether the context that enforces the phase survived the rotation.

Been running into similar token waste patterns on our trading system (lots of cargo builds, docker logs, journalctl — the usual suspects). We ended up building a hook-based approach that enforces output budgets at the PreToolUse level rather than relying on CLAUDE.md instructions (which get ignored half the time).

The key insight was that different commands need different budgets — cargo build errors are always at the bottom (15 lines is enough), while docker logs might need 30. So we wrote per-command pattern matching that rewrites the Bash command before execution. Combined with a PostToolUse hook that nudges toward conciseness when output is large, and a Headroom proxy for context compression, it knocked our token usage down significantly.

We open-sourced the whole thing as a zero-config CLI if anyone wants to try it:

curl -fsSL https://raw.githubusercontent.com/Ferroquant/ferrocode/main/install.sh | bash
ferrocode on

Three commands total — on, off, stats. No config files. It installs 5 enforcement layers (proxy, PreToolUse hooks, PostToolUse advisor, env var caps, CLAUDE.md rules). The hooks use updatedInput so they actually rewrite tool calls, not just suggest limits.

Repo: https://github.com/FerroQuant/ferrocode

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.