claude-wake 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kazuki Nakayashiki
+
+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,204 @@
+# claude-wake
+
+**Auto-resume Claude Code in the VS Code panel when your usage limit resets — while you sleep.**
+
+You're deep in a task and Claude Code stops:
+
+```
+You've hit your session limit · resets 3:30am (America/Los_Angeles)
+```
+
+It's midnight. The limit lifts at 3:30am. Nobody's awake to type "continue" — so
+six hours evaporate. **claude-wake** waits for the reset, re-focuses that exact
+panel, and submits a resume message for you. You wake up to finished work.
+
+There are two ways to run it: a **menu-bar app** or a **CLI** — same engine,
+same `~/.claude-wake` state, so pick whichever you like.
+
+---
+
+## 🚀 Fastest setup: let Claude Code do it
+
+Open a Claude Code session (anywhere) and paste this. It clones, installs, and
+enables claude-wake for you, then walks you through the one‑time permission:
+
+```text
+Set up "claude-wake" for me — it auto-resumes my Claude Code (VS Code panel)
+when my usage limit resets. Steps:
+
+1. Clone https://github.com/kazuki-sf/claude-wake into ~/GitHub/claude-wake
+   (if it already exists, cd in and `git pull` instead).
+2. It's a zero-dependency Node CLI (needs Node 18+). Install it globally:
+   `cd ~/GitHub/claude-wake && npm install -g .`
+   If a global npm install is blocked, symlink it instead:
+   `mkdir -p ~/.local/bin && ln -sf ~/GitHub/claude-wake/bin/claude-wake.js ~/.local/bin/claude-wake && chmod +x ~/GitHub/claude-wake/bin/claude-wake.js`
+   (make sure ~/.local/bin is on PATH).
+3. Enable auto-resume at login: `claude-wake install`.
+4. Run `claude-wake doctor` and follow it to grant macOS Accessibility to the
+   KeySender.app it points to (one-time — required so it can paste into the panel).
+5. Confirm end-to-end with `claude-wake test` (pastes a harmless test message
+   into my most recent Claude Code panel), then show me `claude-wake status`.
+6. Ask me whether I also want the **menu-bar app** — a GUI dashboard with a live
+   countdown to the next resume, pause/resume, and message editing. If yes and
+   the Rust toolchain (`cargo`) is available, build it:
+   `cd app/src-tauri && cargo install tauri-cli --version '^2' --locked && cargo tauri build`,
+   then move the produced `.app` to ~/Applications and open it (it shares the
+   same daemon, so nothing double-runs). If Rust isn't installed, point me to
+   https://rustup.rs or let me skip it — the CLI already handles auto-resume.
+   If I say no, skip this step.
+
+Don't commit anything or modify my repos — everything lives under ~/.claude-wake.
+Then tell me it's running and that it'll resume a limited panel shortly after
+the limit resets.
+```
+
+> What this changes on your machine: it registers a **login item** (the
+> background watcher) and asks for a one-time macOS **Accessibility** grant to a
+> dedicated `KeySender.app` (so it can paste into the panel). Everything lives
+> under `~/.claude-wake`; remove it any time with `claude-wake uninstall`.
+
+> Prefer a GUI? After the CLI is set up, the **menu-bar app** is an optional
+> build — see [The menu-bar app](#the-menu-bar-app).
+
+---
+
+## Install it yourself
+
+### CLI
+
+Once published:
+
+```bash
+npm install -g claude-wake
+```
+
+From source (today):
+
+```bash
+git clone https://github.com/kazuki-sf/claude-wake ~/GitHub/claude-wake
+cd ~/GitHub/claude-wake
+npm install -g .          # zero dependencies; needs Node 18+
+claude-wake install       # start on login
+claude-wake doctor        # verify + grant Accessibility (guided)
+```
+
+### The menu-bar app
+
+A small tray/menu-bar dashboard (Tauri: Rust + plain HTML, no npm frontend).
+Build it from source — needs the Rust toolchain:
+
+```bash
+cd ~/GitHub/claude-wake/app/src-tauri
+cargo install tauri-cli --version '^2' --locked   # once
+cargo tauri build                                 # → target/release/bundle/…
+```
+
+That produces a `.app` (macOS). It's unsigned (OSS) — first launch: right-click
+→ Open. The app bundles the engine and shares `~/.claude-wake` with the CLI, so
+**don't run two watchers** — use the app *or* the CLI daemon, not both. See
+[`app/README.md`](app/README.md).
+
+### macOS: grant permission once
+
+Pasting into the panel needs the **Accessibility** permission. claude-wake
+compiles a tiny dedicated `KeySender.app` on your machine so you grant it to
+**one app only** — not your terminal, not Node. `claude-wake doctor` opens the
+right settings pane and shows exactly what to add:
+
+> System Settings → Privacy & Security → Accessibility → add & enable
+> `~/.claude-wake/KeySender.app`
+
+---
+
+## How it works
+
+1. **Detect** — Claude Code writes each session's transcript to
+   `~/.claude/projects/**/*.jsonl`. A usage limit is a structured entry whose
+   text carries the reset time **with timezone**. claude-wake tails these files
+   (cheap append-only reads) — no screen scraping.
+2. **Focus** — at reset time it opens
+   `vscode://anthropic.claude-code/open?session=<id>`, which brings the exact
+   panel to the front, even with many panels open.
+3. **Send** — the panel's input ignores fake keystrokes but accepts a paste, so
+   it puts the message on the clipboard and does **paste + Enter** — only after
+   confirming your editor is frontmost.
+
+It fires **once per limit** (duplicate events are de-duplicated), and if you
+already resumed manually, it notices and skips. The default message is
+deliberately **safe if it fires when it didn't need to**:
+
+> _"If you were stopped by a usage or token limit, continue from exactly where
+> you left off. If you were not stopped, or the task is already complete, ignore
+> this message."_
+
+## Using it
+
+**Menu-bar app** — click the ⚡ icon to open the popover:
+
+- Live **countdown** to the next resume, current state (Watching / Paused /
+  Not enabled), and recent activity.
+- Edit the **resume message** (applies live), **Pause/Resume**, **Send test**,
+  **Grant permission**, **Start on login**, open logs/config, GitHub, Quit.
+
+**CLI:**
+
+| Command                 | What it does                                                       |
+| ----------------------- | ----------------------------------------------------------------- |
+| `claude-wake watch`     | Watch and auto-resume in the foreground (`--dry-run` to log only). |
+| `claude-wake install`   | Start on login (launchd / systemd / Startup) and run now.         |
+| `claude-wake uninstall` | Stop and remove the login service.                                |
+| `claude-wake status`    | Daemon state + scheduled resumes (`--json` for machines).         |
+| `claude-wake pause` / `resume` | Suspend / un-suspend auto-resume.                          |
+| `claude-wake doctor`    | Check dependencies + permissions, with fixes.                     |
+| `claude-wake test`      | Fire a harmless test message into your latest session now.        |
+| `claude-wake set-message "…"` | Set the resume message (blank resets to default).           |
+| `claude-wake logs [-f]` | Recent log lines (`-f` to follow).                                |
+
+## Configuration
+
+Optional `~/.claude-wake/config.json` (the app edits `message` for you):
+
+```jsonc
+{
+  "message": "Continue from where you left off.", // resume text (one line)
+  "editor": "vscode",         // vscode | vscode-insiders | cursor | windsurf
+  "marginSeconds": 60,        // extra wait after the printed reset time
+  "pollSeconds": 20,          // transcript scan interval
+  "focusDelayMs": 2500,       // wait between opening the panel and pasting
+  "skipIfResumed": true,      // skip if you already continued manually
+  "allowUnverifiedPaste": false // Wayland only — see Platform support
+}
+```
+
+Invalid values fall back to safe defaults. Config changes apply live.
+
+## Platform support
+
+| Platform            | Status                                                          |
+| ------------------- | --------------------------------------------------------------- |
+| **macOS**           | ✅ Reference — verified end-to-end.                             |
+| **Linux (X11)**     | 🧪 Implemented (`xdotool` + `xclip`/`xsel`). Community-verify.  |
+| **Linux (Wayland)** | 🧪 Experimental; blind send, needs `allowUnverifiedPaste`.     |
+| **Windows**         | 🧪 Implemented (PowerShell `SendKeys`). Community-verify.       |
+
+## Security
+
+Zero runtime dependencies, no network, no `eval`. **The text it pastes is always
+your static `message`** — never derived from transcript or web content, so
+summarizing a malicious page can't make it paste anything. Keystrokes go only
+after verifying the editor is frontmost. Full trust model in
+[`SECURITY.md`](SECURITY.md); design in [`docs/design.md`](docs/design.md).
+
+## Uninstall
+
+```bash
+claude-wake uninstall     # stop + remove the login service
+npm rm -g claude-wake     # (or: rm ~/.local/bin/claude-wake)
+rm -rf ~/.claude-wake     # state, logs, KeySender.app
+# macOS: also remove KeySender from System Settings → Accessibility
+# app: drag claude-wake.app to the Trash
+```
+
+## License
+
+MIT © Kazuki Nakayashiki

package/bin/claude-wake.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  BASE_DIR,
+  CONFIG_FILE,
+  LOG_FILE,
+  DEFAULT_MESSAGE,
+  loadConfig,
+  projectsDir,
+  isPaused,
+  setPaused,
+  sanitizeMessage,
+  readConfigRaw,
+  writeConfigRaw,
+} from "../lib/config.js";
+import { createLogger } from "../lib/log.js";
+import { getEditor, isValidSessionId, EDITOR_NAMES } from "../lib/editors.js";
+import { watchLoop } from "../lib/watch.js";
+import { loadState } from "../lib/state.js";
+import { listTranscripts } from "../lib/detect.js";
+import { sendResume } from "../lib/send/index.js";
+import {
+  installDaemon,
+  uninstallDaemon,
+  daemonStatus,
+} from "../lib/install.js";
+import { runDoctor } from "../lib/doctor.js";
+
+const HELP = `claude-wake — auto-resume Claude Code (VS Code panels) when your usage limit resets
+
+Usage: claude-wake <command> [options]
+
+Commands
+  watch            Watch transcripts and auto-resume limited panels (foreground)
+                     --dry-run   detect + schedule, but only log instead of sending
+                     --quiet     no stdout (log file only; used by the daemon)
+  install          Register the watcher to start at login (launchd / systemd / Startup)
+  uninstall        Remove the login registration and stop the daemon
+  status           Show daemon state, pending resumes, and config summary (--json for machines)
+  pause            Suspend auto-resume (watcher keeps running)
+  resume           Un-suspend auto-resume
+  set-message <t>  Set the resume message (blank resets to default)
+  doctor           Check dependencies and permissions, with fix instructions
+  test             Fire one resume into the most recent session right now
+                     --session <id>   target a specific session id
+  logs             Print the last 40 log lines (-f to follow)
+
+Config: ${CONFIG_FILE}  (see README for keys)
+Editors: ${EDITOR_NAMES.join(", ")} (config "editor")
+`;
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flags = new Set(argv.slice(1).filter((a) => a.startsWith("-")));
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--")
+    ? argv[i + 1]
+    : null;
+}
+
+const selfPath = fileURLToPath(import.meta.url);
+
+function pkgVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(
+        path.join(path.dirname(selfPath), "..", "package.json"),
+        "utf8",
+      ),
+    ).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+async function main() {
+  switch (cmd) {
+    case "watch": {
+      const log = createLogger({ quiet: flags.has("--quiet") });
+      const cfg = loadConfig({ warn: log });
+      await watchLoop(cfg, log, { dryRun: flags.has("--dry-run") });
+      break;
+    }
+
+    case "install": {
+      // argv[1] = the bin path the user invoked (npm's stable symlink), NOT
+      // import.meta.url (a version-pinned realpath that dies on node upgrades).
+      const { dest, warnings } = installDaemon(process.argv[1] || selfPath);
+      console.log(`installed: ${dest}`);
+      for (const w of warnings) console.log(`warning: ${w}`);
+      console.log("the watcher now starts at login and is running.");
+      console.log("next: claude-wake doctor   (verify permissions)");
+      break;
+    }
+
+    case "uninstall": {
+      uninstallDaemon();
+      console.log("daemon stopped and login registration removed.");
+      console.log(
+        `(files in ${BASE_DIR} were kept — delete manually for a full removal)`,
+      );
+      break;
+    }
+
+    case "status": {
+      const cfg = loadConfig({
+        warn: flags.has("--json") ? () => {} : (m) => console.log(`warn: ${m}`),
+      });
+      const d = daemonStatus();
+      const st = loadState();
+      if (flags.has("--json")) {
+        // Stable machine-readable contract for the desktop app.
+        process.stdout.write(
+          JSON.stringify({
+            version: pkgVersion(),
+            daemonInstalled: d.installed,
+            daemonRunning: d.running,
+            paused: isPaused(),
+            editor: getEditor(cfg.editor).name,
+            message: cfg.message,
+            defaultMessage: DEFAULT_MESSAGE,
+            messageIsDefault: cfg.message === DEFAULT_MESSAGE,
+            watching: projectsDir(cfg),
+            pending: st.pending.map((p) => ({
+              sessionId: p.sessionId,
+              fire: p.fire,
+              event: p.event,
+            })),
+          }) + "\n",
+        );
+        break;
+      }
+      console.log(
+        `daemon:   ${d.installed ? (d.running ? "running" : "installed, NOT running") : "not installed"}`,
+      );
+      console.log(`state:    ${isPaused() ? "PAUSED" : "active"}`);
+      console.log(`editor:   ${getEditor(cfg.editor).name}`);
+      console.log(`watching: ${projectsDir(cfg)}`);
+      console.log(`pending:  ${st.pending.length}`);
+      for (const p of st.pending) {
+        console.log(
+          `  ${p.sessionId}  fires ${new Date(p.fire).toLocaleString()}`,
+        );
+      }
+      break;
+    }
+
+    case "pause": {
+      setPaused(true);
+      console.log("paused — auto-resume suspended (the watcher keeps running)");
+      break;
+    }
+
+    case "resume": {
+      setPaused(false);
+      console.log("resumed — watching for new limits");
+      break;
+    }
+
+    case "set-message": {
+      // The message is argv[1] (read directly so a leading "-" isn't eaten).
+      const clean = sanitizeMessage(argv[1] ?? "");
+      const raw = readConfigRaw();
+      if (clean) raw.message = clean;
+      else delete raw.message; // blank → fall back to the default
+      writeConfigRaw(raw);
+      console.log(clean ? "message updated" : "message reset to default");
+      break;
+    }
+
+    case "doctor": {
+      const ok = await runDoctor();
+      process.exitCode = ok ? 0 : 1;
+      break;
+    }
+
+    case "test": {
+      const cfg = loadConfig({ warn: (m) => console.log(`warn: ${m}`) });
+      let sessionId = flagValue("--session");
+      if (sessionId && !isValidSessionId(sessionId)) {
+        console.error("invalid --session id (expected a UUID)");
+        process.exitCode = 1;
+        break;
+      }
+      if (!sessionId) {
+        // Most recently modified transcript = most recently active session.
+        const files = (listTranscripts(projectsDir(cfg)) || [])
+          .map((f) => {
+            try {
+              return { f, m: fs.statSync(f).mtimeMs };
+            } catch {
+              return null;
+            }
+          })
+          .filter(Boolean)
+          .sort((a, b) => b.m - a.m);
+        if (!files.length) {
+          console.error(
+            `no session transcripts found under ${projectsDir(cfg)}`,
+          );
+          process.exitCode = 1;
+          break;
+        }
+        sessionId = path.basename(files[0].f, ".jsonl");
+        if (!isValidSessionId(sessionId)) {
+          console.error(
+            `most recent transcript has a non-UUID name (${sessionId}); use --session <id>`,
+          );
+          process.exitCode = 1;
+          break;
+        }
+      }
+      console.log(`sending a test resume into session ${sessionId} …`);
+      const res = await sendResume({
+        sessionId,
+        editor: getEditor(cfg.editor),
+        message:
+          "[claude-wake] Test message — setup works. You can ignore this.",
+        focusDelayMs: cfg.focusDelayMs,
+        allowUnverifiedPaste: cfg.allowUnverifiedPaste,
+        dryRun: flags.has("--dry-run"),
+        log: (m) => console.log(m),
+      });
+      console.log(res.ok ? `ok: ${res.detail}` : `FAILED: ${res.detail}`);
+      if (!res.ok) process.exitCode = 1;
+      break;
+    }
+
+    case "logs": {
+      if (!fs.existsSync(LOG_FILE)) {
+        console.log(`no log yet (${LOG_FILE})`);
+        break;
+      }
+      if (flags.has("-f") || flags.has("--follow")) {
+        if (process.platform === "win32") {
+          // no `tail` on Windows: naive size-diff follower
+          let pos = fs.statSync(LOG_FILE).size;
+          process.stdout.write(
+            fs
+              .readFileSync(LOG_FILE, "utf8")
+              .split("\n")
+              .slice(-10)
+              .join("\n") + "\n",
+          );
+          setInterval(() => {
+            try {
+              const size = fs.statSync(LOG_FILE).size;
+              if (size > pos) {
+                const fd = fs.openSync(LOG_FILE, "r");
+                const buf = Buffer.alloc(size - pos);
+                fs.readSync(fd, buf, 0, buf.length, pos);
+                fs.closeSync(fd);
+                process.stdout.write(buf.toString("utf8"));
+                pos = size;
+              } else if (size < pos) pos = 0;
+            } catch {
+              /* keep polling */
+            }
+          }, 1000);
+          return; // keep process alive
+        }
+        const { spawn } = await import("node:child_process");
+        spawn("tail", ["-f", LOG_FILE], { stdio: "inherit" });
+      } else {
+        const lines = fs.readFileSync(LOG_FILE, "utf8").trimEnd().split("\n");
+        console.log(lines.slice(-40).join("\n"));
+      }
+      break;
+    }
+
+    case "--version":
+    case "-v": {
+      console.log(pkgVersion());
+      break;
+    }
+
+    default:
+      console.log(HELP);
+      if (cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h")
+        process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error(`error: ${err.message}`);
+  process.exit(1);
+});