# How to Verify Token Savings

This guide shows you how to access detailed logs and verify that the Token Optimizer MCP is actually saving you tokens.

## Log Locations

All logs are stored in `~/.claude-global/hooks/logs/` (or `C:\Users\{username}\.claude-global\hooks\logs\` on Windows):

- **Main orchestrator log**: `token-optimizer-orchestrator.log`
- **Dispatcher log**: `dispatcher.log`
- **MCP tool call log**: `token-optimizer-calls.log`

## What to Look For

### Cache Hit Log Entries

When the optimizer retrieves a file from cache (saving tokens), you'll see entries like:

```
[2025-10-20 04:35:15] [INFO] [cache-retrieval] Checking cache for: C:\path\to\file.ts
[2025-10-20 04:35:15] [INFO] [cache-retrieval] CACHE HIT: C:\path\to\file.ts (saved tokens!)
[2025-10-20 04:35:15] [INFO] [cache-retrieval] Cache retrieval stats: Cached content: 85 estimated tokens
```

**What this means**: Instead of reading the full file (e.g., 1250 tokens), Claude received the compressed cached version (85 tokens), saving **1165 tokens** (93% reduction).

### Cache Miss Log Entries

When a file is NOT in cache (first read), you'll see:

```
[2025-10-20 04:35:10] [DEBUG] [cache-retrieval] Cache miss: C:\path\to\file.ts (will cache after Read)
[2025-10-20 04:35:11] [INFO] [auto-cache] Cached C:\path\to\file.ts: 1250 -> 85 tokens (93.2% reduction)
```

**What this means**: The first read pays full cost (1250 tokens), but future reads of this file will use the cached 85-token version.

## Real-Time Monitoring

### Watch Logs in Real-Time (PowerShell)

```powershell
# Watch orchestrator log for cache hits
Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log -Wait -Tail 20 | Where-Object { $_ -match "CACHE HIT|Cache retrieval" }

# Watch all optimization activity
Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log -Wait -Tail 50
```

### Watch Logs in Real-Time (Unix/Mac)

```bash
# Watch orchestrator log for cache hits
tail -f ~/.claude-global/hooks/logs/token-optimizer-orchestrator.log | grep "CACHE HIT\|Cache retrieval"

# Watch all optimization activity
tail -f ~/.claude-global/hooks/logs/token-optimizer-orchestrator.log
```

## Session Statistics

### View Current Session Stats

Check the operations CSV for your current session:

```powershell
# Find your current session ID
$session = Get-Content ~\.claude-global\hooks\data\current-session.txt | ConvertFrom-Json
$sessionId = $session.sessionId

# View operation log
Get-Content ~\.claude-global\hooks\data\operations-$sessionId.csv | ConvertFrom-Csv | Format-Table
```

### Calculate Total Savings

Search logs for all cache hits in a session:

```powershell
# Count cache hits
Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log | Select-String "CACHE HIT" | Measure-Object

# Get detailed cache hit stats
Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log | Select-String "Cache retrieval stats" | ForEach-Object { $_ }
```

## Expected Results

### Multi-Read Scenario (Same Session)

**First read** of `src/server/index.ts`:
```
[DEBUG] Cache miss: src/server/index.ts (will cache after Read)
[INFO] Cached src/server/index.ts: 1250 -> 85 tokens (93.2% reduction)
```

**Second read** of same file:
```
[INFO] CACHE HIT: src/server/index.ts (saved tokens!)
[INFO] Cache retrieval stats: Cached content: 85 estimated tokens
```

**Token savings**: 1250 - 85 = **1165 tokens saved** (93% reduction)

### Cross-Session Scenario

**Session 1** - First read:
```
[DEBUG] Cache miss: package.json (will cache after Read)
[INFO] Cached package.json: 450 -> 35 tokens (92.2% reduction)
```

**Session 2** (new conversation, same file):
```
[INFO] CACHE HIT: package.json (saved tokens!)
[INFO] Cache retrieval stats: Cached content: 35 estimated tokens
```

**Token savings**: 450 - 35 = **415 tokens saved** (92% reduction) even in new session!

## Troubleshooting

### Not seeing cache hits?

1. **Check that files are being cached**:
   ```powershell
   Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log | Select-String "Cached.*->"
   ```

2. **Verify cache database exists**:
   ```powershell
   Test-Path ~\.token-optimizer-cache\cache.db
   ```

3. **Check for errors**:
   ```powershell
   Get-Content ~\.claude-global\hooks\logs\token-optimizer-orchestrator.log | Select-String "ERROR"
   ```

### Cache not persisting across sessions?

Check SQLite database location:
```powershell
# Should show cache.db file
Get-ChildItem ~\.token-optimizer-cache\
```

### No logs appearing?

Verify hooks are enabled:
```powershell
# Check if dispatcher.ps1 exists
Test-Path ~\.claude-global\hooks\dispatcher.ps1

# Check recent log activity
Get-ChildItem ~\.claude-global\hooks\logs\ | Sort-Object LastWriteTime -Descending | Select-Object -First 5
```

## Performance Metrics

### Typical Token Reduction

Based on production usage:

- **Text files**: 85-95% reduction (Brotli compression)
- **Code files**: 90-95% reduction (highly compressible)
- **JSON/config files**: 88-93% reduction
- **Binary/media files**: Not cached (not worth compressing)

### Expected Hit Rate

- **First conversation**: 0% cache hits (everything is new)
- **Continued work on same project**: 40-60% cache hits
- **Refactoring/review sessions**: 70-85% cache hits (lots of re-reads)
- **Cross-session work**: 50-70% cache hits (SQLite persistence)

## Advanced: Query Cache Database Directly

```powershell
# Install sqlite3 if needed
# choco install sqlite (Windows)
# brew install sqlite (Mac)

# Query cache stats
sqlite3 ~\.token-optimizer-cache\cache.db "
  SELECT
    key AS file_path,
    hit_count,
    original_size,
    compressed_size,
    ROUND(100.0 * (original_size - compressed_size) / original_size, 1) AS reduction_pct,
    datetime(created_at/1000, 'unixepoch') AS cached_at,
    datetime(last_accessed_at/1000, 'unixepoch') AS last_used
  FROM cache
  ORDER BY hit_count DESC
  LIMIT 20;
"
```

## Summary

**Quick verification checklist**:

1. ✅ Check logs show "CACHE HIT" entries
2. ✅ Verify "Cache retrieval stats" show low token counts (85-95% reduction)
3. ✅ Confirm cache.db file exists and is growing
4. ✅ See cache misses followed by caching on first read
5. ✅ See cache hits on subsequent reads of same file

If all 5 are true, your token optimizer is working correctly and saving 85-95% on cached operations!