cc-session-recover 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.3 — 2026-06-12
+
+- Install only the runtime `.claude` files and `HANDOFF.md` into target projects; package tooling now stays in the npm package.
+- Enable hooks by default, with `--no-hooks` as the opt-out flag.
+- Add `cc-session-recover watch` for running the closed-terminal watcher through `npx`.
+- Remove the old one-time reminder flow and its `loop.md` prompt from the packaged workflow.
+
 ## 0.1.2 — 2026-06-12
 
 - Stop installing the package docs into target projects.

package/README.md

@@ -9,10 +9,10 @@ Every part of this has been verified against a genuine quota stop, end to end.
 ## Install
 
 ```sh
-npx cc-session-recover init --enable-local-hook /path/to/project
+npx cc-session-recover init /path/to/project
 ```
 
-(Or from a clone: `bash scripts/install-into-project.sh --enable-local-hook /path/to/project`.)
+(Or from a clone: `bash scripts/install-into-project.sh /path/to/project`. Pass `--no-hooks` with either to install the files without activating anything.)
 
 Approve the hooks once when Claude Code asks on the next start. That's the whole setup.
 
@@ -27,15 +27,21 @@ Give Claude your task, normally. Nothing extra to type — the injected standing
 
 If quota dies mid-task, work resumes automatically after the reset.
 
+## Why This Approach Is Stronger
+
+- It avoids `tmux`, `screen`, and terminal-injection hacks. Headless `claude -p --resume` is used only by the optional closed-terminal watcher, targeting the exact recorded session.
+- It gives you two recovery paths. With the terminal open, the heartbeat resumes inside the active Claude Code session. With the terminal closed, the watcher resumes the saved session id.
+- `HANDOFF.md` keeps the next step in the repo, with project state, recent progress, and the exact next action.
+- The heartbeat runs inside the active Claude Code session, so the original context stays alive while quota is blocked.
+
 ## Limits
 
 - It does not bypass quota. It only waits for the reset.
 - The basic flow needs the terminal to stay open. A closed-terminal recovery mode exists; see the docs.
-- Worst case is never lost work: the recovery note is always on disk, and "Read HANDOFF.md and continue" restores any session by hand. A one-time reminder at the reset time is also supported; see the docs.
+- Worst case is never lost work: the recovery note is always on disk, and "Read HANDOFF.md and continue" restores any session by hand.
 
 ## Docs
 
 - [Simple flow](docs/simple-flow.md) — how it works, told as a story (notebook, alarm, watchman).
 - [FAQ](docs/faq.md) — reliability, hook approval, what still needs a human.
-- [Full details](docs/claude-code-auto-resume.md) — closed-terminal watcher, precise reset-time resume, one-time reminders, all limits.
-- [Worked example](docs/verified-quota-resume-example.md) — a concrete one-time reminder example.
+- [Full details](docs/claude-code-auto-resume.md) — closed-terminal watcher, precise reset-time resume, all limits.

package/bin/cli.js

@@ -5,23 +5,24 @@
 // 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).
+//
+// Only files Claude Code must execute from inside the project are installed
+// (the .claude prompts, hooks, and status line wrapper). Tooling like the
+// watcher stays in this package and runs via `npx cc-session-recover watch`.
 
 const fs = require('fs');
 const path = require('path');
+const { spawn } = require('child_process');
 
 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',
-  'scripts/install-into-project.sh',
-  'scripts/quota-watcher.sh',
-  'scripts/test-fake-quota-flow.sh',
 ];
 
 const COPY_IF_MISSING = ['HANDOFF.md'];
@@ -39,18 +40,31 @@ const IGNORE_ENTRIES = [
 const IGNORE_HEADER = '# Claude Code session-recovery runtime state';
 
 function usage() {
-  console.error('Usage: cc-session-recover init [--enable-local-hook] [target-dir]');
+  console.error('Usage: cc-session-recover init [--no-hooks] [target-dir]');
+  console.error('       cc-session-recover watch [target-dir]');
+  console.error('Hooks are enabled by default; Claude Code still asks you to approve them once.');
   process.exit(2);
 }
 
+function watch(target) {
+  const script = path.join(TEMPLATE_ROOT, 'scripts', 'quota-watcher.sh');
+  const child = spawn('bash', [script, target], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code === null ? 1 : code));
+  child.on('error', (err) => {
+    console.error(`Could not start watcher: ${err.message}`);
+    process.exit(1);
+  });
+}
+
 function main() {
   const args = process.argv.slice(2);
-  if (args[0] !== 'init') usage();
+  if (args[0] !== 'init' && args[0] !== 'watch') usage();
 
-  let enableHook = false;
+  let enableHook = true;
   let target = '.';
   for (const arg of args.slice(1)) {
-    if (arg === '--enable-local-hook') enableHook = true;
+    if (arg === '--no-hooks') enableHook = false;
+    else if (arg === '--enable-local-hook') enableHook = true; // legacy no-op, was the old default-off flag
     else if (arg.startsWith('-')) usage();
     else target = arg;
   }
@@ -61,6 +75,11 @@ function main() {
     process.exit(1);
   }
 
+  if (args[0] === 'watch') {
+    watch(target);
+    return;
+  }
+
   for (const rel of FILES) {
     const src = path.join(TEMPLATE_ROOT, rel);
     const dest = path.join(target, rel);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-session-recover",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Quota-resume workflow for Claude Code: handoff notebook, heartbeat auto-continue, StopFailure hooks, and an unattended watcher that resumes after quota resets.",
   "scripts": {
     "check": "node --check bin/cli.js && bash -n scripts/*.sh .claude/hooks/*.sh .claude/statusline-quota-cache.sh && bash scripts/verify-claude-loop-workflow.sh",
@@ -12,7 +12,6 @@
   },
   "files": [
     "bin",
-    ".claude/loop.md",
     ".claude/auto-continue.md",
     ".claude/standing-instructions.md",
     ".claude/settings.example.json",

package/scripts/install-into-project.sh

@@ -3,15 +3,16 @@
 set -eu
 
 usage() {
-  printf 'Usage: %s [--enable-local-hook] /path/to/project\n' "$0" >&2
+  printf 'Usage: %s [--no-hooks] /path/to/project\n' "$0" >&2
+  printf 'Hooks are enabled by default; Claude Code still asks you to approve them once.\n' >&2
 }
 
-ENABLE_LOCAL_HOOK=0
+ENABLE_LOCAL_HOOK=1
 
-if [ "${1:-}" = "--enable-local-hook" ]; then
-  ENABLE_LOCAL_HOOK=1
-  shift
-fi
+case "${1:-}" in
+  --no-hooks) ENABLE_LOCAL_HOOK=0; shift ;;
+  --enable-local-hook) shift ;; # legacy no-op, was the old default-off flag
+esac
 
 if [ "$#" -ne 1 ]; then
   usage
@@ -26,19 +27,14 @@ TEMPLATE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
   exit 1
 }
 
-mkdir -p "$TARGET/.claude/hooks" "$TARGET/scripts"
+mkdir -p "$TARGET/.claude/hooks"
 
-cp "$TEMPLATE_ROOT/.claude/loop.md" "$TARGET/.claude/loop.md"
 cp "$TEMPLATE_ROOT/.claude/auto-continue.md" "$TARGET/.claude/auto-continue.md"
 cp "$TEMPLATE_ROOT/.claude/standing-instructions.md" "$TARGET/.claude/standing-instructions.md"
 cp "$TEMPLATE_ROOT/.claude/statusline-quota-cache.sh" "$TARGET/.claude/statusline-quota-cache.sh"
 cp "$TEMPLATE_ROOT/.claude/hooks/inject-standing-instructions.sh" "$TARGET/.claude/hooks/inject-standing-instructions.sh"
 cp "$TEMPLATE_ROOT/.claude/settings.example.json" "$TARGET/.claude/settings.example.json"
 cp "$TEMPLATE_ROOT/.claude/hooks/log-stop-failure.sh" "$TARGET/.claude/hooks/log-stop-failure.sh"
-cp "$TEMPLATE_ROOT/scripts/install-into-project.sh" "$TARGET/scripts/install-into-project.sh"
-cp "$TEMPLATE_ROOT/scripts/quota-watcher.sh" "$TARGET/scripts/quota-watcher.sh"
-cp "$TEMPLATE_ROOT/scripts/test-fake-quota-flow.sh" "$TARGET/scripts/test-fake-quota-flow.sh"
-
 if [ ! -f "$TARGET/HANDOFF.md" ]; then
   cp "$TEMPLATE_ROOT/HANDOFF.md" "$TARGET/HANDOFF.md"
 fi
@@ -46,9 +42,6 @@ fi
 chmod +x "$TARGET/.claude/hooks/log-stop-failure.sh"
 chmod +x "$TARGET/.claude/hooks/inject-standing-instructions.sh"
 chmod +x "$TARGET/.claude/statusline-quota-cache.sh"
-chmod +x "$TARGET/scripts/test-fake-quota-flow.sh"
-chmod +x "$TARGET/scripts/install-into-project.sh"
-chmod +x "$TARGET/scripts/quota-watcher.sh"
 
 # Keep runtime state out of the target's git history. HANDOFF.md must stay in
 # the project root (Claude Code blocks unattended edits inside .claude/), so

package/scripts/test-fake-quota-flow.sh

@@ -42,6 +42,8 @@ mkdir -p "$DUMMY"
 git -C "$DUMMY" init -q
 bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" --enable-local-hook "$DUMMY" >/dev/null
 [ -f "$DUMMY/.claude/settings.local.json" ] || fail "hook settings not installed"
+[ ! -d "$DUMMY/scripts" ] || fail "install must not create a scripts folder in the target"
+[ ! -d "$DUMMY/docs" ] || fail "install must not create a docs folder in the target"
 
 step "Fake SessionStart: standing instructions should be injected"
 INJECTED=$(printf '{"session_id":"fake-session-123","hook_event_name":"SessionStart","source":"startup"}' \
@@ -89,7 +91,7 @@ chmod +x "$BIN/claude"
 
 step "Run the watcher against the fake CLI"
 QUOTA_WATCH_INTERVAL=1 QUOTA_RESUME_BUFFER=1 PATH="$BIN:$PATH" \
-  bash "$DUMMY/scripts/quota-watcher.sh" "$DUMMY" >"$WORK/watcher.log" 2>&1 &
+  bash "$TEMPLATE_ROOT/scripts/quota-watcher.sh" "$DUMMY" >"$WORK/watcher.log" 2>&1 &
 WATCHER_PID=$!
 disown "$WATCHER_PID" 2>/dev/null || true
 

package/scripts/verify-claude-loop-workflow.sh

@@ -20,7 +20,6 @@ require_text() {
   grep -Fqi -- "$text" "$ROOT/$file" || fail "$file must mention: $text"
 }
 
-require_file ".claude/loop.md"
 require_file ".claude/auto-continue.md"
 require_file "HANDOFF.md"
 require_file ".claude/settings.example.json"
@@ -30,26 +29,20 @@ require_file ".claude/standing-instructions.md"
 require_file "scripts/test-fake-quota-flow.sh"
 require_file "README.md"
 require_file "docs/claude-code-auto-resume.md"
-require_file "docs/verified-quota-resume-example.md"
+require_file "docs/simple-flow.md"
+require_file "docs/faq.md"
 require_file "scripts/install-into-project.sh"
 require_file "scripts/quota-watcher.sh"
 require_file "package.json"
 require_file "bin/cli.js"
 require_file "LICENSE"
 
-require_text ".claude/loop.md" "HANDOFF.md"
-require_text ".claude/loop.md" "git status --short"
-require_text ".claude/loop.md" "one small safe step"
-require_text ".claude/loop.md" "update HANDOFF.md"
-require_text ".claude/loop.md" "stop"
-
 require_text ".claude/auto-continue.md" "HANDOFF.md"
 require_text ".claude/auto-continue.md" "git status --short"
 require_text ".claude/auto-continue.md" "remaining checklist"
 require_text ".claude/auto-continue.md" "safe to fire at any time"
 require_text ".claude/auto-continue.md" "Cancel this recurring schedule"
 
-require_text "docs/claude-code-auto-resume.md" "one-time reminder"
 require_text "docs/claude-code-auto-resume.md" "auto-continue.md"
 require_text "docs/claude-code-auto-resume.md" "heartbeat"
 require_text "docs/claude-code-auto-resume.md" "claude"
@@ -61,12 +54,6 @@ require_text "docs/claude-code-auto-resume.md" "StopFailure"
 require_text "docs/claude-code-auto-resume.md" "Do not use"
 require_text "docs/claude-code-auto-resume.md" "/loop 1m"
 
-require_text "docs/verified-quota-resume-example.md" "02:25"
-require_text "docs/verified-quota-resume-example.md" "one-time reminder"
-require_text "docs/verified-quota-resume-example.md" "git status --short"
-require_text "docs/verified-quota-resume-example.md" "Do not use"
-require_text "docs/verified-quota-resume-example.md" "/loop 1m"
-
 require_text "README.md" "install-into-project.sh"
 require_text "README.md" "npx cc-session-recover init"
 require_text "README.md" "not bypass quota"
@@ -94,7 +81,7 @@ require_text "scripts/quota-watcher.sh" "session_id"
 [ -x "$ROOT/scripts/test-fake-quota-flow.sh" ] || fail "scripts/test-fake-quota-flow.sh must be executable"
 
 for forbidden in "claude -p" "tmux" "screen" "expect" "TIOCSTI"; do
-  if grep -Fqi -- "$forbidden" "$ROOT/.claude/loop.md" "$ROOT/.claude/auto-continue.md" "$ROOT/HANDOFF.md"; then
+  if grep -Fqi -- "$forbidden" "$ROOT/.claude/auto-continue.md" "$ROOT/HANDOFF.md"; then
     fail "runtime workflow must not require $forbidden"
   fi
 done

package/.claude/loop.md

@@ -1,25 +0,0 @@
-# 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.