Home / All Skills / Workflow & Core Tools / claude-code-ping-start-5h-quota
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · daymade/claude-code-skills

claude-code-ping-start-5h-quota

When Claude subscription quota is exhausted before going to sleep or stepping away, set up a one-time local timer to automatically send a minimal `claude -p` message as soon as the quota resets, immediately opening a new 5-hour usage window—so by the time you wake up, most of the window has passed without burning your quota, effectively scoring a free cooldown period. Use when the user says things like: "My quota resets in X hours, ping Claude for me then", "I'm going to sleep, ping it when it resets to open a new window", "Out of quota, hit it right at reset time", "Set a timer to kick off a new 5-hour cooldown window", or mentions scheduled ping, ping Claude, quota ping, window opening, or sending a message right after quota reset. Limited strictly to one-time scheduled tasks on local macOS (caffeinate/BSD date); use /loop or cron for recurring tasks, use tibo-reset-codex to check when ChatGPT/Codex resets, and use claude-usage-analyst to diagnose why quota burned out.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessDual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE 文件；GitHub API spdx MIT；Copyright (c) 2025 daymade）Commit d5c4678cb5
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Leverage the window onset semantics: a 5-hour window begins on the 'first request within the window' rather than rolling over at a fixed time. Thus, if no one sends a message after reset, the window timer does not start; sending a minimal automated message immediately upon reset shifts the start of the window into sleep time.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
Claude 订阅的 5 小时用量窗口从**窗口内第一条请求**开始计时，而不是按固定时刻轮转。
What this accomplishes: turning the dead time of 'quota resetting while sleeping' into an advantage—by the time the user wakes up, the new window is mostly spent with virtually zero quota burned; 'the cost of a ping is negligible: a single-turn `claude -p` message. Fully tested and verified on 2026-08-29.'

The timer itself is a detached background process chain: caffeinate -is prevents sleep during the waiting period → sleep N seconds → cd $HOME → claude -p sends a single-turn message 'Reply with exactly: ok', launched via Bash run_in_background.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
caffeinate -is /bin/sh -c 'sleep <SLEEP_SECONDS> && cd "$HOME" && claude -p "Reply with exactly: ok"'
Command breakdown explaining why each component exists: caffeinate prevents idle/AC sleep (automatically released on process exit; cannot prevent physical lid closure); sleep is the simplest one-time carrier (do not rely on 'at' on macOS; ScheduleWakeup has an insufficient cap of 3600s); cd $HOME avoids loading project CLAUDE.md/hooks and burning tokens unnecessarily; claude -p is a genuine API request that exits after returning a single word.

run_in_background is the key semantic: a foreground sleep would be blocked by the harness; a detached background process does not rely on session survival, and its exit will wake the original session to form a 'double insurance'.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
**必须 run_in_background**：前台 sleep 会被 harness 拦截；后台任务是 detached 进程，且退出时会重新唤醒当前会话（见 Step 5）。
'Being woken up is itself an API request, acting as a mutual safety net with `claude -p`—either one will successfully open the window.' This is a design highlight: wake notification = host-initiated request, providing redundancy alongside the scheduled ping.

Idempotency and read-back verification: run `ps` before launching to check if an identical timer is already running (if so, report and ask whether to replace it); after launch, verify via `ps` that all three lines of the process chain (sh/caffeinate/sleep) exist.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
ps -ef | grep -E 'claude -p "Reply with exactly: ok"' | grep -v grep
'A launch receipt is not proof; use ps to verify that the process chain truly exists' serves as independent read-back verification; expect at least three lines, and a missing sleep line indicates the process failed to spin up.

Time conversion formula: wait minutes = minutes until reset + 5-minute buffer; absolute times earlier than or equal to current time are interpreted as the same time tomorrow (late-night inputs crossing midnight are standard); SLEEP_SECONDS = wait minutes × 60.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
换算公式（占位符全文统一）：`等待分钟数 = 距重置分钟数 + 5`；`SLEEP_SECONDS = 等待分钟数 × 60`。
Rationale for the +5 minute buffer: 'The reset time based on user description has variance; pinging before reset hits the old window, which is pure waste.' The target wall-clock time must be reported to the user ('the user wants to know the wall-clock time before bed'), along with explaining midnight-crossing semantics (e.g., 'resets at 6:15' means tomorrow morning).

Final verification and cancellation discipline: once woken up at the scheduled time, read the task output file, expecting 'ok' + '[exited with code 0]'; verify the actual trigger time using the output file mtime (stat -f '%Sm'); cancel using signature-string pkill and strictly forbid killing by sleep seconds.

daymade-claude-code/claude-code-ping-start-5h-quota/SKILL.md
**禁止按秒数 `pkill -f 'sleep <SLEEP_SECONDS>'`**：本机长驻脚本的心跳 sleep 可能恰好同秒数，实测发生过误杀
The cancellation command is pkill -f 'Reply with exactly: ok' (verified on 2026-08-29 to kill caffeinate and sh; harmless orphan sleep remains, but sh is dead so commands after && will not run); the output file path is written to the chat history during Step 4 as a fallback against 'lost notifications / context compression' ('if the path is also lost, inspect the process chain via ps... if no local evidence can be read, honestly report "cannot confirm locally"'—no false reporting).

2Core Capabilities

01One-time delayed quota window trigger (caffeinate anti-sleep + sleep timer + claude -p single-turn ping)
02Idempotency: detects existing timers before launch and prompts for replacement (no silent duplication)
03Independent process chain read-back verification (expected 3 lines in ps)
04Persistent declaration of task output path + wake-up final verification (ok / exit 0 / actual trigger time via stat)
05Safe signature-string cancellation (pkill 'Reply with exactly: ok'; strictly forbidden to kill by sleep seconds)
06Relative/absolute time conversion + midnight-crossing next-day semantics + 5-minute safety buffer

3External Dependencies

KindDependency / Endpoint
cliclaude（官方 Claude Code CLI；claude -p 单轮 print 模式）
clicaffeinate（macOS 防睡眠）
clisleep / date / ps / pkill / stat（macOS/BSD 系统工具）
cli宿主 Bash 的 run_in_background 后台任务 + task-notification 唤醒（harness 能力）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Execute local script or command: Agent executes in the host background: caffeinate -is /bin/sh -c 'sleep <S> && cd $HOME && claude -p
  • 网络端点: Declare external network access: Initiates an authentic subscription API request to Anthropic via the official claude CLI (single-turn claude -p; this is the core purpose of the skill)
Audit Notes: Unified grading: No script assets, no credential access (claude CLI uses its own authentication state; skill does not read keys/cookies/envs), and no direct networking code—primarily local system CLI/process management (leans Blue). Justification for elevating to Yellow: ① Generates authentic outbound network API traffic via the official claude CLI (targets Anthropic; expected, but burns subscription quota and initiates a usage window); ② Instructions include 'retry with dangerouslyDisableSandbox: true when blocked by sandbox'—advising host sandbox bypass for caffeinate/claude under specific failure paths represents a security downgrade requiring user awareness; ③ Long-running background processes + signature-string cancellation via pkill retain a residual surface of miskilling other processes (skill enforces anti-miskill discipline, but risk remains non-zero).

5Second-Pass Verification

  • [ok] 无自带脚本/资产（纯指令 skill） — glob 确认目录仅 SKILL.md；external_deps/internal_assets 不夸大（asset 列表为空）。
  • [ok] caffeinate/sleep/claude -p 命令链存在且为固定模板 — Step 2 代码块逐字存在；命令解剖表逐组件解释；无 shell 拼接注入（数字换算后入占位符）。
  • [ok] run_in_background 语义与双保险 — SKILL.md 原文『后台任务是 detached 进程，且退出时会重新唤醒当前会话』与 Step 5『被唤醒本身也是一次 API 请求』一致。
  • [ok] 幂等检查与 ps 读回验证 — Step 0 的 ps grep 命令与 Step 3 的三行预期存在；Step 4 交代 output 路径进对话历史。
  • [ok] 凭证接触面为零 — token 扫描（API_KEY/token/cookie/secret/Authorization）零命中；无 env/keychain/文件读取。
  • [ok] pkill 取消纪律（防误杀） — 禁止按秒数 pkill 的原文与实测误杀背景存在；特征串 pkill 为唯一取消路径。
  • [ok] 功能声明 vs 夸大检查 — 『5 小时窗口从窗口内第一条请求起算』是描述性机制声明（对 Claude 订阅语义的表述，标注 2026-08-29 实测）；skill 边界（macOS/一次性/不查询重置时刻）自我声明清晰，无越界承诺。
  • [ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。

6Verdict & Scenarios

  • Time arbitrage based on the subscription rule where 'the window starts on the first request', offering a clear value proposition at minimal cost (a single `claude -p` message).
  • Double insurance and restorable state design: `claude -p` and session wake-up back each other up, output path is recorded in chat history against compression loss, and lack of evidence is reported honestly as unconfirmed.
  • Anti-miskill and idempotency discipline forged from real testing: forbidden to pkill by sleep duration (previously miskilled heartbeat sleeps), pre-launch duplicate checks, and full replacement workflows.
  • Transfers system knowledge to subsequent agents: command breakdown explains 'why it is here and what breaks if changed' for each component, preventing future agents from optimizing away critical parts.
  • Honest boundaries: macOS-only, one-time only, no reset prediction, and no false promises when machines are shut down or lids are closed—no pretense of universal applicability.
    • Best for: Best for: Local macOS users whose Claude subscription quota is exhausted, will reset in a few hours, and who want to shift the start of their 5-hour window into sleeping/away hours; scenarios where a one-time timer semantic is acceptable, and where users are willing to verify via `ps` after launch and record the output path. Triggered by phrases in the description ("X hours until reset", "ping when it resets while I sleep", etc.).
    Not for: Not suitable for: Non-macOS environments (Linux caffeinate/date -v are unavailable and untested); recurring keep-alive/daily schedules (use /loop or cron instead); querying/predicting ChatGPT/Codex reset times (route to tibo-reset-codex); machines frequently shut down or closed (cannot fulfill promises); users uncomfortable with 'retrying with sandbox disabled' or background processes.
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload claude-code-ping-start-5h-quota.tar.gz
    sha256: c6f9d07b09144f82…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.