# Catch the 5-Hour Cap Before You Hit It: token-budget-advisor and Status-Line Integration

> Source: <https://dev.to/bokuwalily/catch-the-5-hour-cap-before-you-hit-it-token-budget-advisor-and-status-line-integration-14ab>
> Published: 2026-07-17 11:00:05+00:00

My last piece, "[Auto-resuming a session that stalled on a rate limit](https://zenn.dev/bokuwalily/articles/ratelimit-resume)," was about what to do *after* a 5-hour block stops you. This one is about the machinery that lets you **notice before it stops you**.

Claude MAX's 5-hour block halts your session the instant output tokens hit the ceiling. Even with `🕐 5h 82%`

visible in the status line, you have no idea how many tokens that remaining 18% actually represents. `token-budget-advisor.sh`

detects the boundary in absolute terms — **"getting dangerous around 800k, already cooked past 1.2M"** — and this article covers its design, its integration into `dashboard.sh`

, and how it gets wired into the status line.

The Claude Code status line shows `🕐 5h N%`

. `~/.claude/scripts/statusline.sh`

reads this straight from Claude's stdin.

```
H5=$(j '.rate_limits.five_hour.used_percentage // empty')
H5R=$(j '.rate_limits.five_hour.resets_at // empty')
```

The `pcolor`

function turns the value yellow at 50%+ and red at 80%+, but that's **the percentage Claude computed**, not an absolute token count. What 80% translates to in tokens shifts depending on your Max plan's contract state, and if you keep going with long completions you hit the cap and get abruptly stopped from the next turn onward.

To check, you have to run `ccusage blocks`

every single time, and if you forget and then kick off a heavy task, you'll cleanly burn through your 5-hour window. When an unattended job is running in the background, everything can slip into an all-SKIP state before a human even notices.

The policy in the header of `~/.claude/scripts/token-budget-advisor.sh`

doubles as its design.

```
# しきい値:
#   5h block:  output > 800k  → warn (>1.2M で critical)
#   weekly:    cost  > $3000  → warn
#   sessions:  >5/day         → warn (集中作業の疑い)
#
# 失敗時は exit 0 で fail-open (dashboard 統合のため)
# bash 3.2 互換
```

It first tries `ccusage blocks --json`

.

```
if command -v ccusage >/dev/null 2>&1; then
  CC_JSON=$(ccusage blocks --json 2>/dev/null || true)
  if [ -n "$CC_JSON" ]; then
    EXTRACTED=$(printf '%s' "$CC_JSON" | python3 -c "
import sys, json
try:
    d = json.load(sys.stdin)
    active = [b for b in d.get('blocks', []) if b.get('isActive')]
    if active:
        b = active[0]
        tc = b.get('tokenCounts', {}) or {}
        out = int(tc.get('outputTokens', 0))
        cost = float(b.get('costUSD', 0))
        print(f'{out}|{cost}')
    ...")
```

In environments where ccusage isn't present, it runs on `cost-log.jsonl`

alone. When both are available, it prefers ccusage's values and records the discrepancy as `source_diff_pct`

.

```
# ccusage の値が有効ならそちらを優先 (transcript 計算より信頼できる)
own_out_5h = out_5h
if cc_out is not None and cc_out > 0:
    out_5h = cc_out

# 比較 (検証用)
diff_pct = None
if cc_out is not None and own_out_5h > 0:
    diff_pct = round(abs(cc_out - own_out_5h) / max(cc_out, own_out_5h) * 100, 1)
```

When the gap is large, there may be a problem with the cost-log side's aggregation logic, and `source_diff_pct`

serves as a signal for that.

cost-log.jsonl gets written across multiple lines under the same `(session_id, transcript)`

key (by design, the cumulative value mid-session is appended). Summing all lines double-counts the tokens.

```
# cost-log は session_id × transcript ごとに累積値で書かれる仕様。
# 最新行のみ採用するため、(session_id, transcript) で最終行を取り直す。
latest = {}
with open(log_path) as f:
    for line in f:
        r = json.loads(line)
        key = (r.get("session_id", ""), r.get("transcript", ""))
        prev = latest.get(key)
        if (prev is None) or (t > prev[0]):
            latest[key] = (t, r)
```

You adopt only the final line, then filter by the 5h/7d windows. Sum every line without knowing this and you'll get numbers 2–3x the real value.

```
THRESH_5H_WARN     = 800_000      # output tokens
THRESH_5H_CRIT     = 1_200_000
THRESH_WEEK_WARN   = 3000         # USD
THRESH_SESS_PER_DAY = 5

if out_5h >= THRESH_5H_CRIT:
    s5 = "critical"
elif out_5h >= THRESH_5H_WARN:
    s5 = "warn"
else:
    s5 = "ok"
```

The intensive-work check is made from "average over the last 3 days > 5 sess/day."

```
recent_days = sorted(by_day.keys())[-3:]
avg_sess = sum(by_day[d] for d in recent_days) / max(1, len(recent_days))
burst = avg_sess > THRESH_SESS_PER_DAY
```

`--short`

mode
The `_short`

field is generated on the Python side.

```
"_short": f"{icon} {label} (5h:{out_5h/1000:.0f}k tok ${cost_5h:.1f} / 7d:${cost_7d:.0f})",
```

Example outputs per state (actual token counts will vary).

```
🟢 OK (5h:234k tok $0.3 / 7d:$2)
🟡 burst (5h:841k tok $1.2 / 7d:$8)
🔴 cap-near (5h:1243k tok $2.1 / 7d:$12)
```

Since you can match just the icon with `grep -qE '🔴|cap-near'`

, you can drop it directly into a shell-script gate. On error it prints `⚫ n/a`

and returns with exit 0 (fail-open design), so the caller doesn't get halted.

The `## 💰 Cost (7d)`

section of `~/.claude/scripts/dashboard.sh`

looks like this.

```
echo "## 💰 Cost (7d)"
~/.claude/scripts/cost-summary.sh --short
echo "  budget: $(~/.claude/scripts/token-budget-advisor.sh --short)"
```

It gets written out to `~/.claude/dashboard.md`

, so at the start of a project you just open the file to see the budget situation.

Here's the config for `~/Library/LaunchAgents/com.shun.dashboard.plist`

.

```
<key>Label</key>
<string>com.shun.dashboard</string>
<key>StartInterval</key>
<integer>14400</integer>
```

`14400`

seconds = 4 hours. While the Mac is awake, `dashboard.sh`

runs once every 4 hours and the budget line gets rewritten automatically. Without manually running `ccusage blocks`

, you can check the most recent aggregate just by looking at the file.

In unattended scripts like autopilot, you stop a job ahead of time using the `--short`

output (the wiring I introduced in the `claude-autopilot`

article).

```
BUDGET=$(~/.claude/scripts/token-budget-advisor.sh --short)
if echo "$BUDGET" | grep -qE '🔴|critical|cap-near'; then
  log "ABORT: budget critical"; exit 0
fi
```

Note

Label matching alone can let something slip through right at the boundary. For critical decisions, it's safer to pull the`5h_output_tokens`

field out of the JSON output (without`--short`

) as a number and check`>= 1200000`

directly.

`(session_id, transcript)`

key`command -v ccusage`

and keep a fallback path that runs on cost-log.jsonl alone when it's missing`⚫ n/a`

output to protect the dashboard's other sections`ProgramArguments`

through `/bin/zsh -c`

so it picks up zsh's path`THRESH_SESS_PER_DAY`

depending on your usage`rate_limits`

is `--`

before the first turn`token-budget-advisor.sh`

aggregates from a `source_diff_pct`

`(session_id, transcript)`

key, cost-log gives you a `--short`

mode compresses down to a single `🟢/🟡/🔴`

line, usable directly in shell gates and dashboard embedding`dashboard.sh`

auto-updates on launchd's StartInterval 14400 (4h), keeping the budget line always currentNext time I'll write about log rotation for the `cost-log.jsonl`

this dashboard references, and compressing old entries before aggregation gets heavy.

*Written by **Lily** — I ship iOS apps and automate my content stack with Claude Code.

Follow along: [Portfolio](https://bokuwalily.com) · [X](https://x.com/bokuwalily) · [GitHub](https://github.com/bokuwalily)*