cc-session-recover 0.1.0

package/.claude/auto-continue.md

@@ -0,0 +1,30 @@
+You are resuming a task that was interrupted, most likely by a quota stop.
+Act now. Do not describe these instructions, do not summarize them, and do not wait for a task.
+This prompt is safe to fire at any time, so if there is nothing to do, that is a normal outcome.
+
+Read `HANDOFF.md` now.
+
+If the Goal in the handoff is complete:
+
+1. Update `HANDOFF.md` so Current Status and the checklist show the goal is complete.
+2. Cancel this recurring schedule if one exists.
+3. Reply DONE and stop.
+
+If the Goal is incomplete, do the work now:
+
+1. Run `git status --short`.
+2. Inspect the current diff only enough to understand the working tree.
+3. Continue from `Next Exact Action`.
+4. Keep working through the remaining checklist.
+5. Run the narrowest relevant check after each step.
+6. Update `HANDOFF.md` after every small safe step.
+7. Stop only when the Goal is complete or you are blocked on the user.
+
+Rules:
+
+- Do not repeat completed work.
+- Do not start unrelated work.
+- Do not do broad refactors.
+- Do not run destructive commands.
+- Do not run expensive full test suites unless `HANDOFF.md` says they are needed.
+- If the handoff is missing or unclear, update it with what you know and stop.

package/.claude/hooks/inject-standing-instructions.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+# SessionStart hook.
+# Whatever this prints to stdout is added to Claude's context for the session,
+# so the user does not have to paste the heartbeat instructions every time.
+
+set -u
+
+PROJECT_DIR=${CLAUDE_PROJECT_DIR:-$(pwd)}
+INSTRUCTIONS="$PROJECT_DIR/.claude/standing-instructions.md"
+
+[ -f "$INSTRUCTIONS" ] || exit 0
+
+cat "$INSTRUCTIONS"
+
+exit 0

package/.claude/hooks/log-stop-failure.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -u
+
+PROJECT_DIR=${CLAUDE_PROJECT_DIR:-$(pwd)}
+CLAUDE_DIR="$PROJECT_DIR/.claude"
+HANDOFF="$PROJECT_DIR/HANDOFF.md"
+LOG="$CLAUDE_DIR/stop-failure-events.jsonl"
+MARKER="$CLAUDE_DIR/quota-blocked.json"
+STAMP=$(date '+%Y-%m-%d %H:%M:%S %Z')
+INPUT=$(cat)
+
+mkdir -p "$CLAUDE_DIR" || exit 0
+
+printf '{"logged_at":"%s","hook_input":%s}\n' "$STAMP" "$INPUT" >> "$LOG" 2>/dev/null || true
+
+# Marker for the optional unattended watcher. The watcher deletes it after a
+# successful resume; a stale marker is harmless otherwise.
+# If the status line cached the rate-limit reset time, stamp it in so the
+# watcher can sleep until exactly then instead of knocking on an interval.
+RATE_STATE='null'
+if [ -f "$CLAUDE_DIR/rate-limit-state.json" ]; then
+  RATE_STATE=$(cat "$CLAUDE_DIR/rate-limit-state.json" 2>/dev/null) || RATE_STATE='null'
+fi
+
+printf '{"logged_at":"%s","rate_limit_state":%s,"hook_input":%s}\n' "$STAMP" "${RATE_STATE:-null}" "$INPUT" > "$MARKER" 2>/dev/null || true
+
+# Dedupe: during one outage every blocked retry fires this hook again, so
+# only append a note when the handoff does not already end with one.
+if [ -f "$HANDOFF" ] && ! tail -5 "$HANDOFF" | grep -Fq 'claude-code-stop-failure'; then
+  {
+    printf '\n<!-- claude-code-stop-failure: %s -->\n' "$STAMP"
+    printf '\nAutomatic note: Claude Code hit a rate limit at %s.\n' "$STAMP"
+    printf 'Raw hook input was saved to `.claude/stop-failure-events.jsonl`.\n'
+    printf 'This hook cannot schedule a same-session resume by itself.\n'
+  } >> "$HANDOFF" 2>/dev/null || true
+fi
+
+exit 0

package/.claude/loop.md

@@ -0,0 +1,25 @@
+# Claude Code Resume Prompt
+
+Use this prompt for a one-time scheduled resume or for a slow `/loop`.
+
+Resume only if the task is incomplete.
+
+First read `HANDOFF.md`.
+
+Then:
+
+1. Run `git status --short`.
+2. Inspect the current diff only enough to understand the working tree.
+3. Continue exactly one small safe step from `Next Exact Action`.
+4. Run the narrowest relevant check for that step.
+5. Update HANDOFF.md with the new state.
+6. Stop after that small step.
+
+Rules:
+
+- Do not repeat completed work.
+- Do not start unrelated work.
+- Do not do broad refactors.
+- Do not run destructive commands.
+- Do not run expensive full test suites unless `HANDOFF.md` says they are needed.
+- If the handoff is missing or unclear, update it with what you know and stop.

package/.claude/settings.example.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-standing-instructions.sh"
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "matcher": "rate_limit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-stop-failure.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/standing-instructions.md

@@ -0,0 +1,10 @@
+Standing quota-recovery instructions for this project:
+
+If the user gives a multi-step coding task in this session:
+
+1. Keep `HANDOFF.md` updated after every small safe step.
+2. Create a recurring schedule every 45 minutes with this prompt: "Read .claude/auto-continue.md and follow it."
+3. Cancel that schedule when the task is fully complete.
+
+Do not create the schedule for quick questions or single-step requests.
+Do not create a second schedule if one already exists.

package/.claude/statusline-quota-cache.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+# Status line wrapper that caches rate-limit state for the quota workflow.
+#
+# Claude Code feeds the status line JSON that includes
+# rate_limits.five_hour.resets_at. This script saves those fields to
+# .claude/rate-limit-state.json so the StopFailure hook can stamp the exact
+# reset time into the quota marker when a quota stop happens.
+#
+# Display:
+# - If CLAUDE_QUOTA_STATUSLINE_DELEGATE is set, the same JSON is passed to
+#   that command and its output is shown, so an existing status line keeps
+#   working unchanged.
+# - Otherwise a minimal line with model and quota usage is printed.
+
+set -u
+
+INPUT=$(cat)
+
+DIR=$(printf '%s' "$INPUT" | jq -r '.workspace.project_dir // .cwd // empty' 2>/dev/null)
+
+if [ -n "$DIR" ] && [ -d "$DIR/.claude" ]; then
+  STATE=$(printf '%s' "$INPUT" | jq -c '{
+    five_hour_used: (.rate_limits.five_hour.used_percentage // null),
+    five_hour_resets_at: (.rate_limits.five_hour.resets_at // null),
+    seven_day_used: (.rate_limits.seven_day.used_percentage // null),
+    seven_day_resets_at: (.rate_limits.seven_day.resets_at // null),
+    cached_at: now | floor
+  }' 2>/dev/null)
+
+  if [ -n "$STATE" ] && [ "$(printf '%s' "$STATE" | jq -r '.five_hour_resets_at')" != "null" ]; then
+    printf '%s\n' "$STATE" > "$DIR/.claude/rate-limit-state.json" 2>/dev/null || true
+  fi
+fi
+
+if [ -n "${CLAUDE_QUOTA_STATUSLINE_DELEGATE:-}" ]; then
+  printf '%s' "$INPUT" | "$CLAUDE_QUOTA_STATUSLINE_DELEGATE"
+  exit 0
+fi
+
+MODEL=$(printf '%s' "$INPUT" | jq -r '.model.display_name // "Claude"' 2>/dev/null)
+FIVE=$(printf '%s' "$INPUT" | jq -r '.rate_limits.five_hour.used_percentage // empty' 2>/dev/null)
+RESETS=$(printf '%s' "$INPUT" | jq -r '.rate_limits.five_hour.resets_at // empty' 2>/dev/null)
+
+if [ -n "$FIVE" ] && [ -n "$RESETS" ]; then
+  RESETS_LOCAL=$(date -r "$RESETS" '+%H:%M' 2>/dev/null || date -d "@$RESETS" '+%H:%M' 2>/dev/null || echo '?')
+  printf '%s | 5h quota: %s%% (resets %s)' "$MODEL" "$FIVE" "$RESETS_LOCAL"
+else
+  printf '%s' "$MODEL"
+fi

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2026-06-12
+
+Initial release of the quota-resume template.
+
+### Included
+
+- `HANDOFF.md` notebook and `.claude/auto-continue.md` heartbeat prompt for automatic continuation after quota resets.
+- `SessionStart` hook that injects the standing instructions, so the setup never has to be typed.
+- `StopFailure` hook that logs quota stops and writes a marker for the unattended watcher.
+- Watcher script that resumes the exact recorded session headlessly once quota is back, sleeping until the known reset time plus a 15-minute buffer when the status line cache is configured.
+- Installer, verify script, plain-English docs, and a self-test that proves the whole chain in a throwaway repo without using real quota.
+
+### Verification
+
+- Every link was verified against real Claude Code sessions, including one genuine quota stop: the hook captured it, the heartbeat retried while blocked, and the first fire after the reset resumed and completed the task with no human input.

package/HANDOFF.md

@@ -0,0 +1,44 @@
+# Claude Code Handoff
+
+This file lives in the project root on purpose.
+Files under `.claude/` are treated as sensitive by Claude Code, so edits to them are blocked in unattended runs.
+
+Use this file for the current task only.
+Keep it fresh while work is active.
+Update it after each small step and before any long or risky step.
+
+## Goal
+
+- Not set yet.
+
+## Current Status
+
+- No active task is recorded yet.
+
+## Completed Work
+
+- None yet.
+
+## Remaining Checklist
+
+- [ ] Add the next task steps here.
+
+## Files Changed
+
+- None yet.
+
+## Commands Run
+
+- None yet.
+
+## Current Errors or Failing Tests
+
+- None known.
+
+## Known Risks
+
+- None known.
+
+## Next Exact Action
+
+- Set the goal and first safe step when a task starts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pradeep Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# cc-session-recover
+
+Keep a long Claude Code task recoverable when quota or a rate limit stops it.
+
+This project installs a small workflow into another repo. Claude keeps a handoff file and sets a slow in-session heartbeat. If the terminal closes after a quota stop is recorded, an optional watcher can resume the same Claude session from another shell.
+
+## Why This Approach Is Stronger
+
+- It has two recovery paths. With the terminal open, the heartbeat resumes inside the active Claude Code session. With the terminal closed, the watcher can resume the saved session id.
+- Claude Code hooks record the quota stop. The watcher uses `claude -p --resume` only for closed-terminal recovery, so it does not depend on terminal text.
+- `HANDOFF.md` keeps the next step in the repo. A resume has project state, recent progress, and the exact next action.
+- The heartbeat runs inside the active Claude Code session. It keeps the original context alive while quota is blocked.
+- The watcher covers closed terminals. It reads the quota marker, waits for the reset time when available, and resumes the saved session id.
+- The status line cache reduces noisy retries. When Claude Code exposes a reset time, the watcher sleeps until that time plus a buffer.
+- The fake quota test checks the full path: install, hook injection, quota marker, retry loop, exact-session resume, and marker cleanup.
+
+## What You Get
+
+- `HANDOFF.md`: the recovery note for the current task.
+- `.claude/auto-continue.md`: the prompt used by the recurring heartbeat.
+- `.claude/loop.md`: a one-step resume prompt for a scheduled one-time reminder.
+- A `SessionStart` hook that injects the standing instructions at the start of each Claude Code session.
+- A `StopFailure` hook that records quota stops and writes `.claude/quota-blocked.json`.
+- `scripts/quota-watcher.sh`: an optional watcher that uses the marker file to resume the recorded session with `claude -p --resume`.
+- `scripts/test-fake-quota-flow.sh`: an end-to-end test that proves the install, hooks, marker, and watcher without using real quota.
+
+## Install
+
+Use `npx` from any project:
+
+```sh
+npx cc-session-recover init /path/to/project
+```
+
+Enable the local Claude Code hooks during install:
+
+```sh
+npx cc-session-recover init --enable-local-hook /path/to/project
+```
+
+You can also install from a clone of this repo:
+
+```sh
+cd /path/to/cc-session-recover
+bash scripts/install-into-project.sh --enable-local-hook /path/to/project
+```
+
+Claude Code may ask you to approve the hooks the next time you start `claude` in that project. Approve them once.
+
+## Use It
+
+Start Claude Code in the target project:
+
+```sh
+cd /path/to/project
+claude
+```
+
+Then give Claude your real task.
+
+With hooks enabled, the `SessionStart` hook prints `.claude/standing-instructions.md` into Claude's context. That tells Claude to:
+
+1. Keep `HANDOFF.md` current after each small step.
+2. Create a recurring schedule every 45 minutes.
+3. Use this scheduled prompt: `Read .claude/auto-continue.md and follow it.`
+4. Cancel the schedule when the task is complete.
+
+If quota blocks the session, each heartbeat fails while quota remains blocked. The first heartbeat after the reset reads `HANDOFF.md` and continues from the recorded next step.
+
+The terminal must stay open for this heartbeat. The schedule lives inside the running Claude Code session.
+
+## Use Without Hooks
+
+If you install without hooks, include this with your task:
+
+```text
+Keep HANDOFF.md updated after every small safe step.
+
+Also create a recurring schedule every 45 minutes with this prompt:
+
+Read .claude/auto-continue.md and follow it.
+
+Cancel that schedule when the task is complete.
+```
+
+## One-Time Resume
+
+Use this when you know the quota reset time and want one future resume.
+
+Look at the reset time in the Claude Code status line. Add 10 to 15 minutes. Then ask Claude Code to schedule one reminder.
+
+Example:
+
+```text
+Update HANDOFF.md now.
+
+Then set a one-time reminder for 02:25 local time with this prompt:
+
+Read HANDOFF.md first. If the task is incomplete, run git status --short, inspect the current diff only enough to understand the working tree, continue exactly one small safe step from Next Exact Action, run the narrowest relevant check, update HANDOFF.md, and stop.
+```
+
+Pick a time like `02:25`, rather than exactly `02:00` or `02:30`.
+
+Use `/loop` for short polling jobs, such as checking CI. Avoid `/loop 1m` for overnight quota recovery.
+
+## Watcher For Closed Terminals
+
+The heartbeat dies when the terminal closes. If you need unattended recovery after that, enable the local hook and run the watcher from another shell:
+
+```sh
+bash scripts/quota-watcher.sh /path/to/project
+```
+
+The watcher needs `jq` and the `claude` CLI on `PATH`.
+
+When quota stops a turn, the hook writes `.claude/quota-blocked.json`. The watcher reads the saved `session_id` and runs:
+
+```sh
+claude -p --resume <session_id> --permission-mode acceptEdits "<contents of .claude/auto-continue.md>"
+```
+
+If the status line cache has a reset time, the watcher sleeps until that time plus a 15-minute buffer before it tries. Without a reset time, it retries on an interval.
+
+Close the interactive Claude Code session before you rely on the watcher. Otherwise the open session and the watcher may work on the same task.
+
+## Status Line Cache
+
+`.claude/statusline-quota-cache.sh` saves Claude Code rate-limit fields into `.claude/rate-limit-state.json`.
+
+The `StopFailure` hook copies that reset time into `.claude/quota-blocked.json`. The watcher uses it to wait for the reset instead of retrying blind.
+
+To keep your existing status line, set `CLAUDE_QUOTA_STATUSLINE_DELEGATE` to your current status line command. The wrapper passes the display through after it caches the quota data.
+
+## Test The Workflow
+
+Run the static project check:
+
+```sh
+bash scripts/verify-claude-loop-workflow.sh
+```
+
+Run the fake quota flow:
+
+```sh
+bash scripts/test-fake-quota-flow.sh
+```
+
+When you run the fake test, the script creates a throwaway repo, installs the workflow, fakes a `SessionStart` event, fakes a `rate_limit` `StopFailure`, replaces `claude` with a stub that fails twice, then checks that the watcher resumes the recorded session.
+
+## Limits
+
+- This does not bypass quota.
+- The heartbeat needs Claude Code to stay open and idle when the scheduled prompt fires.
+- The watcher needs the local hook marker file. It only acts after a quota stop gets recorded.
+- Headless resume cannot ask for permission. Review `--permission-mode acceptEdits` before you use it.
+- Scheduled tasks require Claude Code v2.1.72 or newer.
+
+## More Docs
+
+- [Simple flow](docs/simple-flow.md): the notebook, alarm, and watcher explained without code.
+- [FAQ](docs/faq.md): reliability, hook approval, and what still needs a human.
+- [Auto-resume details](docs/claude-code-auto-resume.md): full behavior and limits.
+- [Verified quota resume example](docs/verified-quota-resume-example.md): a concrete one-time reminder example.

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security Policy
+
+`cc-session-recover` is a local Claude Code recovery workflow. The highest-risk areas are Claude Code hook behavior, session-id handling, local project files, status line data, and unattended headless resume.
+
+## Supported Versions
+
+Security fixes target the latest release only. Early preview versions before the current `latest` tag are not supported.
+
+Check the current version:
+
+```sh
+npm view cc-session-recover version
+```
+
+## Reporting a Vulnerability
+
+Do not paste secrets, prompts, transcripts, tool output, local file contents, shell output, or exploit details into a public issue.
+
+Preferred path:
+
+1. Use GitHub private vulnerability reporting for this repository if it is available.
+2. If private reporting is not available, open a public issue with only a short summary and ask for a private contact path. Do not include sensitive details.
+
+Useful report details:
+
+- `cc-session-recover` version and install method.
+- Claude Code version, Node version, shell, and OS.
+- Whether the issue affects install, hooks, status line cache, `HANDOFF.md`, scheduled resume, or `scripts/quota-watcher.sh`.
+- A minimal reproduction that uses dummy paths and dummy data.
+- Whether any prompt, transcript, shell output, file content, local path, API key, or raw Claude session id was exposed.
+
+## Security-Sensitive Behavior
+
+Please treat these as security-relevant:
+
+- Raw prompts, assistant text, tool output, shell output, command arguments, file contents, local paths, transcript paths, workspace paths, API keys, or raw Claude session ids are printed or stored in an unsafe place.
+- Install overwrites Claude Code settings without warning or without leaving the existing file intact.
+- Hooks run unexpected commands, change unrelated files, or write files outside the target project.
+- `scripts/quota-watcher.sh` resumes the wrong session id.
+- `scripts/quota-watcher.sh` runs while the interactive session is still active and causes two sessions to work on the same task.
+- Runtime marker files are created with broad permissions or are included in version control.
+- Shell command construction can be changed by project paths, settings, or marker contents in a way that changes execution.
+
+These are usually not `cc-session-recover` security bugs:
+
+- Claude Code model behavior.
+- Claude Code authentication, billing, or quota behavior.
+- A local user intentionally reading files from their own account.
+- A scheduled resume failing because quota is still blocked.
+
+## Project Privacy Invariants
+
+`cc-session-recover` should store only the minimum state needed for recovery: handoff notes written by the user or agent, hook event metadata, rate-limit reset time, and a session id needed to resume the recorded Claude Code session.
+
+It must not store or print raw secrets, API keys, unrelated local file contents, unrelated shell output, or unrelated Claude Code transcript content.

package/bin/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict';
+
+// npx installer for the Claude Code quota-resume workflow.
+// Pure Node so it also works where bash is absent; the installed runtime
+// scripts themselves are bash and need a POSIX shell (macOS, Linux, WSL,
+// Git Bash).
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATE_ROOT = path.join(__dirname, '..');
+
+const FILES = [
+  '.claude/loop.md',
+  '.claude/auto-continue.md',
+  '.claude/standing-instructions.md',
+  '.claude/settings.example.json',
+  '.claude/statusline-quota-cache.sh',
+  '.claude/hooks/log-stop-failure.sh',
+  '.claude/hooks/inject-standing-instructions.sh',
+  'docs/claude-code-auto-resume.md',
+  'docs/verified-quota-resume-example.md',
+  'docs/simple-flow.md',
+  'docs/faq.md',
+  'scripts/install-into-project.sh',
+  'scripts/verify-claude-loop-workflow.sh',
+  'scripts/quota-watcher.sh',
+  'scripts/test-fake-quota-flow.sh',
+];
+
+const COPY_IF_MISSING = ['HANDOFF.md', 'README.md'];
+
+function usage() {
+  console.error('Usage: cc-session-recover init [--enable-local-hook] [target-dir]');
+  process.exit(2);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args[0] !== 'init') usage();
+
+  let enableHook = false;
+  let target = '.';
+  for (const arg of args.slice(1)) {
+    if (arg === '--enable-local-hook') enableHook = true;
+    else if (arg.startsWith('-')) usage();
+    else target = arg;
+  }
+
+  target = path.resolve(target);
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    console.error(`Target directory does not exist: ${target}`);
+    process.exit(1);
+  }
+
+  for (const rel of FILES) {
+    const src = path.join(TEMPLATE_ROOT, rel);
+    const dest = path.join(target, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    if (rel.endsWith('.sh')) {
+      try { fs.chmodSync(dest, 0o755); } catch (_) { /* no-op on Windows */ }
+    }
+  }
+
+  for (const rel of COPY_IF_MISSING) {
+    const dest = path.join(target, rel);
+    if (!fs.existsSync(dest)) {
+      fs.copyFileSync(path.join(TEMPLATE_ROOT, rel), dest);
+    }
+  }
+
+  if (enableHook) {
+    const local = path.join(target, '.claude', 'settings.local.json');
+    if (fs.existsSync(local)) {
+      console.error('Skipped hook enablement: .claude/settings.local.json already exists.');
+      console.error('Merge .claude/settings.example.json into it manually if wanted.');
+    } else {
+      fs.copyFileSync(path.join(TEMPLATE_ROOT, '.claude', 'settings.example.json'), local);
+    }
+  }
+
+  console.log(`Installed Claude Code session recovery workflow into ${target}`);
+  console.log('Next: start `claude` there and approve the hooks once when asked.');
+}
+
+main();