# Send Token Usage Optimizer to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "token-usage-optimizer",
    "name": "Token Usage Optimizer",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/rusel95/token-usage-optimizer",
    "canonicalUrl": "https://clawhub.ai/rusel95/token-usage-optimizer",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/token-usage-optimizer",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=token-usage-optimizer",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "references/api-endpoint.md",
      "references/plans.md",
      "references/token-extraction.md",
      "scripts/auto-refresh-cron.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "token-usage-optimizer",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-01T13:01:21.665Z",
      "expiresAt": "2026-05-08T13:01:21.665Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=token-usage-optimizer",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=token-usage-optimizer",
        "contentDisposition": "attachment; filename=\"token-usage-optimizer-1.0.5.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "token-usage-optimizer"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/token-usage-optimizer"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/token-usage-optimizer",
    "downloadUrl": "https://openagent3.xyz/downloads/token-usage-optimizer",
    "agentUrl": "https://openagent3.xyz/skills/token-usage-optimizer/agent",
    "manifestUrl": "https://openagent3.xyz/skills/token-usage-optimizer/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/token-usage-optimizer/agent.md"
  }
}
```
## Documentation

### 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)

### 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

PlanMonthlyWeekly BudgetDaily BudgetPro$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 <access-token>
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

### 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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: rusel95
- Version: 1.0.5
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-01T13:01:21.665Z
- Expires at: 2026-05-08T13:01:21.665Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/token-usage-optimizer)
- [Send to Agent page](https://openagent3.xyz/skills/token-usage-optimizer/agent)
- [JSON manifest](https://openagent3.xyz/skills/token-usage-optimizer/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/token-usage-optimizer/agent.md)
- [Download page](https://openagent3.xyz/downloads/token-usage-optimizer)