| name | token-pacing |
| description | Calculate the optimal token usage burn rate to reach exactly 100% usage by reset. Use when the user asks about token budget, usage limits, spending speed, or "will I run out". Supports Claude, Gemini, Codex, VS Code, and other providers. |
Token Pacing Calculator
Analyzes current token usage against the reset deadline to provide a specific daily burn rate target.
Why? Optimizes resource utility by ensuring the user neither runs out of tokens too early nor leaves unused budget on the table.
Quick Start
This skill calculates optimal token burn rate from current usage data.
To use this skill, provide:
- Provider name (Claude, Gemini, Codex, VS Code, Cursor, Windsurf, etc.)
- Current usage % (or % remaining)
- Time until reset (for weekly providers)
Example: "I'm at 31% in Claude, resets in 4 days"
Then the skill will:
- Apply provider profile to normalize metric
- Calculate pacing (Steps 1-4 below)
- Output the Token Pacing Report
How to Get Usage Data (Optional)
If you have ai-usage installed, run it for a quick overview of all services.
Otherwise, check your provider directly:
| Provider | How to Check |
|---|
| Claude Code | IDE status bar, or /usage command |
| OpenAI Codex | ChatGPT settings, or IDE status bar |
| Gemini CLI | gcli quota or Google Cloud dashboard |
| VS Code Copilot | Copilot icon in status bar → "View quota usage" |
| Cursor | Settings → Copilot → Usage |
| Windsurf | Codeium status panel |
Web dashboards:
Provider Profiles
Auto-detect the provider and apply these defaults:
| Provider | Aliases | Metric Shown | Reset Period | Reset Day |
|---|
| Claude | Claude Code, Anthropic | Usage % | Weekly | User-specific (ask) |
| Gemini | Google Gemini, Gemini Code | Usage % | Weekly | User-specific (ask) |
| Codex | OpenAI Codex, ChatGPT | % Remaining | Weekly | User-specific (ask) |
| VS Code | VS Code Copilot, GitHub Copilot (VS Code) | Usage % | Monthly | 1st of month |
| Cursor | Cursor AI | Usage % | Monthly | 1st of month |
| Windsurf | Codeium Windsurf | Usage % | Monthly | 1st of month |
[!NOTE]
Weekly providers (Claude, Gemini, Codex) have personal reset cycles — there's no universal reset day. Ask the user (unless provided): "When does your week reset?"
Metric Normalization
If provider shows "% remaining" (e.g., Codex):
usage_% = 100 - remaining_%
Else:
usage_% = reported value
Reset Date Calculation
Weekly providers (Claude, Gemini, Codex):
# Reset day is USER-SPECIFIC — must ask if not provided
# Example: "My Claude resets on Thursdays" or "resets in 3 days"
cycle_days = 7
reset = user's next reset date/time
days_remaining = (reset - now) in days
days_elapsed = cycle_days - days_remaining
Monthly providers (VS Code, Cursor, Windsurf):
# Reset is predictable — 1st of next month
cycle_days = days in current month (28-31)
reset = 1st of next month, 12:00am
days_remaining = (reset - now) in days
days_elapsed = current day of month
[!TIP]
For weekly providers, if user doesn't know their reset day, suggest they check their usage dashboard — it usually shows "resets in X days".
Inputs Required
For monthly providers (VS Code, Cursor, Windsurf):
- Just the metric value — reset date is predictable
- Example: "16% in VS Code"
For weekly providers (Claude, Gemini, Codex):
- Metric value + reset info (days remaining or reset day)
- Example: "31% in Claude, resets in 4 days" or "Codex 40% left, resets Thursday"
[!TIP]
If user gives weekly provider without reset info, ask: "When does your usage reset? (e.g., 'in 3 days' or 'on Friday')"
[!CAUTION]
Ambiguous phrasing: If user says "X% left" for a non-Codex provider, clarify immediately: "Is that X% used or X% remaining?" — this changes the calculation entirely.
Calculation Steps
Perform these calculations directly — no external script needed.
Step 0: Validate Inputs
Before calculating, confirm:
- Provider is identified → if not, ask
- Metric type is clear (usage % vs % remaining) → if ambiguous, clarify
- Reset info is available → for weekly providers, ask if missing
Step 1: Calculate Time Metrics
now = current date/time
reset = reset date/time (from provider profile or user input)
days_remaining = (reset - now) in days (decimal, e.g., 4.4)
cycle_days = 7 (weekly) or days_in_month (monthly)
days_elapsed = cycle_days - days_remaining
time_elapsed_% = (days_elapsed / cycle_days) × 100
Step 2: Calculate Usage Metrics
# Normalize metric based on provider
if provider shows "% remaining":
usage_% = 100 - reported_value
else:
usage_% = reported_value
remaining_% = 100 - usage_%
daily_target = remaining_% / days_remaining
Step 3: Determine Status
Compare usage_% to time_elapsed_%:
| Condition | Status | Meaning |
|---|
usage_% < time_elapsed_% - 3 | Under Budget | Saving tokens, can spend more freely |
usage_% > time_elapsed_% + 3 | Over Budget | Burning too fast, need to slow down |
| Otherwise | On Track | Balanced pace |
[!TIP]
The ±3% buffer avoids false alarms for minor deviations.
Step 4: Calculate Buffer
buffer_% = time_elapsed_% - usage_%
- Positive buffer = tokens banked (ahead of schedule)
- Negative buffer = tokens owed (behind schedule)
Response Template
Report the following:
## Token Pacing Report
**Provider:** [Provider Name] ([weekly/monthly] reset)
**Status:** [Under Budget / On Track / Over Budget]
| Metric | Value |
|--------|-------|
| Used | X% |
| Time Elapsed | Y% |
| Buffer | ±Z% |
| Remaining | W% over N days |
| Daily Target | D%/day |
[One sentence recommendation based on status]
Recommendation by Status
- Under Budget: "You're saving tokens. You can increase usage to [daily_target]%/day to hit 100% by reset."
- On Track: "You're pacing well. Maintain ~[daily_target]%/day."
- Over Budget: "You're burning fast. Limit usage to [daily_target]%/day to last until reset."
Examples
Example 1: VS Code (Monthly Reset)
Input: "16% in VS Code" (current date: Jan 11)
Provider: VS Code → monthly reset, 1st of next month
cycle_days = 31 (January)
days_elapsed = 11
days_remaining = 20
time_elapsed_% = (11 / 31) × 100 = 35.5%
usage_% = 16%
remaining_% = 84%
daily_target = 84 / 20 = 4.2%/day
buffer_% = 35.5 - 16 = +19.5% (well under budget)
status = Under Budget
Output:
## Token Pacing Report
**Provider:** VS Code (monthly reset)
**Status:** Under Budget
| Metric | Value |
|--------|-------|
| Used | 16% |
| Time Elapsed | 35.5% |
| Buffer | +19.5% |
| Remaining | 84% over 20 days |
| Daily Target | 4.2%/day |
You're saving tokens. Increase to 4.2%/day to fully utilize your allocation.
Example 2: Claude (Weekly Reset)
Input: "31% used in Claude" (current: Jan 10, reset: Jan 15 Wed 9am PT)
Provider: Claude → weekly reset, Wednesday 9am PT
cycle_days = 7
days_remaining = 4.4 days
days_elapsed = 2.6 days
time_elapsed_% = (2.6 / 7) × 100 = 37%
usage_% = 31%
remaining_% = 69%
daily_target = 69 / 4.4 = 15.7%/day
buffer_% = 37 - 31 = +6%
status = Under Budget
Output:
## Token Pacing Report
**Provider:** Claude (weekly reset)
**Status:** Under Budget
| Metric | Value |
|--------|-------|
| Used | 31% |
| Time Elapsed | 37% |
| Buffer | +6% |
| Remaining | 69% over 4.4 days |
| Daily Target | 15.7%/day |
You're saving tokens. You can increase usage to 15.7%/day to hit 100% by reset.
Example 3: Codex (% Remaining Format)
Input: "Codex shows 40% left" (current: Thursday, reset: Sunday 12am)
Provider: Codex → weekly reset, shows % REMAINING (invert!)
usage_% = 100 - 40 = 60%
cycle_days = 7
days_remaining = 2.5 days (Thu to Sun)
days_elapsed = 4.5 days
time_elapsed_% = (4.5 / 7) × 100 = 64%
remaining_% = 40%
daily_target = 40 / 2.5 = 16%/day
buffer_% = 64 - 60 = +4%
status = On Track
Output:
## Token Pacing Report
**Provider:** Codex (weekly reset)
**Status:** On Track
| Metric | Value |
|--------|-------|
| Used | 60% (40% remaining) |
| Time Elapsed | 64% |
| Buffer | +4% |
| Remaining | 40% over 2.5 days |
| Daily Target | 16%/day |
You're pacing well. Maintain ~16%/day.
Example 4: Over Budget (The Spender)
Input: "80% in Gemini" (current: Tuesday, reset: Monday 12am)
Provider: Gemini → weekly reset, Monday 12am PT
cycle_days = 7
days_remaining = 6 days
days_elapsed = 1 day
time_elapsed_% = (1 / 7) × 100 = 14%
usage_% = 80%
remaining_% = 20%
daily_target = 20 / 6 = 3.3%/day
buffer_% = 14 - 80 = -66% (way behind)
status = Over Budget
Output:
## Token Pacing Report
**Provider:** Gemini (weekly reset)
**Status:** Over Budget
| Metric | Value |
|--------|-------|
| Used | 80% |
| Time Elapsed | 14% |
| Buffer | -66% |
| Remaining | 20% over 6 days |
| Daily Target | 3.3%/day |
You're burning fast. Limit usage to 3.3%/day to last until reset.
Example 5: On Track (The Balanced)
Input: "50% in Claude" (mid-week)
Provider: Claude → weekly reset
cycle_days = 7
days_remaining = 3.5 days
days_elapsed = 3.5 days
time_elapsed_% = 50%
usage_% = 50%
remaining_% = 50%
daily_target = 50 / 3.5 = 14.3%/day
buffer_% = 0%
status = On Track
Output:
## Token Pacing Report
**Provider:** Claude (weekly reset)
**Status:** On Track
| Metric | Value |
|--------|-------|
| Used | 50% |
| Time Elapsed | 50% |
| Buffer | 0% |
| Remaining | 50% over 3.5 days |
| Daily Target | 14.3%/day |
You're pacing well. Maintain ~14.3%/day.
The 5pm Rule (Advanced Pacing)
Problem: Standard pacing aims for 100% at the exact reset time. But if your reset is at 11:59 AM and you hit 100% at 11:58 AM, you've perfectly paced... but also can't use tokens all morning. Similarly, evening resets (10 PM) mean you can't use tokens during dinner/evening work.
Solution: Aim to hit 100% by 5:00 PM on the "effective reset day" — this eliminates "dead time" when you'd otherwise be token-limited during productive hours.
Effective Reset Day
| Reset Time | Effective Target |
|---|
| Morning reset (before 5 PM) | 5:00 PM the day before |
| Evening reset (5 PM or later) | 5:00 PM the same day |
Examples:
- Reset at 11:59 AM Wednesday → Target: 5:00 PM Tuesday
- Reset at 10:56 PM Thursday → Target: 5:00 PM Thursday
- Reset at 12:00 AM (midnight) Monday → Target: 5:00 PM Sunday
Adjusted Calculation
When using the 5pm Rule, replace the reset datetime in Step 1:
# Standard calculation
reset = actual_reset_datetime
# 5pm Rule calculation
if reset.time < 17:00:
effective_reset = (reset.date - 1 day) at 17:00
else:
effective_reset = reset.date at 17:00
# Then use effective_reset for all calculations
days_remaining = (effective_reset - now) in days
[!TIP]
The 5pm Rule is optional but recommended for users who want to maximize productive usage hours. Always mention when using it in the report.
Report Addition for 5pm Rule
When using the 5pm Rule, add to the report:
**Target:** 5:00 PM [Day] (5pm Rule applied)
Quality Guidelines
[!WARNING]
If daily_target > 50%/day, add this warning: "This requires very heavy usage. Consider whether you can realistically sustain this pace."
Pre-Calculation Checklist
Before running calculations, verify:
Troubleshooting
| Problem | Solution |
|---|
| Provider not specified | Ask: "Which tool? (Claude, Gemini, VS Code, Codex, Cursor, Windsurf)" |
| User gives ambiguous date ("next Wednesday") | Parse as the next upcoming occurrence from current date |
| Reset time appears to be in the past | Ask user to confirm the next reset date |
| Usage reported as > 100% | Report status as "Exhausted" with 0% remaining, 0%/day target |
| User doesn't know exact reset time | Use provider default from profiles table |
| Very short time remaining (< 4 hours) | Switch to per-hour targets and emphasize urgency |
| Unknown provider | Ask for reset period (weekly/monthly) and metric type (usage % or % remaining) |
| User reports "X% left" for non-Codex | Clarify: "Is that usage or remaining?" then normalize |
Common Mistakes to Avoid
| Mistake | Correct Approach |
|---|
| Assuming weekly reset for all providers | Check provider profile — VS Code/Cursor/Windsurf are monthly |
| Not inverting "% remaining" for Codex | Codex shows remaining; convert: usage = 100 - remaining |
| Using 7 days for monthly providers | Use actual days in month (28-31) |
| Forgetting to convert "days left" to decimal | Use precise decimal (e.g., 4.4 days, not 4 days) |
| Reporting buffer as absolute tokens | Buffer is always a percentage |
| Not adjusting for partial days | Include fractional days in calculations |
