claude-cache-keepalive 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fifthadj
+
+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,103 @@
+# claude-cache-keepalive (`cwarm`)
+
+Keep [Claude Code](https://claude.com/claude-code)'s **prompt cache warm while you're idle**, so coming back to a session you stepped away from doesn't pay a full cache‑miss.
+
+It runs `claude` inside a PTY it controls (via [node-pty](https://github.com/microsoft/node-pty)) and, when you've been idle past your plan's cache TTL, injects a tiny keepalive so the cache stays warm. Because injection is an in‑process PTY write, **it keeps working when the window is unfocused, minimized, or in the background** — only closing the window stops it.
+
+Cross‑platform, **no tmux required**. This is the missing piece for setups (Windows / Git Bash, plain terminals) where the usual tmux‑based keepalive isn't available.
+
+> ⚠️ **Honest note — this uses your usage/quota.** Keeping the cache warm means sending a small message (`hi`) when you go idle, which counts against your plan usage and leaves `hi` turns in the conversation. It only fires after a long idle (≈58 min on Max, ≈4 min on Pro) with a one‑TTL cooldown, so it's conservative — but it is opt‑in by design. If that trade‑off isn't for you, don't use it.
+
+## Install
+
+```sh
+npm install -g claude-cache-keepalive
+```
+
+This puts a `cwarm` command on your PATH (npm creates both the Unix and Windows shims automatically).
+
+## Usage
+
+```sh
+cwarm                 # = claude --continue, inside the keepalive host
+cwarm new             # any claude args are passed straight through
+cwarm resume
+cwarm -p "..."
+cwarm --version       # (passed through → prints claude's version)
+cwarm help            # cwarm's own help
+```
+
+It's transparent — type and use claude exactly as normal (no `Ctrl-b` prefix, no new keys). Exit claude (`/exit` or Ctrl‑C) and the host exits with it.
+
+**Pause keepalive:** `touch ~/.claude/cwarm.disabled` (delete to resume).
+**Log:** `~/.claude/cwarm-keepalive.log`.
+
+## How it works
+
+- **PTY host** — `cwarm` spawns `claude` inside a pseudo‑terminal it owns and transparently pipes your keyboard ↔ claude ↔ screen (and window resizes). This is the same approach tmux / expect / VS Code's terminal use, and the only robust way to inject input into a terminal program.
+- **Idle detection** — idle = time since your last keystroke. Self‑contained, no external files. When you step away, idle grows; when you type, it resets.
+- **Plan‑aware** — reads your plan from `~/.claude/.credentials.json`:
+  - **Max** → cache TTL 1 h → inject after ~58 min idle, cooldown 1 h.
+  - **Pro** → cache TTL 5 min → inject after ~4 min idle, cooldown 5 min.
+- **Focus/minimize independent** — injection is an in‑process `pty.write`, unrelated to window state. Only closing the window (ending the host process) stops it.
+
+## Optional: cache‑countdown statusline
+
+A small statusline add‑on shows the live countdown the keepalive is protecting:
+
+```
+[Opus 4.8] │ my-project │ ♻️ cache 58m12s
+```
+
+It's **opt‑in** and never clobbers your existing statusline — it **wraps** it (runs yours, then appends the `♻️ cache …` segment), backs up `settings.json` first, and is fully restorable:
+
+```sh
+cwarm setup            # interactive; asks before editing settings.json
+cwarm setup --remove   # restores your previous statusline
+```
+
+(Written in Node — no Python dependency, no Windows codepage issues.)
+
+## Configuration
+
+Environment variables (mostly for testing / advanced use):
+
+| Var | Meaning |
+|-----|---------|
+| `CWARM_MSG` | keepalive message (default `hi`) |
+| `CWARM_TICK_MS` | check interval (default `20000`) |
+| `CWARM_THRESHOLD_S` | override idle threshold (seconds) |
+| `CWARM_TTL_S` | override cooldown (seconds) |
+| `CWARM_CLAUDE` | path to the `claude` executable (otherwise auto‑detected via `which`/`where`) |
+| `CLAUDE_CONFIG_DIR` | Claude config dir (default `~/.claude`) |
+
+## Limitations
+
+- **No detach.** Closing the window ends the session — there's no tmux‑style detach/reattach (that would mean reimplementing a terminal multiplexer; out of scope). But minimize / background / unfocused all keep working.
+- **Single session.** Designed for one `cwarm` session at a time.
+- If you walk away mid‑typing, an injected `hi` is appended to whatever's in the input box. Rare and harmless.
+
+## Platform support
+
+- **Windows** (Git Bash / PowerShell / cmd / Windows Terminal): verified, including non‑ASCII (CJK) input.
+- **Linux arm64 / aarch64**: verified on a Raspberry Pi 4 (Debian, Node 22) — global install (node-pty compiled cleanly), `cwarm` launch, and live keepalive injection all confirmed. x64 expected to behave the same.
+- **macOS**: same cross‑platform mechanism (node-pty + your shell's `claude`); expected to work, not yet tested. Reports welcome.
+
+## 繁體中文
+
+讓 [Claude Code](https://claude.com/claude-code) 的 **prompt cache 在你離開時保持溫熱**，回來時就不必再付一次完整的 cache‑miss。
+
+`cwarm` 把 `claude` 跑在自己控制的 PTY 裡；當你閒置超過方案的 cache TTL 時，注入一個極小的 keepalive 訊息讓 cache 不過期。因為注入是行程內部的 PTY 寫入，**視窗非焦點、縮小、在背景都照常運作**——只有關閉視窗才會停。跨平台、**不需要 tmux**。
+
+> ⚠️ **誠實說明**：保溫＝閒置時送一則小訊息（`hi`），會消耗你的方案用量、並在對話留下 `hi` 紀錄。只在長時間閒置後才觸發（Max 約 58 分、Pro 約 4 分）且有冷卻，屬保守設計、明確 opt‑in。不接受這個取捨就別用。
+
+- **安裝**：`npm install -g claude-cache-keepalive`
+- **使用**：`cwarm`（＝`claude --continue` 跑在保溫 host 裡；其餘參數原樣轉給 claude）
+- **暫停**：`touch ~/.claude/cwarm.disabled`；**紀錄**：`~/.claude/cwarm-keepalive.log`
+- **選配 statusline**（顯示 `♻️ cache 58m12s` 倒數；會先備份、包裝既有 statusline、可一鍵還原）：`cwarm setup` / `cwarm setup --remove`
+- **限制**：不能 detach（關視窗＝結束，但縮小／背景照常保溫）。
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "claude-cache-keepalive",
+  "version": "0.1.0",
+  "description": "Keep Claude Code's prompt cache warm while idle, by running claude inside a PTY host and injecting a tiny keepalive when you step away. Cross-platform, no tmux required.",
+  "type": "module",
+  "bin": {
+    "cwarm": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "fifthadj",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fifthadj/claude-cache-keepalive.git"
+  },
+  "homepage": "https://github.com/fifthadj/claude-cache-keepalive#readme",
+  "bugs": {
+    "url": "https://github.com/fifthadj/claude-cache-keepalive/issues"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "prompt-cache",
+    "keepalive",
+    "pty",
+    "node-pty"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "node-pty": "^1.0.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// cli.mjs — `cwarm` 指令。攔截 `setup` 子指令，其餘原樣轉給 claude。
+import { startHost } from './host.mjs';
+
+const argv = process.argv.slice(2);
+const first = argv[0];
+
+if (first === 'setup') {
+  const { runSetup } = await import('./setup.mjs');
+  process.exit((await runSetup(argv.slice(1))) || 0);
+} else if (first === 'help' || first === '--cwarm-help') {
+  printHelp();
+  process.exit(0);
+} else {
+  startHost({ args: argv }); // 無參數時 host 內部預設 --continue
+}
+
+function printHelp() {
+  process.stdout.write(`cwarm — keep Claude Code's prompt cache warm while idle.
+
+Usage:
+  cwarm [claude args...]   Launch claude (default: --continue) inside the keepalive host.
+  cwarm setup              Optionally install the cache-countdown statusline (opt-in).
+  cwarm setup --remove     Remove the statusline this tool installed.
+  cwarm help               Show this help.
+
+Everything except the 'setup' subcommand is passed straight to claude
+(e.g. \`cwarm --version\`, \`cwarm resume\`, \`cwarm -p "..."\`).
+
+Keepalive only fires after you've been idle past the plan threshold
+(max ~58min / pro ~4min). Pause anytime:  touch ~/.claude/cwarm.disabled
+Log:  ~/.claude/cwarm-keepalive.log
+`);
+}

package/src/host.mjs

@@ -0,0 +1,96 @@
+// host.mjs — 把 claude 跑在自己控制的 PTY 裡，做透明 I/O 多工 + 內建 prompt cache 保溫。
+//   注入是行程內部的 pty.write，與視窗焦點/縮小無關；只要 host 行程活著就保溫。
+//   跨平台：靠 node-pty（Windows=ConPTY、mac/Linux=forkpty），不需 tmux。
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { defaultClaudeDir, planParams, detectPlan, decideInject } from './keepalive.mjs';
+
+const require = createRequire(import.meta.url);
+const isWin = process.platform === 'win32';
+
+// 跨平台找出 claude 執行檔的完整路徑（Windows 的 node-pty 不會自己補 .exe，需給全路徑）。
+export function resolveClaude() {
+  if (process.env.CWARM_CLAUDE) return process.env.CWARM_CLAUDE;
+  try {
+    const r = spawnSync(isWin ? 'where' : 'which', ['claude'], { encoding: 'utf8' });
+    const first = (r.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+    if (first) return first;
+  } catch { /* fall through */ }
+  return 'claude'; // 最後手段：交給 node-pty 用 PATH 試
+}
+
+// 算出要 spawn 的 (file, args)。Windows 上 .cmd/.bat shim 無法被 node-pty 直接 exec，改用 cmd.exe 包。
+function spawnSpec(claudeBin, args) {
+  if (isWin && /\.(cmd|bat)$/i.test(claudeBin)) {
+    return { file: process.env.ComSpec || 'cmd.exe', args: ['/c', claudeBin, ...args] };
+  }
+  return { file: claudeBin, args };
+}
+
+export function startHost(opts = {}) {
+  const pty = require('node-pty');
+  const claudeDir = defaultClaudeDir();
+  const LOG = path.join(claudeDir, 'cwarm-keepalive.log');
+  const DISABLE = path.join(claudeDir, 'cwarm.disabled');
+
+  const args = opts.args && opts.args.length ? opts.args : ['--continue'];
+  const { file, args: spawnArgs } = spawnSpec(resolveClaude(), args);
+
+  const ptyProc = pty.spawn(file, spawnArgs, {
+    name: process.env.TERM || 'xterm-256color',
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  // ---- 透明 I/O 多工 ----
+  // 直接寫 Buffer（純位元組轉送）：UTF-8 多位元組（中文等）才不會被重編碼弄壞。
+  let lastInput = Date.now();
+  if (process.stdin.isTTY) { try { process.stdin.setRawMode(true); } catch {} }
+  process.stdin.resume();
+  process.stdin.on('data', (d) => { lastInput = Date.now(); ptyProc.write(d); });
+  ptyProc.onData((d) => process.stdout.write(d));
+  process.stdout.on('resize', () => {
+    try { ptyProc.resize(process.stdout.columns || 80, process.stdout.rows || 24); } catch {}
+  });
+
+  // ---- 內建保溫 ----
+  const tickMs = Number(process.env.CWARM_TICK_MS) || 20_000;
+  const msg = process.env.CWARM_MSG || opts.msg || 'hi';
+  const overrides = {};
+  const thr = process.env.CWARM_THRESHOLD_S ?? opts.thresholdS;
+  const ttlO = process.env.CWARM_TTL_S ?? opts.ttlS;
+  if (thr != null) overrides.idleThreshold = Number(thr);
+  if (ttlO != null) overrides.ttl = Number(ttlO);
+
+  let lastFire = 0;
+  const timer = setInterval(() => {
+    const plan = detectPlan(claudeDir);
+    const { ttl, idleThreshold } = planParams(plan, overrides);
+    const now = Date.now();
+    if (decideInject({ now, lastInput, lastFire, idleThreshold, ttl, disabled: fs.existsSync(DISABLE) })) {
+      ptyProc.write(msg + '\r');
+      lastFire = now;
+      const idle = Math.round((now - lastInput) / 1000);
+      try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" plan=${plan} idle=${idle}s\n`); } catch {}
+    }
+  }, tickMs);
+
+  // ---- 收尾 ----
+  function restore() {
+    try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
+    try { process.stdin.pause(); } catch {}
+  }
+  ptyProc.onExit(({ exitCode }) => {
+    clearInterval(timer);
+    restore();
+    process.exit(exitCode || 0); // node-pty 會卡住 event loop，必須主動退出
+  });
+  process.on('exit', () => { try { ptyProc.kill(); } catch {} });
+  process.on('SIGTERM', () => { try { ptyProc.kill(); } catch {} process.exit(0); });
+
+  return ptyProc;
+}

package/src/keepalive.mjs

@@ -0,0 +1,41 @@
+// keepalive.mjs — 純決策邏輯 + plan 偵測（無 PTY、無副作用，便於單元測試）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// plan → { ttl(秒), idleThreshold(秒) }。對齊各家慣例：max 提早 ~2 分注入、pro 提早 1 分。
+export const PLAN_PARAMS = {
+  max: { ttl: 3600, idleThreshold: 3480 },
+  pro: { ttl: 300, idleThreshold: 240 },
+};
+
+export function planParams(plan, overrides = {}) {
+  const base = PLAN_PARAMS[plan] || PLAN_PARAMS.pro;
+  return {
+    ttl: overrides.ttl ?? base.ttl,
+    idleThreshold: overrides.idleThreshold ?? base.idleThreshold,
+  };
+}
+
+export function defaultClaudeDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+// 從 Claude Code 憑證判方案；讀不到一律當 'pro'（保守）。
+export function detectPlan(claudeDir = defaultClaudeDir()) {
+  try {
+    const cred = JSON.parse(fs.readFileSync(path.join(claudeDir, '.credentials.json'), 'utf8'));
+    return cred?.claudeAiOauth?.subscriptionType === 'max' ? 'max' : 'pro';
+  } catch {
+    return 'pro';
+  }
+}
+
+// 純決策：現在該不該注入 keepalive？
+//   idle = now - lastInput（使用者最後一次按鍵到現在）。自包含、跨平台、不依賴外部檔。
+export function decideInject({ now, lastInput, lastFire, idleThreshold, ttl, disabled }) {
+  if (disabled) return false;                              // 暫停開關
+  if (now - lastInput < idleThreshold * 1000) return false; // 使用者最近還在操作
+  if (now - lastFire < ttl * 1000) return false;            // 冷卻未滿一個 TTL
+  return true;
+}

package/src/setup.mjs

@@ -0,0 +1,80 @@
+// setup.mjs — opt-in 安裝/移除 cache-countdown statusline。
+//   原則：會動 settings.json → 先備份、互動確認、絕不偷蓋既有 statusline（改成「包裝」它）、可一鍵還原。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+import { defaultClaudeDir } from './keepalive.mjs';
+
+const claudeDir = defaultClaudeDir();
+const SETTINGS = path.join(claudeDir, 'settings.json');
+const ORIG = path.join(claudeDir, 'cwarm-statusline-orig.json');
+const SEGMENT = fileURLToPath(new URL('./statusline/segment.mjs', import.meta.url));
+
+const readJson = (file, dflt) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return dflt; } };
+const cwarmCommand = () => `node "${SEGMENT}"`;
+const isCwarmStatusline = (sl) =>
+  !!(sl && sl.type === 'command' && typeof sl.command === 'string' && sl.command.includes('segment.mjs'));
+
+async function confirm(q) {
+  if (process.argv.includes('--yes') || process.env.CWARM_YES) return true;
+  if (!process.stdin.isTTY) { console.log('(non-interactive; re-run with --yes to proceed)'); return false; }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const a = (await rl.question(q)).trim().toLowerCase();
+  rl.close();
+  return a === 'y' || a === 'yes';
+}
+
+function backup() {
+  if (!fs.existsSync(SETTINGS)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+  const bak = `${SETTINGS}.cwarm-bak.${ts}`;
+  fs.copyFileSync(SETTINGS, bak);
+  return bak;
+}
+
+export async function runSetup(args = []) {
+  return args.includes('--remove') ? removeStatusline() : installStatusline();
+}
+
+async function installStatusline() {
+  if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
+  const settings = readJson(SETTINGS, {});
+  const existing = settings.statusLine;
+
+  if (isCwarmStatusline(existing)) { console.log('cwarm statusline already installed. Nothing to do.'); return 0; }
+
+  console.log('\ncwarm setup — cache-countdown statusline (opt-in)\n');
+  if (existing) {
+    console.log('You already have a statusLine. cwarm will WRAP it (run yours, then append');
+    console.log('a "♻️ cache …" countdown). Your original is saved and fully restorable.');
+  } else {
+    console.log('No existing statusLine. cwarm installs a minimal one:  [model] │ ♻️ cache …');
+  }
+  console.log(`\nThis edits ${SETTINGS} (a timestamped backup is made first).`);
+  if (!(await confirm('Proceed? [y/N] '))) { console.log('Aborted. Nothing changed.'); return 1; }
+
+  const bak = backup();
+  fs.writeFileSync(ORIG, JSON.stringify(existing ?? null, null, 2)); // 存原 statusLine 物件供還原
+  settings.statusLine = { type: 'command', command: cwarmCommand(), refreshInterval: 3 };
+  fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+
+  console.log(`\n✓ Installed.${bak ? ' Backup: ' + path.basename(bak) : ''}`);
+  console.log('  Remove anytime:  cwarm setup --remove');
+  return 0;
+}
+
+async function removeStatusline() {
+  const settings = readJson(SETTINGS, null);
+  if (!settings) { console.log('No settings.json found; nothing to remove.'); return 0; }
+  if (!isCwarmStatusline(settings.statusLine)) { console.log("Current statusLine isn't cwarm's; leaving it alone."); return 0; }
+
+  backup();
+  const orig = readJson(ORIG, null); // 還原成安裝前的物件（或無）
+  if (orig) settings.statusLine = orig; else delete settings.statusLine;
+  fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+  try { fs.unlinkSync(ORIG); } catch {}
+
+  console.log('✓ Removed cwarm statusline; restored your previous setting.');
+  return 0;
+}

package/src/statusline/segment.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// segment.mjs — cwarm 的 statusLine：跑使用者原本的 statusline（若有）再接上「cache 保溫倒數」。
+//   純 Node、跨平台（不依賴 Python）；emoji 走 Node UTF-8 stdout，沒有 Windows cp950 問題。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { defaultClaudeDir, detectPlan } from '../keepalive.mjs';
+
+const claudeDir = defaultClaudeDir();
+const ORIG = path.join(claudeDir, 'cwarm-statusline-orig.json');
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+// cache 倒數段：用 transcript mtime 當 idle、plan 決定 TTL（max 1h / pro 5min）。
+function cacheSegment(payload) {
+  const tp = payload?.transcript_path;
+  if (!tp) return '';
+  let mtimeMs;
+  try { mtimeMs = fs.statSync(tp).mtimeMs; } catch { return ''; }
+  const plan = detectPlan(claudeDir);
+  const ttl = plan === 'max' ? 3600 : 300;
+  const idle = Math.max(0, Math.floor((Date.now() - mtimeMs) / 1000));
+  const rem = ttl - idle;
+  if (rem <= 0) return `\u{1F534} cache ${Math.floor(idle / 60)}m`;      // 🔴 已冷
+  if (rem <= 60) return `\u{1F7E1} cache ${rem}s`;                       // 🟡 快過期
+  return `♻️ cache ${Math.floor(rem / 60)}m${rem % 60}s`;       // ♻️ 倒數
+}
+
+// 跑使用者原本存起來的 statusLine 指令（餵同一份 stdin），回傳其輸出；沒有就 null。
+function runOriginal(raw) {
+  let orig;
+  try { orig = JSON.parse(fs.readFileSync(ORIG, 'utf8')); } catch { return null; }
+  if (!orig || orig.type !== 'command' || !orig.command) return null;
+  try {
+    const r = spawnSync(orig.command, { shell: true, input: raw, encoding: 'utf8', timeout: 3000, windowsHide: true });
+    const out = (r.stdout || '').replace(/\s+$/, '');
+    return out || null;
+  } catch { return null; }
+}
+
+function minimalBase(payload) {
+  const model = payload?.model?.display_name;
+  return model ? `[${model}]` : 'claude';
+}
+
+const raw = readStdin();
+let payload = {};
+try { payload = JSON.parse(raw); } catch { /* 空/壞就用空物件 */ }
+
+const seg = cacheSegment(payload);
+let base = runOriginal(raw);
+if (base == null) base = minimalBase(payload);
+// 接在末行尾（base 末端即最後一行末端）
+const out = seg ? `${base} │ ${seg}` : base;
+process.stdout.write(out + '\n');