| name | twicc-usage |
| description | Show API usage quotas and cost estimates per backend provider. Use when you or the user want to check utilization, rate limits, or spending. |
TwiCC Usage
Show the latest usage quota snapshot with cost estimates for every provider.
When to use
- You or the user want to check current API usage, quota utilization, or spending.
How to invoke
Prefer the mcp__twicc__* tools when you have them. Inside a TwiCC session your tool list may include mcp__twicc__* tools — one per command below (the command with / and - turned into _, e.g. mcp__twicc__create_session, mcp__twicc__update_session_settings). When present, use them instead of the $TWICC CLI: same arguments, same JSON result, no shell, and your session identity travels with the call so self/parent resolve on their own. Fall back to the $TWICC CLI below when those tools aren't available (outside a session, or when scripting from a terminal).
TwiCC's executable varies by launch mode (uvx, dev, installed tool). ALWAYS USE THIS TO RESOLVE $TWICC AT THE START OF EACH BASH INVOCATION:
TWICC=${TWICC_BIN:-$(command -v twicc 2>/dev/null)}
[ -n "$TWICC" ] || { echo "TwiCC executable not found in this context" >&2; exit 1; }
Then run $TWICC <args> — never quote $TWICC (use $TWICC args, never "$TWICC" args): it may expand to multiple words, which quoting would break.
Usage
$TWICC usage
No options.
Output format
JSON object keyed by provider:
{
"claude_code": {
"provider": "claude_code",
"fetched_at": "2026-05-31T07:51:20+00:00",
"five_hour_utilization": 2.0,
"five_hour_resets_at": "2026-05-31T12:20:00+00:00",
"seven_day_utilization": 38.0,
"seven_day_resets_at": "2026-06-04T19:00:00+00:00",
"extra_usage_is_enabled": true,
"extra_usage_monthly_limit": 6000,
"extra_usage_used_credits": 512.0,
"extra_usage_utilization": 8.5,
"extra_usage_remaining_credits": null,
"period_costs": {
"five_hour": {"spent": 3.19, "estimated_period": 27.59, "estimated_monthly": 3973.0, "capped": false, "cutoff_at": null},
"seven_day": {"spent": 721.30, "estimated_period": 1898.15, "estimated_monthly": 8134.95, "capped": true, "cutoff_at": "2026-06-04T11:17:42+00:00"}
},
"five_hour_temporal_pct": 10.4,
"five_hour_burn_rate": 19.2,
"five_hour_started_at": "2026-05-31T07:20:00+00:00",
"seven_day_temporal_pct": 36.2,
"seven_day_burn_rate": 104.9,
"seven_day_started_at": "2026-05-28T19:00:00+00:00",
"five_hour_burn_rate_30min": 95.4,
"five_hour_burn_rate_1h": 87.1,
"seven_day_burn_rate_12h": 132.0,
"seven_day_burn_rate_24h": 118.4
}
}
Key fields
five_hour_* / seven_day_* — 5-hour and 7-day rolling window quotas.*_utilization — percentage of quota used (e.g. 45.0 = 45%).*_temporal_pct — percentage of time elapsed in the quota window.*_burn_rate — utilization vs. time elapsed since window start; >100 means on track to exhaust before reset.five_hour_burn_rate_30min / five_hour_burn_rate_1h / seven_day_burn_rate_12h / seven_day_burn_rate_24h — burn rate over the trailing lookback (same scale as *_burn_rate); null when not computable.*_resets_at — when the quota window resets (ISO 8601).extra_usage_* — extra usage billing (if enabled). For Claude code, credits are in cents of the user currency, and uses monthly limit, used credits and utilization. Codex only uses remaining_credits.period_costs.*.spent — actual cost in USD so far.period_costs.*.estimated_monthly — projected monthly cost at current pace.period_costs.*.capped — true if the estimate was capped (quota exhausted before period end).period_costs.*.cutoff_at — when the cap was hit (ISO 8601), or null.
How to present results
- Summarize per provider; focus on 5-hour and 7-day quotas.
- Show utilization as percentages; highlight if above 80%.
- Use burn rate to assess risk: >100 means quota will be exhausted before reset.
- Show reset times in human-readable format.
- Include cost estimates only when asked.
- For Claude Code, redirect to https://claude.ai/settings/usage for more detail.
