# Token Pacing

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

- Skill: `diegosouzapw/token-pacing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/token-pacing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/token-pacing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/token-pacing

---


# 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:**
1. **Provider name** (Claude, Gemini, Codex, VS Code, Cursor, Windsurf, etc.)
2. **Current usage %** (or % remaining)
3. **Time until reset** (for weekly providers)

**Example:** "I'm at 31% in Claude, resets in 4 days"

**Then the skill will:**
1. Apply provider profile to normalize metric
2. Calculate pacing (Steps 1-4 below)
3. 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:**
- Claude/Codex: Provider settings pages
- Gemini: https://console.cloud.google.com/
- Copilot: https://github.com/settings/copilot

---

## 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:
1. **Provider** is identified → if not, ask
2. **Metric type** is clear (usage % vs % remaining) → if ambiguous, clarify
3. **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

- Round percentages to 1 decimal place
- **Always show both metrics:** Time passed % vs % used — this makes pacing intuitive at a glance
- If `daily_target > 50%`, warn that this is an extremely heavy workload
- If `days_remaining < 1`, switch to hourly targets:
  ```
  hours_remaining = days_remaining × 24
  hourly_target = remaining_% / hours_remaining
  ```

> [!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:

- [ ] Provider identified (or asked)
- [ ] Metric type confirmed (usage % vs % remaining)
- [ ] Reset period known (weekly vs monthly)
- [ ] For weekly providers: reset day/time obtained from user
- [ ] Ambiguous phrasing clarified ("50% left" → usage or remaining?)

---

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