$ claude
  … ✗ You've hit your session limit · resets 4:10pm (Asia/Dhaka)

$ claude-standby resume-at
  Resume scheduled.
    workspace  : ~/projects/my-app
    resume at  : auto-detect (probing every 30 min until the limit lifts)
    session    : 612fb08b — the original conversation continues (claude --resume)
    importance : critical
    daemon     : running detached, wakes every 60s

$ # …close the laptop lid. Walk away.
  # At reset: desktop notification → YOUR session picks up where it stopped.

Screenshots

The VS Code cockpit (it follows your editor theme):

Everything in the panel maps 1:1 to a CLI command — the reference is built in:

Why

Long agentic tasks regularly outlive a usage window. When the limit hits,
the session dies mid-task — and you check back every twenty minutes so you
can type "continue" the moment it resets. That's an alarm clock job, not a
developer job. claude-standby takes the shift for you: one command
after the limit hits (soon: zero commands), and the task resumes itself
the moment resuming is possible.

Features

Installation

One command — no root, no dependencies beyond bash (jq recommended,
python3 used if present):

curl -fsSL https://raw.githubusercontent.com/0xsaju/claude-standby/main/install.sh | bash

This is the complete setup: the CLI lands on your PATH
(~/.local/bin) and the engine in ~/.claude-standby. Nothing else to
configure — exact-reset detection works automatically if your status line
already caches your usage (otherwise claude-standby setup-statusline
adds a tiny sensor, opt-in).

The tool manages itself from then on:

claude-standby update       # get the latest version (download + swap)
claude-standby doctor       # verify the whole environment
claude-standby uninstall    # remove cleanly (keeps your task state)

Windows: best-effort via WSL/Git Bash for now; native support
(Task Scheduler) is on the roadmap.

The cockpit (optional GUI)

A thin VS Code / Cursor panel over the same CLI — status bar, one-click
scheduling, and a dashboard. Install from your editor's Extensions view
(search "Claude Standby"), or directly:

• VS Code → Marketplace
• Cursor / Windsurf / VSCodium → Open VSX

On first run it offers to install the CLI above for you. The cockpit drives
the CLI; it never spawns or parses Claude Code itself.

Quick start

The day a limit interrupts you:

cd ~/projects/my-app
claude-standby resume-at          # auto-detect the reset, resume, done

Prefer an exact time, or want to watch?

claude-standby resume-at 20:00    # resume precisely at 20:00
claude-standby status             # task state, attempts, journal
claude-standby watch              # follow the daemon log live
claude-standby cancel             # stop everything, immediately

Track a long task up front so it carries an importance tier:

claude-standby start critical "Migrate the billing service to the new API"

Tip: alias cs='claude-standby'.

Commands

Full reference with examples: User Guide.

How it works

One small engine behind state.json, fed by data Claude Code already
produces. Nothing polls a server, nothing guesses — the whole flow, from
the limit to the resumed conversation:

sequenceDiagram
    actor You
    participant CC as Claude Code
    participant AR as claude-standby
    participant D as daemon
    Note over You,CC: your long task is running
    CC-->>You: 5-hour limit hit — task stops
    You->>AR: resume-at reset
    AR->>CC: read the exact reset time, pin your session
    AR->>D: schedule and spawn (detached)
    D->>D: wait for the reset (checks the clock)
    Note over D: window resets — quota is back
    D->>CC: claude --resume (your conversation)
    CC-->>You: same conversation continues

1. Schedule — resume-at pins the session to continue, records the task
   in ~/.claude/auto-resume/state.json, and spawns a small detached daemon.
2. Wait — the daemon wakes every 60 seconds, re-reads state (so cancel
   and reschedule always take effect within a tick), and compares wall-clock
   time. Each tick is a few local file reads: zero tokens, zero network.
3. Detect the reset — auto mode reads your live reset time from Claude
   Code's own usage data (streamed to the status line — a source we
   measured, F4) and schedules for that exact moment, no probe, no quota.
   No local data? It falls back to one minimal haiku probe whose limit
   message announces the reset time (…resets 4:10pm, measured — F1).
4. Resume — a safety beat after the reset, claude --resume <session>
   continues the exact conversation headlessly. Success → done; a bounce
   off a still-active limit → back off and retry, bounded by max_resumes.

Task states move waiting → resuming → done (or failed / cancelled).
Everything the daemon knows lives in that one human-readable state.json —
also the contract every UI reads. One engine, many front doors:

bin/claude-standby    the CLI — the only interface
plugin/scripts/           the engine: state, daemon, rate sensor, time parsing
vscode-extension/         status-bar + dashboard cockpit for VS Code
test/                     fake-claude stub + full test suite
docs/                     user guide · architecture · decision log · findings

Detection is measured, never guessed

The exact behavior Claude Code emits at a limit hit is undocumented, and
code built on guessed formats fails silently at the worst possible moment
— so this project refuses to guess. Every detection path is written only
against formats we measured and recorded in
HOOK-FINDINGS.md, and cites them: the live rate
stream that carries the exact reset time (F4), the limit message the
fallback probe reads (F1), and the session store the resume id comes from
(F2). If we haven't measured it, we don't ship logic on it — and weekly
caps we can't beat, the docs say so plainly.

Project status

Alpha — the resume flow is complete and tested end-to-end against the
test harness (test/fake-claude.sh). Resuming through a real usage limit
is still unverified — see Contributing if you can help confirm it.

Development

git clone https://github.com/0xsaju/claude-standby
cd claude-standby
bash test/run-tests.sh        # full suite, no real quota ever spent

The suite exercises the state library across three JSON engines (jq,
python3, pure awk/sed), the daemon's full lifecycle, auto-detection
(rate-snapshot and probe paths) against a mode-switchable fake claude, the
status-line rate sensor, and the installer end-to-end. Ground rules live in
CLAUDE.md; every non-obvious decision is logged in
DECISIONS.md.

Documentation

Contributing

Contributions are welcome — see CONTRIBUTING.md.
Real-limit verification is especially valuable: confirming the exact
used_percentage at a genuine block, and that --resume continues the
conversation once it lifts.

Limitations

Stated plainly, because a tool that manages your quota shouldn't oversell:

• Weekly caps are untouchable. Everything here helps the rolling
  window only; nothing resumes you past a weekly cap (auto mode detects
  this case and tells you instead of probing forever).
• Resuming spends quota the moment it resets — that's the point, but
  choose critical deliberately.
• Headless resumes need pre-approved permissions to edit files;
  configure an allowlist (User Guide §6). The tool never adds
  --dangerously-skip-permissions for you.
• Daemons don't survive reboots yet (roadmap: OS-level one-shots).

License

MIT © claude-standby authors