# Send Claude Code Usage 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": "claude-code-usage",
    "name": "Claude Code Usage",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/azaidi94/claude-code-usage",
    "canonicalUrl": "https://clawhub.ai/azaidi94/claude-code-usage",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/claude-code-usage",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-usage",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "CRON_SETUP.md",
      "README.md",
      "SKILL.md",
      "scripts/claude-usage.sh",
      "scripts/monitor-and-notify.sh",
      "scripts/monitor-usage.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "claude-code-usage",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-01T11:40:19.395Z",
      "expiresAt": "2026-05-08T11:40:19.395Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-usage",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-usage",
        "contentDisposition": "attachment; filename=\"claude-code-usage-1.2.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "claude-code-usage"
      },
      "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/claude-code-usage"
    },
    "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/claude-code-usage",
    "downloadUrl": "https://openagent3.xyz/downloads/claude-code-usage",
    "agentUrl": "https://openagent3.xyz/skills/claude-code-usage/agent",
    "manifestUrl": "https://openagent3.xyz/skills/claude-code-usage/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/claude-code-usage/agent.md"
  }
}
```
## Documentation

### Claude Code Usage

Check your Claude Code OAuth API usage limits for both session (5-hour) and weekly (7-day) windows.

### Quick Start

cd {baseDir}
./scripts/claude-usage.sh

### Usage

# Default: show cached usage (if fresh)
./scripts/claude-usage.sh

# Force refresh from API
./scripts/claude-usage.sh --fresh

# JSON output
./scripts/claude-usage.sh --json

# Custom cache TTL
./scripts/claude-usage.sh --cache-ttl 300

### Output

Text format (default):

🦞 Claude Code Usage

⏱️  Session (5h): 🟢 ████░░░░░░ 40%
   Resets in: 2h 15m

📅 Weekly (7d): 🟡 ██████░░░░ 60%
   Resets in: 3d 8h

JSON format (--json):

{
  "session": {
    "utilization": 40,
    "resets_in": "2h 15m",
    "resets_at": "2026-01-19T22:15:00Z"
  },
  "weekly": {
    "utilization": 60,
    "resets_in": "3d 8h",
    "resets_at": "2026-01-22T04:00:00Z"
  },
  "cached_at": "2026-01-19T20:00:00Z"
}

### Features

📊 Session limit (5-hour window) - Short-term rate limit
📅 Weekly limit (7-day window) - Long-term rate limit
⚡ Smart caching - 60-second cache to avoid API spam
🎨 Beautiful output - Progress bars, emojis, color-coded status
🔄 Force refresh - --fresh flag to bypass cache
📤 JSON output - Machine-readable format
🔔 Automated monitoring - Get notified when quotas reset

### Status Indicators

🟢 Green - 0-50% usage (healthy)
🟡 Yellow - 51-80% usage (moderate)
🔴 Red - 81-100% usage (high/critical)

### Requirements

macOS: Uses Keychain to access Claude Code credentials
Linux: Uses secret-tool for credential storage
Credentials: Must have Claude Code CLI authenticated

### How It Works

Retrieves OAuth token from system keychain
Queries api.anthropic.com/api/oauth/usage with OAuth bearer token
Parses five_hour and seven_day utilization metrics
Calculates time remaining until reset
Formats output with progress bars and status indicators
Caches result for 60 seconds (configurable)

### Cache

Default cache: /tmp/claude-usage-cache (60s TTL)

Override:

CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh

### Examples

Check usage before starting work:

./scripts/claude-usage.sh --fresh

Integrate with statusline:

usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}')
echo "Session: $usage"

Get JSON for monitoring:

./scripts/claude-usage.sh --json | jq '.session.utilization'

### Session Refresh Reminders (Recommended)

Get notified exactly when your 5-hour session quota refreshes!

Quick Setup:

./scripts/session-reminder.sh

This creates a self-scheduling chain of cron jobs that:

Checks your current session expiry time
Schedules the next reminder for when your session refreshes
Notifies you with current usage stats
Auto-removes itself (the new cron takes over)

What You'll Get:

🔄 Claude Code Session Status

⏱️  Current usage: 44%
⏰ Next refresh: 2h 15m

Your 5-hour quota will reset soon! 🦞

✅ Next reminder scheduled for: Jan 22 at 01:22 AM

How It Works:

Each reminder runs claude-usage.sh to find the exact session reset time
Schedules a one-time cron for that exact moment
Repeats every 5 hours automatically
Self-correcting if session times ever drift

Benefits:

✅ Accurate to the minute
✅ No manual scheduling needed
✅ Adapts to your actual usage patterns
✅ Minimal API calls (only when needed)

### Reset Detection Monitor (Alternative)

Get automatic notifications when your Claude Code quotas reset by polling usage.

Quick Setup:

# Test once
./scripts/monitor-usage.sh

# Setup automated monitoring (runs every 30 minutes)
./scripts/setup-monitoring.sh

Or add via Clawdbot directly:

# Check every 30 minutes
clawdbot cron add --cron "*/30 * * * *" \\
  --message "cd /Users/ali/clawd/skills/claude-code-usage && ./scripts/monitor-usage.sh" \\
  --name "Claude Code Usage Monitor" \\
  --session isolated --deliver --channel telegram

What You'll Get:

🎉 Claude Code Session Reset!

⏱️  Your 5-hour quota has reset
📊 Usage: 2%
⏰ Next reset: 4h 58m

Fresh usage available! 🦞

How It Works:

Monitors usage every 30 minutes (configurable)
Detects resets when usage drops significantly (>10% or <5%)
Sends notifications via Telegram when resets occur
Tracks state in /tmp/claude-usage-state.json

Customization:

# Change check interval
clawdbot cron add --cron "*/15 * * * *" ...  # Every 15 minutes
clawdbot cron add --cron "0 * * * *" ...      # Every hour

# Custom state file location
STATE_FILE=/path/to/state.json ./scripts/monitor-usage.sh

### Which Monitoring Method?

FeatureSession ReminderReset DetectionAccuracy✅ Exact minute~30min windowAPI callsMinimalEvery checkNotification timingRight on resetUp to 30min delaySetupOne commandOne commandMaintenanceSelf-schedulingCron runs forever

Recommendation: Use Session Reminder for precise, real-time notifications.

### Troubleshooting

No credentials found:

Ensure Claude Code CLI is installed and authenticated
Run claude once to trigger OAuth flow

API request failed:

Check internet connection
Verify OAuth token hasn't expired
Try --fresh to force new request

Linux users:
Install libsecret for credential storage:

# Debian/Ubuntu
sudo apt install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: azaidi94
- Version: 1.2.0
## 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-01T11:40:19.395Z
- Expires at: 2026-05-08T11:40:19.395Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/claude-code-usage)
- [Send to Agent page](https://openagent3.xyz/skills/claude-code-usage/agent)
- [JSON manifest](https://openagent3.xyz/skills/claude-code-usage/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/claude-code-usage/agent.md)
- [Download page](https://openagent3.xyz/downloads/claude-code-usage)