feat: add token savings data to current-session.txt for easy real-time monitoring

[ooples]

Problem

Currently, current-session.txt only tracks operation counts, NOT actual token savings:

{
    "lastOptimized": 0,
    "sessionId": "aad1f532-43d3-44af-ba65-6f89c409b122",
    "sessionStart": "20251031-082211",
    "totalOperations": 2201,
    "totalTokens": 0
}

Users must manually call get_session_stats() MCP tool to see their savings. This creates friction for:

• Real-time monitoring during sessions
• Quick checks of optimization effectiveness
• Dashboard integrations
• Automation scripts

Proposed Solution

Auto-update current-session.txt with token savings data from get_session_stats():

{
    "sessionId": "aad1f532-43d3-44af-ba65-6f89c409b122",
    "sessionStart": "20251031-082211",
    "totalOperations": 2201,
    "savings": {
        "totalTokensSaved": 125430,
        "tokenReductionPercent": 68.2,
        "originalTokens": 184000,
        "optimizedTokens": 58570,
        "cacheHitRate": 42.5,
        "compressionRatio": 3.2,
        "lastUpdated": "20251031-092500"
    }
}

Implementation

Where: handlers/token-optimizer-orchestrator.ps1 - Update-SessionOperation function

How:

1. After incrementing totalOperations, call token-optimizer MCP's get_session_stats
2. Extract savings data from response
3. Add savings object to session file
4. Write atomically to prevent corruption

Code Example:

function Update-SessionOperation {
    # ... existing operation count logic ...

    # Auto-update token savings every N operations (e.g., every 10)
    if ($session.totalOperations % 10 -eq 0) {
        try {
            $stats = Invoke-MCP -Server "token-optimizer" -Tool "get_session_stats" -ToolArguments @{}

            if ($stats -and $stats.result) {
                $savingsData = $stats.result.content[0].text | ConvertFrom-Json

                $session.savings = @{
                    totalTokensSaved = $savingsData.totalTokensSaved
                    tokenReductionPercent = $savingsData.tokenReductionPercent
                    originalTokens = $savingsData.originalTokens
                    optimizedTokens = $savingsData.optimizedTokens
                    cacheHitRate = $savingsData.cacheHitRate
                    compressionRatio = $savingsData.compressionRatio
                    lastUpdated = Get-Date -Format "yyyyMMdd-HHmmss"
                }
            }
        } catch {
            Write-Log "[WARN] Could not update token savings: $($_.Exception.Message)" "WARN"
        }
    }

    # Write updated session
    $session | ConvertTo-Json -Depth 10 | Out-File $SESSION_FILE -Encoding UTF8
    return $session
}

User Experience Improvements

Before (current):

# User must manually call MCP tool
$stats = Invoke-MCP -Server "token-optimizer" -Tool "get_session_stats" -ToolArguments @{}
$stats.result.content[0].text | ConvertFrom-Json

After (proposed):

# User can just read the file
Get-Content "C:\Users\cheat\.claude-global\hooks\data\current-session.txt" -Raw | ConvertFrom-Json
# Savings data is already there!

Benefits:

• No MCP calls needed for quick checks
• Dashboard-friendly (just poll the file)
• Automation-friendly (parse JSON directly)
• Real-time visibility into optimization effectiveness

Success Criteria

• current-session.txt includes savings object with 7 fields
• Savings data updates automatically during session (every 10 operations)
• Handles MCP errors gracefully (logs warning, continues without savings data)
• Performance impact < 50ms per update (batched every 10 operations)
• Documentation updated in README.md explaining the new fields

Related Issues

• feat: implement granular per-hook/per-action/per-MCP-server token analytics #112 (granular token analytics) - This issue provides simplified user-facing version of that data

[github-actions]

This issue has been resolved in version 4.1.0. 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀