🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

Token Usage Optimizer

by @rusel95

Maximize your Claude Code subscription value with smart usage monitoring and burn rate optimization. Track 5-hour session and 7-day weekly quotas, get one-ti...

Versionv1.0.5
Downloads1,319
Installs2
TERMINAL
clawhub install token-usage-optimizer

πŸ“– About This Skill


name: token-usage-optimizer version: 1.0.5 description: Maximize your Claude Code subscription value with smart usage monitoring and burn rate optimization. Track 5-hour session and 7-day weekly quotas, get one-time alerts, and daily reports showing if you're under/over-using your $20-200/month plan. Ultra-lightweight (10min cache, minimal API calls). Perfect for Pro, Max 100, and Max 200 subscribers who want to get every dollar's worth. metadata: clawdbot: emoji: "πŸ“Š" os: - darwin - linux requires: bins: - curl - date - grep

Token Usage Optimizer

Version: 1.0.5

Get the most out of your Claude Code subscription by monitoring usage in real-time and optimizing your daily burn rate.

Why Use This?

You're paying $20-200/month for Claude Code. Are you:

  • βœ… Using it to its full potential?
  • ❌ Hitting limits too early?
  • ❌ Leaving quota unused at reset?
  • This skill tracks your 5-hour session and 7-day weekly quotas, calculates your daily burn rate, and tells you if you should use more or throttle back.

    Features

  • πŸ“Š Burn Rate Tracking β€” Are you under/over/on-pace for optimal usage?
  • ⚑ Smart Alerts β€” One-time warnings when SESSION > 50% (no spam)
  • 🎯 Plan-Aware β€” Auto-detects Pro ($20), Max 100 ($100), Max 200 ($200)
  • πŸ’Ύ Ultra-Lightweight β€” 10-minute cache, minimal API calls
  • πŸ“… Daily Reports β€” Evening summary: SESSION, WEEKLY, burn rate
  • πŸ”„ Token Health Check β€” Hourly check + alert if manual refresh needed (~once per week)
  • Quick Start

    1. Setup

    Run the setup wizard to configure your OAuth tokens:

    cd {baseDir}
    ./scripts/setup.sh
    

    You'll need:

  • Access Token (sk-ant-oat01-...)
  • Refresh Token (sk-ant-ort01-...)
  • See references/token-extraction.md for how to get these.

    2. Check Usage

    ./scripts/check-usage.sh
    

    Output:

    SESSION=22.0
    WEEKLY=49.0
    BURN_RATE=OK
    CACHED_AT=1771583780
    

    3. Human-Readable Report

    ./scripts/report.sh
    

    Output:

    πŸ“Š Claude Code Daily Check:

    ⏱️ SESSION (5h): 22% πŸ“… WEEKLY (7d): 49%

    βšͺ На Ρ‚Π΅ΠΌΠΏΡ– β€” ΠΎΠΏΡ‚ΠΈΠΌΠ°Π»ΡŒΠ½Π΅ використання

    Burn Rate Interpretation

  • 🟒 UNDER β€” You're under-using your subscription. Use more to get your money's worth!
  • βšͺ OK β€” On pace. Optimal usage for your plan.
  • πŸ”΄ OVER β€” Over-burning. You'll hit limits before reset.
  • Daily Budget by Plan

    | Plan | Monthly | Weekly Budget | Daily Budget | |------|---------|---------------|--------------| | Pro | $20 | ~14% | ~2% | | Max 100 | $100 | ~14% | ~2% | | Max 200 | $200 | ~14% | ~2% |

    *(7-day window resets weekly, so ~14% per day = 100% per week)*

    Integration with Heartbeat

    Add to your HEARTBEAT.md:

    ### Evening Check (18:00-20:00)
    
  • Claude Code usage: /path/to/token-usage-optimizer/scripts/report.sh
  • Alert Thresholds

  • SESSION > 50% β†’ 🟑 One-time warning (won't repeat until next reset)
  • WEEKLY > 80% β†’ 🟑 One-time warning
  • Alerts use state tracking (/tmp/claude-usage-alert-state) to avoid spam.

    Cache

    Default: /tmp/claude-usage.cache with 10-minute TTL.

    Override:

    CACHE_FILE=/custom/path CACHE_TTL=300 ./scripts/check-usage.sh
    

    Files

  • scripts/setup.sh β€” Initial token configuration
  • scripts/check-usage.sh β€” Core usage checker (cached, burn rate calc)
  • scripts/report.sh β€” Human-readable daily report
  • references/api-endpoint.md β€” Anthropic OAuth API docs
  • references/token-extraction.md β€” How to get OAuth tokens
  • references/plans.md β€” Claude Code subscription tiers
  • API Endpoint

    GET https://api.anthropic.com/api/oauth/usage
    Authorization: Bearer 
    anthropic-beta: oauth-2025-04-20
    

    Response:

    {
      "five_hour": {
        "utilization": 22.0,
        "resets_at": "2026-02-20T14:00:00.364238+00:00"
      },
      "seven_day": {
        "utilization": 49.0,
        "resets_at": "2026-02-24T10:00:01.364256+00:00"
      }
    }
    

    Requirements

  • curl β€” API requests
  • date β€” Timestamp parsing
  • grep, cut, printf β€” Text parsing
  • No external dependencies (jq, etc.).

    Privacy

    Tokens are stored in {baseDir}/.tokens (gitignored).

    Never share your access/refresh tokens.

    Token Health Check (Recommended)

    OAuth tokens work for ~1 week, then need manual refresh. Set up 30-minute health check for better reliability:

    # Add cron job to check token health every 30 minutes
    openclaw cron add \
      --name "claude-token-refresh" \
      --every 30m \
      --announce \
      --message "Запусти {baseDir}/scripts/auto-refresh-cron.sh"
    

    What it does:

  • βœ… Token valid β†’ silent (no spam)
  • πŸ”΄ Token expired β†’ one-time alert with manual refresh instructions
  • Manual refresh (once per week, 30 seconds):

    claude auth login
    

    Browser opens β†’ sign in to claude.ai β†’ done!

    Tokens auto-sync to {baseDir}/.tokens after successful login.

    Troubleshooting

    "No token configured" β†’ Run ./scripts/setup.sh

    "Token expired" / "API request failed" β†’ OAuth tokens expire after ~1 week β†’ Manual refresh: claude auth login (browser opens β†’ sign in β†’ done) β†’ Set up hourly health check to get alerts before expiry (see above)

    Burn rate shows empty β†’ API response missing resets_at β€” try again in a few minutes

    Auto-refresh failed β†’ OAuth refresh endpoint may have changed β†’ Manual refresh: claude auth login β†’ copy new tokens β†’ run ./scripts/setup.sh

    Changelog

    v1.0.5 (2026-02-22)

  • πŸ› Bugfix: Fixed token extraction in auto-refresh-cron.sh (removed quotes handling)
  • ⚑ Performance: Reduced cron interval from 1h to 30m for more reliable token refresh
  • πŸ“ Improved reliability of OAuth token sync with ~/.claude/.credentials.json
  • v1.0.4 (2026-02-21)

  • πŸ”„ Replaced automatic refresh with health check + manual refresh workflow
  • πŸ“š Updated documentation with manual refresh instructions
  • ⏰ Health check alerts when manual refresh needed (~once per week)
  • v1.0.3 (2026-02-20)

  • ⏱️ Fixed auto-refresh interval (hourly instead of 5h)
  • πŸ“Š Improved burn rate calculation accuracy
  • Contributing

    Found a bug or have a feature request? β†’ Open an issue on ClawHub: https://clawhub.ai/friday/token-usage-optimizer

    License

    MIT

    πŸ’‘ Examples

    1. Setup

    Run the setup wizard to configure your OAuth tokens:

    cd {baseDir}
    ./scripts/setup.sh
    

    You'll need:

  • Access Token (sk-ant-oat01-...)
  • Refresh Token (sk-ant-ort01-...)
  • See references/token-extraction.md for how to get these.

    2. Check Usage

    ./scripts/check-usage.sh
    

    Output:

    SESSION=22.0
    WEEKLY=49.0
    BURN_RATE=OK
    CACHED_AT=1771583780
    

    3. Human-Readable Report

    ./scripts/report.sh
    

    Output:

    πŸ“Š Claude Code Daily Check:

    ⏱️ SESSION (5h): 22% πŸ“… WEEKLY (7d): 49%

    βšͺ На Ρ‚Π΅ΠΌΠΏΡ– β€” ΠΎΠΏΡ‚ΠΈΠΌΠ°Π»ΡŒΠ½Π΅ використання

    πŸ“‹ Tips & Best Practices

    "No token configured" β†’ Run ./scripts/setup.sh

    "Token expired" / "API request failed" β†’ OAuth tokens expire after ~1 week β†’ Manual refresh: claude auth login (browser opens β†’ sign in β†’ done) β†’ Set up hourly health check to get alerts before expiry (see above)

    Burn rate shows empty β†’ API response missing resets_at β€” try again in a few minutes

    Auto-refresh failed β†’ OAuth refresh endpoint may have changed β†’ Manual refresh: claude auth login β†’ copy new tokens β†’ run ./scripts/setup.sh