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...
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:
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
Quick Start
1. Setup
Run the setup wizard to configure your OAuth tokens:
cd {baseDir}
./scripts/setup.sh
You'll need:
sk-ant-oat01-...)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
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
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 configurationscripts/check-usage.sh β Core usage checker (cached, burn rate calc)scripts/report.sh β Human-readable daily reportreferences/api-endpoint.md β Anthropic OAuth API docsreferences/token-extraction.md β How to get OAuth tokensreferences/plans.md β Claude Code subscription tiersAPI 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 requestsdate β Timestamp parsinggrep, cut, printf β Text parsingNo 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:
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)
auto-refresh-cron.sh (removed quotes handling)~/.claude/.credentials.jsonv1.0.4 (2026-02-21)
v1.0.3 (2026-02-20)
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:
sk-ant-oat01-...)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