convez.ai
SkillAutomaçãoAvançado
WillHsiaoNYC

Otsukare — Guardrail de Limites de Uso

WillHsiaoNYC/Claude-Code-Skill-Otsukare

Pausa inteligente em limites de uso e retomada automática após reset

Ver no GitHub
BomPluginScore · de 0 a 100

Uma skill para Claude Code que monitora e gerencia os limites de uso rolling (5h/7d) em planos de assinatura. Pausa tarefas longas em checkpoints seguros quando o orçamento está próximo e retoma automaticamente após o reset do limite, evitando que trabalhos sejam perdidos.

Instalação

$npx convez-ai WillHsiaoNYC/Claude-Code-Skill-Otsukare

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
24
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Executar tarefas multi-hora (refatoração, batch jobs) sem interrupção
  • Proteger workflows de múltiplos agentes contra limites de taxa
  • Automatizar retomada de trabalho após reset de janelas de 5h/7d

Veredito

Skill robusta e bem arquitetada para um problema real em Claude Code: perda de progresso por limites de taxa. Implementação sólida com unit tests, lógica de safety net confiável e reportagem clara. Uso específico (só aplicável a planos Pro/Max com rolling limits), mas essencial para quem executa jobs longos.

README

A tradução para o português deste README ainda está na fila.

otsukare — a usage-limit guardrail skill for Claude Code

お疲れ (otsukare) — "good work, go rest." A Claude Code skill that wraps a long task in a rate-limit guardrail: it watches your 5-hour and 7-day usage, pauses the work at a safe checkpoint before a limit is exhausted, and auto-resumes just after the limit resets — even if a sudden burst of subagents hard-cuts the session.

You start a big multi-hour job, walk away, and come back to find it finished — it quietly paused when you ran out of budget and picked itself back up after the window reset, instead of dying half-done.

🤖 Installing with an AI agent? Paste this repo's URL into Claude Code (or any coding agent) and say "install this skill by following the README." The agent should follow Install → With an AI agent below — it's written as a step-by-step procedure an agent can execute directly, including the one manual-ish step (wiring your statusline).

📋 Subscription plans only. otsukare guards Claude Code's 5-hour / 7-day rate-limit windows, which exist on Pro/Max subscriptions. On an API / usage-billed setup (metered per token, no rolling windows) there's nothing to guard — the skill runs a --preflight check at startup, detects the absence of rate_limits, tells you, and exits cleanly.


The problem

Claude Code enforces a rolling 5-hour limit and a 7-day limit. A long, token-heavy run (big refactors, multi-agent workflows, batch jobs) can hit the wall mid-task and simply stop — losing the thread and leaving the work half-finished. You either babysit the clock or lose progress.

How it works

otsukare runs as a skill you invoke at the start of a long task. It doesn't do the work itself — it wraps it:

  1. Arms a safety net. Before any work, it schedules a "dead-man's-switch" resume for just after the next 5h reset. If a swarm of subagents spikes you to 100% before the skill can react, a resume is already scheduled.
  2. Monitors at seams. After each natural stopping point (a subagent batch returns, a step completes, a commit), it checks usage.
  3. Pauses safely. At 90% (soft) it pauses if substantial work remains; at 97% (hard) it always pauses. Pausing = drain in-flight subagents, write a checkpoint, commit work-in-progress.
  4. Resumes automatically. Just after the binding limit resets (+10 min), it re-establishes context (cd, checkout, verify), confirms the limit actually cleared, and continues from where it left off.
  5. Reports & cleans up. On completion it prints a run summary — how many times it continued, total/active/waiting time, tokens, and cost (measured as the delta over the otsukare span) — then removes the scheduled job, checkpoint, and state. Net zero lingering state.
お疲れ! otsukare summary — refactor auth module
  Continued:  2× (91%, 96%)
  Run time:   4h 18m total · 1h 51m active · 2h 27m waiting
  Tokens:     412K in/out · 4.1M cache (4.5M total)
  Cost:       $3.84

A heartbeat file lets the safety net tell whether the main run is still alive, so it only takes over if the session actually died — never double-resuming a healthy run.

Architecture: a small, unit-tested Python helper (scripts/otsukare_usage.py) owns all the freshness/threshold/scheduling math; SKILL.md is the model-facing playbook that orchestrates pause/resume.


Install — With an AI agent (recommended)

If you are an AI coding agent installing this, follow these steps exactly. They are deterministic; the only judgement call is editing the user's existing statusline in step 4 (do it idempotently and back it up).

1. Get the files. Clone the repo (or use the local copy if already present):

git clone https://github.com/WillHsiaoNYC/Claude-Code-Skill-Otsukare.git
cd Claude-Code-Skill-Otsukare

2. Install the skill into the Claude Code user skills directory:

mkdir -p ~/.claude/skills/otsukare
cp -R SKILL.md scripts ~/.claude/skills/otsukare/
chmod +x ~/.claude/skills/otsukare/scripts/otsukare_usage.py

3. Verify the helper runs and its tests pass:

python3 ~/.claude/skills/otsukare/scripts/otsukare_usage.py --cron-for 1700000000   # prints a cron string
( cd ~/.claude/skills/otsukare/scripts && python3 -m unittest test_otsukare_usage ) # all tests OK

4. Wire the rate-limit mirror (REQUIRED — otsukare is blind without it). Claude Code pipes live rate-limit data only to the statusline script's stdin, so the statusline must mirror that blob to ~/.claude/last-statusline-input.json.

a. Read ~/.claude/settings.json (and ~/.claude/settings.local.json if it exists) and find "statusLine".command.

b. If a statusline script is configured (e.g. "command": "bash ~/.claude/statusline.sh"):

  • Resolve the script path and read it.
  • Idempotency: if it already contains last-statusline-input.json, the mirror is present — skip this step.
  • Otherwise back it up (cp script script.bak), then insert these lines immediately after the line that captures stdin (usually input=$(cat) — match the script's actual variable name if different):
    # otsukare: mirror the rate-limit blob so the local agent can read it (atomic write)
    printf '%s' "$input" > ~/.claude/last-statusline-input.json.tmp 2>/dev/null \
      && mv ~/.claude/last-statusline-input.json.tmp ~/.claude/last-statusline-input.json 2>/dev/null
    
  • If the script never captures stdin, add input=$(cat) as its first executable line, then the mirror lines above (Claude Code feeds the JSON on stdin).

c. If NO statusline is configured: create ~/.claude/statusline.sh with the minimal script from Manual setup below (chmod +x it), and merge this into ~/.claude/settings.json without clobbering other keys:

{ "statusLine": { "type": "command", "command": "bash ~/.claude/statusline.sh" } }

5. Verify the mirror works. Ask the user to send any message in Claude Code (the statusline renders every few seconds while active), then:

python3 ~/.claude/skills/otsukare/scripts/otsukare_usage.py

Expect JSON with "ok": true and real five_hour / seven_day values. If "ok": false or the values are missing, the mirror isn't writing yet — re-check step 4.

6. Finish. Tell the user to restart Claude Code so it discovers the skill, then invoke it with:

otsukare — <your long task>

Install — Manual

git clone https://github.com/WillHsiaoNYC/Claude-Code-Skill-Otsukare.git
cd Claude-Code-Skill-Otsukare
./install.sh        # copies the skill into ~/.claude/skills/otsukare and runs the tests

Then do the one required manual step — mirror your usage to a file the skill can read.

Add the mirror line to your existing statusline

In the script configured under statusLine.command in ~/.claude/settings.json, right after it reads stdin, add:

input=$(cat)

# otsukare: mirror the rate-limit blob so the local agent can read it (atomic write)
printf '%s' "$input" > ~/.claude/last-statusline-input.json.tmp 2>/dev/null \
  && mv ~/.claude/last-statusline-input.json.tmp ~/.claude/last-statusline-input.json 2>/dev/null

Don't have a statusline yet?

Create ~/.claude/statusline.sh:

#!/bin/bash
input=$(cat)

# otsukare: mirror the rate-limit blob (atomic write)
printf '%s' "$input" > ~/.claude/last-statusline-input.json.tmp 2>/dev/null \
  && mv ~/.claude/last-statusline-input.json.tmp ~/.claude/last-statusline-input.json 2>/dev/null

# minimal status line: model + 5h usage
echo "$input" | python3 -c '
import json, sys
d = json.load(sys.stdin)
model = d.get("model", {}).get("display_name", "Claude")
five = (d.get("rate_limits", {}).get("five_hour", {}) or {}).get("used_percentage", "?")
print(f"{model} · 5h {five}%")
'

Then wire it in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline.sh"
  }
}

Restart Claude Code afterward so it discovers the skill.


Why the statusline step?

Claude Code provides live rate-limit data only to your statusline script's stdin — it is not available to the model or to a plain script. Mirroring that blob to ~/.claude/last-statusline-input.json is what lets otsukare's helper read your current 5h/7d usage and reset times.

The mirrored blob must contain a rate_limits object with five_hour / seven_day (each with used_percentage and resets_at). Claude Code provides these to the statusline; if your plan or version doesn't surface them, otsukare can't see your limits.

Usage

Invoke at the start of a long task:

otsukare — then <your long task here>

otsukare arms the safety net, runs your task, and handles the limits transparently. When it pauses, it tells you exactly where it stopped and when it will resume. You can also use the helper standalone:

python3 ~/.claude/skills/otsukare/scripts/otsukare_usage.py | python3 -m json.tool

Configuration

Defaults live at the top of scripts/otsukare_usage.py; override per-call via flags (--soft 85, --stale-buffer 10, …) or environment variables (OTSUKARE_SOFT=85):

ConstantDefaultMeaning
SOFT90Soft threshold (%) — pause if substantial work remains
HARD97Hard ceiling (%) — always pause
STALE_BUFFER8Points added to usage when the data file is stale (rounds against you)
STALE_AGE120Seconds before a read is considered stale
RESUME_OFFSET_MIN10Minutes after reset to resume

Helper modes

otsukare_usage.py                     # decision for current usage
otsukare_usage.py --preflight         # is this a subscription plan with 5h/7d limits? (vs API/usage-billed)
otsukare_usage.py --wait-fresh        # block until the mirror is freshly rendered with a current 5h reset
otsukare_usage.py --arm               # safety-net target for the 5h window (validate-or-fallback)
otsukare_usage.py --resume-check N    # 'clear' / 'wait' against binding reset epoch N
otsukare_usage.py --cron-for EPOCH    # bounded retry-window cron string for EPOCH
otsukare_usage.py --state S --state-action init|pause|resume|summary   # run-metrics lifecycle + summary

How tokens & cost are measured

The summary reports the delta over the otsukare span, not whole-session totals — because both the token and cost sources are session-cumulative and a session often includes work from before otsukare was invoked.

  • Baseline + delta. At skill start, otsukare snapshots a baseline (current token total and total_cost_usd). At completion it subtracts the baseline. Across pauses/resumes the baseline is re-snapshotted at each resume and the per-segment deltas are summed, so the number reflects only the wrapped task. (State is keyed by the original session_id, so a dead-man's-switch resume in a fresh session still accumulates into the same totals.)

  • Tokens come from the session transcript (transcript_path in the statusline blob) — a .jsonl where each assistant message carries a usage object. otsukare sums:

    • in/out = input_tokens + output_tokens
    • cache = cache_creation_input_tokens + cache_read_input_tokens

    These are shown separately on purpose: cache-read usually dominates the raw count (re-reading context each turn is cheap), so a single "total tokens" figure is misleading. The blob's context_window.total_input_tokens is not used — it's the current context-window size, not cumulative usage.

  • Cost comes from the statusline blob's cost.total_cost_usd — Claude Code's own running cost meter — as a start→end delta. Because it accounts for cache and model pricing automatically, cost is the most honest bottom line of the four numbers.

  • Run time is wall-clock from started_at to completion, split into active (sum of work segments) and waiting (sum of paused-for-reset gaps) via the pause/resume timestamps.

Caveats. The numbers are best-effort: tokens depend on the transcript being readable, and a hard cut mid-segment can miss the sliver of work since the last checkpoint. The arithmetic lives in the unit-tested helper (--state-action init|pause|resume|summary), not in model prose, so the accounting itself is deterministic.

Limitations

  • Resume needs Claude Code running. The resume fires via a scheduled job that runs while the REPL is idle. It's robust if your machine stays awake with Claude Code open; if the app is fully quit at reset time, resume waits until it's next launched.
  • Usage data is best-effort. The mirror file refreshes when the statusline renders (every few seconds while active). At start and resume, otsukare blocks on a --wait-fresh barrier until a render lands with a current 5h window, so it never reads a stale reset from a previous session; a conservative stale buffer covers any remaining idle gap. It still isn't a guaranteed live meter.
  • Account-global usage. Limits are shared across all your sessions; otsukare reads whichever session rendered last and verifies freshness before trusting a "cleared" reading.
  • Foreground subagents only during a wrapped run (background agents can't be drained at a checkpoint).

License

MIT © Will Hsiao

Ver o original no GitHub

Bom para

Relacionados