convez.ai
SkillAutomaçãoAvançado
xoonjaeho

Continuous — Continuidade de Sessão Além de Limites de Taxa

xoonjaeho/claude-skill-continuous

Mantém tarefas longas vivas além dos limites de taxa do Claude.ai

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill para Claude Code que mantém tarefas de longa duração ativas através dos limites de taxa de 5 horas do Claude.ai. Usa ScheduleWakeup para pausar automaticamente, hibernar em blocos de ~55 minutos e retomar a mesma tarefa quando o limite é resetado, preservando contexto da transcrição.

Instalação

$npx convez-ai xoonjaeho/claude-skill-continuous

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
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Refatoração de código em projetos grandes sem interrupção
  • Processamento de batch de análise de dados com múltiplas iterações
  • Correção sistemática de erros em bases de código extensas
  • Automação de tarefas repetitivas que excedem janelas de 5 horas

Veredito

Solução sofisticada para problema real do Claude.ai. Requer setup técnico (hooks, OAuth, estado em disco) e compreensão profunda de limites de taxa, mas entrega valor alto para workflows de longa duração. Ideal para builders que enfrentam limites regularmente.

README

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

/continuous — Session Continuity Across Rate Limits

A Claude Code skill that keeps a long-running task alive across Claude.ai's 5-hour rate-limit boundaries. When utilization reaches a threshold, the skill pauses (via ScheduleWakeup), sleeps in ~55-minute chunks (held just under the 1-hour cache TTL), and automatically resumes the same task in the same conversation when the limit resets.

Quick start

/loop /continuous 95 "<your task>"
  • 95 is the 5-hour utilization threshold (default 95). Below this, work proceeds.
  • Must be invoked through /loop — /continuous alone refuses (loop detection by transcript inspection).
  • Quote the task if it has spaces.

Examples:

/loop /continuous 95 "refactor the rendering pipeline"
/loop /continuous 90 "fix all type errors in the api package"
/loop /continuous "answer pending PRs"      # threshold defaults to 95

How it works

[invocation]
   /loop /continuous 95 "task"
   ├─ probe.py: inspects transcript — refuses if not in /loop
   ├─ writes per-session state.json
   └─ probes /api/oauth/usage

[normal operation]
   each tool call → PreToolUse hook (scripts/hook.py)
   ├─ if active state + 5h util ≥ threshold → blocks (exit 2 + stderr marker)
   └─ otherwise passes through

[on block]
   skill body parses marker
   ├─ axis=five_hour → ScheduleWakeup(min(reset+60, 3300), same prompt)
   └─ axis=seven_day (≥99% only) → terminate, push notify, no wakeup

[on wake]
   transcript context preserved → re-checks usage → resumes work

Files

continuous/
├── README.md              this file
├── LICENSE                MIT
├── SKILL.md               skill body Claude follows at runtime
└── scripts/
    ├── constants.py         single source of truth (markers, regex, paths)
    ├── usage_fetch.py       OAuth /api/oauth/usage client + disk cache
    ├── state.py             per-session state lifecycle
    ├── probe.py             unified turn-start probe
    ├── measure_cache_ttl.py prompt-cache TTL health monitor
    ├── hook.py              PreToolUse hook
    └── loop_check.py        /loop-context detector (transcript-based)

State and cache live at two locations:

~/.claude/cache/continuous/ — skill-private runtime files:

  • <session_id>.json — per-session state
  • ttl_health.json — cached TTL health-check (~30 day throttle)

~/.claude/cache/usage/ — shared OAuth usage cache (also read by other consumers on the same machine — e.g. a custom statusline):

  • oauth-usage.json — disk cache of /api/oauth/usage responses (TTL cache_ttl_sec, default 60s)
  • oauth-usage.lock — lock coalescing concurrent fetches (TTL lock_ttl_sec, default 30s)
  • .policy.json (optional) — per-user TTL override (see Configuration)

Install

1. Place the skill

Copy or clone this repo to ~/.claude/skills/continuous/:

git clone https://github.com/xoonjaeho/claude-skill-continuous ~/.claude/skills/continuous

The directory name continuous is significant — it must match the slash command (/continuous).

2. Register the PreToolUse hook

Open ~/.claude/settings.json, find hooks.PreToolUse (create the key if missing), and append:

macOS / Linux:

{
  "matcher": "*",
  "hooks": [
    {
      "type": "command",
      "command": "python \"$HOME/.claude/skills/continuous/scripts/hook.py\""
    }
  ]
}

Windows:

{
  "matcher": "*",
  "hooks": [
    {
      "type": "command",
      "command": "python \"%USERPROFILE%\\.claude\\skills\\continuous\\scripts\\hook.py\""
    }
  ]
}

Note: the \\ sequences are JSON string escapes for a single backslash. If GitHub or your viewer renders them as a single \, you must restore the doubled form when copying into settings.json — JSON parsers reject single backslashes.

The matcher * fires the hook on every tool call. The hook short-circuits to exit 0 unless an active /continuous session state file exists, so it has no effect outside this skill.

3. Verify

Run this from any shell — same command works on bash, zsh, cmd.exe, and PowerShell:

python -c "import json,pathlib; p=pathlib.Path.home()/'.claude'/'settings.json'; s=json.loads(p.read_text(encoding='utf-8')); hooks=[h for e in s.get('hooks',{}).get('PreToolUse',[]) for h in e.get('hooks',[]) if 'continuous' in h.get('command','')]; print('registered' if hooks else 'NOT registered')"

Expect registered. If you see NOT registered, re-check the JSON edit in step 2.

4. Disable / remove

Either:

  • Remove the hook entry from settings.json, or
  • Delete ~/.claude/skills/continuous/ (cache at ~/.claude/cache/continuous/ may also be cleared).

Configuration

The skill is intentionally minimal. There are two thresholds:

AxisThresholdSourceEffect on hit
5-houruser-supplied (default 95)command argScheduleWakeup 1h sleep, retry
7-dayhardcoded 99constants.py:SEVEN_DAY_THRESHOLDterminal — no resume

7-day is hardcoded because reset is up to 7 days away — sleep-and-retry is wasteful at that scale, terminal is the right behavior.

OAuth usage cache TTL override (optional)

The OAuth usage cache and its lock have two timing knobs, both defaulting to sensible values baked into constants.py. To override, create ~/.claude/cache/usage/.policy.json:

{
  "cache_ttl_sec": 60,
  "lock_ttl_sec": 30
}
KeyDefaultEffect
cache_ttl_sec60How long a /api/oauth/usage response is reused before re-fetch. Lower = fresher numbers in the rate-limit hook, more HTTP fetches per 5h cycle (no LLM token impact).
lock_ttl_sec30Lock TTL — concurrent fetchers wait on the lock to coalesce into one HTTP call. Should be ≥ typical fetch latency.

The file is optional. If absent or a key is missing, defaults apply. Values are loaded once at module import — restart Claude Code (and any independent consumer reading the same cache) for changes to take effect.

The file lives under ~/.claude/cache/usage/ rather than the skill directory because it is per-machine runtime configuration, not part of the skill's source. Cloning this repo does not ship the file.

Cache TTL alignment

Sleeps are capped at MAX_SLEEP_SEC (3300s), held just under Anthropic's 1h (3600s) prompt-cache TTL tier (observed active on Pro/Max with telemetry on). The TTL is a last-access timer running from the last pre-sleep cache write — and nothing accesses the cache during a sleep, so the window is NOT refreshed mid-sleep. A full 3600s sleep (plus scheduling overhead) therefore overruns the TTL: the cache expires and the whole context is re-written to the 1h tier on wake at the ~2x write rate, instead of read at ~0.1x.

Requirement — the 1h cache tier must be active. The whole approach is load-bearing on Anthropic granting the 1h (3600s) prompt-cache TTL. With only the default 5min (300s) tier, every sleep ≥ 5min misses regardless of the cap — no sub-300s cap keeps /continuous useful. The 1h tier is observed active on Pro/Max with telemetry on (correlation seen in measure_cache_ttl.py, not a documented guarantee); it is not a reliable manual toggle (ENABLE_PROMPT_CACHING_1H=1 is documented for API-key / Bedrock / Vertex / Foundry, untested on OAuth/Pro·Max). Verify with python scripts/measure_cache_ttl.py: a write tier ratio ≥ 5 (ideally ≫) means the 1h tier is being written. If it sits near 1, the tier is off and /continuous cannot ride rate-limit windows cheaply — ensure DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC are NOT set.

Measured (single ~1h hop, ~160k-token conversation):

Sleep gapcache_readeph_1h (re-write)OutcomeRel. cost
3649s (over TTL)25,709100,670MISS — ~80% of context re-written at 2x~1.0
3312s (capped, under TTL)158,820395HIT — context read from cache~0.1

So the 3300 cap cuts per-hop cost ~10x. This is why the cap exists — at 3600s every hop pays the re-write premium.

Detecting regression

Run python scripts/measure_cache_ttl.py periodically (e.g. monthly):

SignalHealthyRegression hintMitigation
write tier ratio (1h : 5m)≥ 5< 5Telemetry coupling — make sure DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC are NOT set
wake-turn eph_1h (cache_creation)≪ context size≈ context sizeSleep is overrunning the TTL — lower MAX_SLEEP_SEC further

Blind spot: the wake-turn read/input ratio is NOT a reliable miss signal. A boundary miss re-writes the context to the 1h tier with tiny input_tokens, so read/input stays high (measured 12,854 at the 3649s miss) and looks healthy. Watch wake-turn eph_1h (cache_creation.ephemeral_1h_input_tokens) instead — it spikes toward full-context size on a miss. measure_cache_ttl.py's current read/input check does not catch this.

cache_read_input_tokens is a single flat field — per-tier read breakdown is not exposed by Claude Code transcripts, so 1h vs 5m read split must be inferred from the write-tier ratio.

The skill auto-runs the health check (throttled to once per 30 days) on each /continuous activation. On regression the user is notified via PushNotification and a one-line warning is prepended to the wake/start message.

Troubleshooting

SymptomLikely causeFix
/continuous works only inside /loop dynamic mode.invoked without /loop prefixre-invoke via /loop /continuous …
401 from usage fetchaccessToken expiredrestart Claude Code (it refreshes credentials)
Hook blocks unrelated sessionstate file leaked from prior crash, or two Claude Code sessions running simultaneously where one has /continuous activerun python scripts/state.py --reap (or let it be reaped on the next /continuous activation that needs disambiguation — there is no passive background timer). The hook only auto-disambiguates between sessions when the tool payload includes session_id; without it, a single leftover state file applies to all sessions on the machine.
parse_fail_count increasinghook stderr marker driftedcheck BLOCK_MARKER_FORMAT matches BLOCK_MARKER_REGEX in constants.py
Hook errors block all toolssettings.json path wrongedit settings.json externally to fix path; cannot be fixed from inside Claude Code

Test mode bypass

CONTINUOUS_TEST_BYPASS=1 <your-bash-command>

or set CONTINUOUS_TEST_BYPASS=1 in the shell that launches Claude Code. The hook honors both forms and returns exit 0.

Component-level diagnostics

python scripts/usage_fetch.py                          # current usage (live)
python scripts/usage_fetch.py --mock '{"five_hour":{"utilization":97,"resets_at":"2030-01-01T00:00:00Z"}}'
python scripts/state.py --list                         # active sessions
python scripts/state.py --show <sid>                   # inspect one
python scripts/state.py --reap                         # remove stale (>7d)
python scripts/state.py --delete <sid>                 # remove a specific session
python scripts/hook.py --self-test --mock-util 96 --threshold 95
python scripts/loop_check.py --explain                 # is current turn in /loop?
python scripts/measure_cache_ttl.py                    # human-readable TTL report
python scripts/constants.py                            # print all constants + self-test

Limits / out-of-scope

  • 7-day threshold is not user-configurable (hardcoded 99)
  • key=value style args (e.g. round=N) are not parsed — positional only
  • No multi-session limit coordination (each /loop /continuous is independent)
  • No mid-turn pause: Claude can only pause between turns, not within a single response
  • Falls back to no-op when /loop exits — task continuation requires user re-invocation only after 7d-terminal events

Dependencies

  • Python 3.9+ (stdlib only — no requests, no dateutil, no third-party)
  • Claude Code build with ScheduleWakeup tool support and the built-in /loop dynamic mode
  • OAuth credentials at ~/.claude/.credentials.json (Pro/Max subscription)
  • The 1h prompt-cache TTL tier active (observed on Pro/Max with telemetry on) — load-bearing; see Cache TTL alignment for why and how to verify

/loop is a Claude Code built-in command, not a separate install. loop_check.py detects it by matching the literal SKILL.md header line # /loop — schedule a recurring or self-paced prompt in the transcript. If Claude Code changes that header upstream, edit LOOP_BODY_HEADER in scripts/loop_check.py to match.

PushNotification is a Claude Code deferred tool routed through whichever channel the user has configured (e.g. an OS notification, a chat plugin, etc.). If unavailable, the skill silently skips the push and still emits the in-terminal warning.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados