cckeep 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kamihork
+
+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.ja.md

@@ -0,0 +1,183 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/kamihork/cckeep/main/assets/logo.png" width="140" height="140" alt="cckeep ロゴ — 開いたまま保たれるリンク">
+
+  <h1>cckeep</h1>
+
+  <p><strong>Claude Code のリモートコントロールが黙って死ぬのを防ぎます。</strong><br>
+  リモートコントロールは約31秒で再試行を諦め、二度と戻りません。<br>
+  <code>cckeep</code> はそれを検知して繋ぎ直します — 作業中のセッションには触れずに。</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/cckeep"><img src="https://img.shields.io/npm/v/cckeep?color=1f9d8f&label=npm" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/cckeep"><img src="https://img.shields.io/npm/dt/cckeep?color=3987e5" alt="npm downloads"></a>
+    <a href="https://github.com/kamihork/cckeep/actions/workflows/test.yml"><img src="https://github.com/kamihork/cckeep/actions/workflows/test.yml/badge.svg" alt="test status"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/kamihork/cckeep?color=199e70" alt="license"></a>
+  </p>
+
+  <p><a href="https://kamihork.github.io/cckeep/">Website</a> | <a href="README.md">English</a> | 日本語</p>
+</div>
+
+## 何が問題か
+
+[リモートコントロール](https://code.claude.com/docs/en/remote-control)は、手元で動いている Claude Code のセッションをスマホや claude.ai から操作する機能です。接続が切れても自動で再接続してくれます — ただし **1/2/4/8/16秒のバックオフで5回まで**。合計 **31秒** の予算です。ノートを閉じる、Wi-Fi を切り替える、エレベーターに乗る。それだけで予算は尽き、接続は閉じられて二度と戻りません。
+
+もう一つの壊れ方もあります。`/rc reconnecting` の表示のまま永久に固まるパターンで、これが [anthropics/claude-code#34255](https://github.com/anthropics/claude-code/issues/34255) — 2026年3月から open、👍 99件、未修正です。
+
+どちらにせよ気づき方は同じです。スマホを開いたらセッションが消えている。公式に案内されている復旧方法は、机に戻って `/remote-control` と打つことです。
+
+## クイックスタート
+
+```sh
+npx cckeep install
+```
+
+バックグラウンドジョブを登録します(macOS は launchd、Linux は systemd user timer)。15秒ごとに確認し、死んでいるものを繋ぎ直します。
+
+条件が一つあります。**Claude Code が tmux の中で動いていること。** 素のターミナルで起動したセッションには別プロセスから入力を送る手段がなく、どんなツールでも手が出せません。→ [tmux で Claude Code を動かす](#tmux-で-claude-code-を動かす)
+
+```sh
+npx cckeep            # いま何が見えているか(何も変更しません)
+npx cckeep doctor     # tmux・ペイン・スケジューラの確認
+```
+
+> 机に戻る手間が省けたなら、⭐ が同じ問題を抱えている人に届く助けになります。
+
+## 作業中のセッションには打ち込みません
+
+これが設計上の核心です。タイマーでターミナルに文字を打ち込むツールは、「いま安全か」を確実に判断できない限り危険物でしかありません。以下はすべて実装され、[テスト](test/)されています。
+
+- **ターン実行中は絶対に打たない。** ペインを2秒あけて2回キャプチャします。実行中はスピナーとトークンカウンタが動くので、2回が一致すれば何も起きていない証拠、違えば手を出さない
+- **ダイアログには打たない。** 権限プロンプトや選択メニューでは Enter が「選択」になります。選択マーカーが画面にあれば、その回はスキップ
+- **あなたが開いたパネルには打たない。** `/remote-control` は QR コード付きのステータスパネルを開きます。cckeep が Enter を押すのは、自分で開いたときだけ
+- **自分で切ったセッションは戻さない。** 一度でも接続済みだったペインだけを追跡します。意図的に切ったものは切れたまま
+- **連打しない。** 1ペインにつき5分に1回まで
+- **直前に再確認する。** 判断は1回のキャプチャで下し、待機後にもう一度確認します。その間に復帰したりダイアログが出ていれば、何も送りません
+
+`--dry-run` を付けると、何をするつもりかだけを表示して一切送信しません。
+
+## 何を見ているか
+
+| 画面の状態 | 意味 | cckeep の動作 |
+|---|---|---|
+| `/rc active` | 接続中 | ペインを記憶するだけ |
+| `/rc reconnecting` | 31秒の予算内 | 待つ(たいていこれで直る) |
+| `/rc reconnecting` が2分継続 | 固着([#34255](https://github.com/anthropics/claude-code/issues/34255)) | パネルを開いて切断し、張り直す |
+| `Remote Control disconnected` | 諦めた | 即座に繋ぎ直す |
+| 表示なし(以前はあった) | 通知が流れて消えた | 4回静かなら繋ぎ直す |
+| 表示なし(一度もなかった) | そういう使い方ではない | 何もしない |
+
+## コマンド
+
+```
+cckeep                 # 状態表示: Claude Code のペインごとに1行
+cckeep watch           # スケジュール登録せずフォアグラウンドで実行
+cckeep once            # 1回だけ実行(スケジューラが叩くもの)
+cckeep install         # バックグラウンドジョブを登録
+cckeep uninstall       # 解除
+cckeep doctor          # tmux・ペイン・スケジューラ・各パス
+cckeep logs            # これまでの動作
+```
+
+オプション: `--dry-run`、`--json`、`--interval <秒>`、`--lang en|ja`(`LANG` から自動判定)。
+
+## tmux で Claude Code を動かす
+
+cckeep は tmux ペインを読み、そこに入力します。動いている Claude Code セッションに別プロセスから届く経路はこれだけで、だからこそ tmux 内での起動が必要です。プロセスの再起動は代替になりません — 会話が終わってしまい、守りたかったものそのものを失うからです。
+
+最小の変更は、対話起動だけを包むシェル関数です。`claude update` や `claude doctor`、`claude -p` はそのまま素通しします。
+
+```sh
+cc() {
+  local a
+  for a in "$@"; do
+    case "$a" in
+      -p|--print|-v|--version|-h|--help|--bg|--background|--output-format) command claude "$@"; return ;;
+      agents|auth|doctor|install|mcp|plugin|project|setup-token|update|upgrade|remote-control|rc|config)
+        command claude "$@"; return ;;
+      -*) ;;
+      *) break ;;
+    esac
+  done
+  local session="claude-$(basename "$PWD")-$(printf '%s' "$PWD" | cksum | cut -d' ' -f1)"
+  if [ -n "$TMUX" ]; then command claude "$@"
+  elif tmux has-session -t "=$session" 2>/dev/null; then tmux attach-session -t "=$session"
+  else tmux new-session -s "$session" -c "$PWD" claude "$@"
+  fi
+}
+```
+
+あわせて `~/.tmux.conf` に2行必要です。これが無いと tmux 内で Shift+Enter とデスクトップ通知が壊れます([公式の案内](https://code.claude.com/docs/en/terminal-config#configure-tmux))。
+
+```sh
+set -g allow-passthrough on
+set -s extended-keys on
+set -as terminal-features 'xterm*:extkeys'
+```
+
+Ctrl+B の衝突は対処不要です。Claude Code は tmux を検出して、自身のショートカットを `Ctrl+B Ctrl+B` に読み替えます。
+
+## 設定
+
+デフォルトは「存在に気づかない」ことを狙って調整してあります。`~/.cckeep/config.json`、環境変数、実行時フラグの順で上書きされます。壊れた設定ファイルは黙って一部だけ読むのではなく、エラーで停止します。
+
+```json
+{
+  "interval": 15,
+  "cooldown": 300,
+  "stuckLimit": 8,
+  "missLimit": 4,
+  "settle": 2000,
+  "paneCommand": "claude"
+}
+```
+
+- `interval` — 巡回間隔(秒)。`install` が登録する間隔でもある
+- `cooldown` — 同じペインに再度手を出せるまでの秒数
+- `stuckLimit` — `reconnecting` が何回続いたら固着とみなすか
+- `missLimit` — 表示のあったペインが何回無表示なら繋ぎ直すか
+- `settle` — 静止判定の2回のキャプチャ間隔(ミリ秒)。遅いマシンでは増やす
+- `paneCommand` — Claude Code のペインと判定するフォアグラウンドプロセス名
+
+すべてに環境変数版があります: `CCKEEP_INTERVAL`、`CCKEEP_COOLDOWN`、`CCKEEP_STUCK_LIMIT`、`CCKEEP_MISS_LIMIT`、`CCKEEP_SETTLE`、`CCKEEP_PANE_COMMAND`。`CCKEEP_HOME` で状態・設定・ログの置き場所を `~/.cckeep` から移せます。
+
+## 適用範囲
+
+cckeep がするのは接続の張り直しだけです。Claude Code の再試行予算そのものは**変えません** — クローズドソースのバイナリ内の定数であり、変えられるのは Anthropic だけです。[#34255](https://github.com/anthropics/claude-code/issues/34255) が修正されればこのツールは不要になります。それが正しい結末です。それまでは、ここに star を付けるより向こうに 👍 を付けるほうが価値があります。
+
+設計上、以下は対象外です。
+
+- **tmux 外のセッション** — 入力を送る経路がない
+- **VS Code 拡張** — ターミナル TUI ではなく、tmux で包めない
+- **サーバーモード**(`claude remote-control`)— 自分が起動したプロセスなので、launchd/systemd や `while true` ループで直接監督すればよい
+- **10分を超える通信断** — Claude Code 自身がセッションを終了するため、張り直す対象が残らない
+
+## プライバシー
+
+cckeep は接続状態を判定するために tmux ペインの表示テキストを読みます。それはあなたの会話です。したがって:
+
+- すべてローカルで完結し、このパッケージにネットワークコードはありません
+- テレメトリなし、アカウントなし、外部送信なし
+- ペインのテキストは数個の判定文字列と照合した後すぐ破棄され、ログに残るのはペイン名と判定結果だけです
+- ログは `~/.cckeep/cckeep.log`。`cckeep logs` で表示できます
+
+## 仕組み
+
+Claude Code はフッターにリモートコントロールの状態を描画します。接続中は `/rc active`、再試行中は `/rc reconnecting`、諦めたときは `Remote Control disconnected` の通知です。cckeep は tmux にフォアグラウンドプロセスが `claude` のペインを問い合わせ、`tmux capture-pane` からこれらを読み取り、ペインごとの小さなカウンタを `~/.cckeep/state.json` に保持します。
+
+判定層(`src/detect.js`)は画面テキストと直前の状態だけを引数に取る純粋関数です。だからこそ安全ルールをターミナル無しで網羅的にテストできます。I/O は実行層(`src/run.js`)が担当します — 静止判定、直前の再確認、キー送信です。
+
+これらは公開 API ではありません。判定文字列は UI テキストであり変わり得ます。変わったとき cckeep は誤動作ではなく沈黙します — 読めないペインは「一度も接続していない」ように見え、接続を見たことがないペインには決して手を出さないためです。
+
+## 開発
+
+```sh
+git clone https://github.com/kamihork/cckeep.git && cd cckeep
+npm test                       # 36テスト。ネットワークも tmux も不要
+node bin/cckeep.js doctor
+```
+
+テストは tmux をフェイクするのでどこでも走ります。コントリビューション歓迎です — 特に、検出が漏れる Claude Code のバージョンやターミナルでの実際の表示文字列が助かります。[CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+[MIT](LICENSE) © [kamihork](https://github.com/kamihork)

package/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/kamihork/cckeep/main/assets/logo.png" width="140" height="140" alt="cckeep logo — a link held open between two ends">
+
+  <h1>cckeep</h1>
+
+  <p><strong>Keeps Claude Code Remote Control from silently going dead.</strong><br>
+  Remote Control retries for about 31 seconds and then gives up for good.<br>
+  <code>cckeep</code> notices, and re-arms the session — without touching one that's busy.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/cckeep"><img src="https://img.shields.io/npm/v/cckeep?color=1f9d8f&label=npm" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/cckeep"><img src="https://img.shields.io/npm/dt/cckeep?color=3987e5" alt="npm downloads"></a>
+    <a href="https://github.com/kamihork/cckeep/actions/workflows/test.yml"><img src="https://github.com/kamihork/cckeep/actions/workflows/test.yml/badge.svg" alt="test status"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/kamihork/cckeep?color=199e70" alt="license"></a>
+  </p>
+
+  <p><a href="https://kamihork.github.io/cckeep/">Website</a> | English | <a href="README.ja.md">日本語</a></p>
+</div>
+
+## The problem
+
+[Remote Control](https://code.claude.com/docs/en/remote-control) lets you drive a local Claude Code session from your phone or from claude.ai. It reconnects on its own when the link drops — for **5 attempts with 1/2/4/8/16-second backoff**. That is a **31-second** budget. Close your laptop lid, switch Wi-Fi, ride an elevator, and the budget is gone. The connection closes and never comes back.
+
+There is a second failure too: the session wedges in `/rc reconnecting` and sits there forever. That one is [anthropics/claude-code#34255](https://github.com/anthropics/claude-code/issues/34255) — open since March 2026, 99 👍, no fix.
+
+Either way you find out the same way: you reach for your phone, and the session is gone. The documented recovery is to walk back to your desk and type `/remote-control`.
+
+## Quick start
+
+```sh
+npx cckeep install
+```
+
+That registers a background job — launchd on macOS, a systemd user timer on Linux — that checks every 15 seconds and re-arms whatever went dead.
+
+One requirement: **Claude Code has to be running inside tmux.** A session started in a bare terminal cannot be reached from another process, so there is nothing any tool can do for it. See [Running Claude Code in tmux](#running-claude-code-in-tmux).
+
+```sh
+npx cckeep            # what it sees right now — changes nothing
+npx cckeep doctor     # check tmux, panes, and the scheduler
+```
+
+> If cckeep saved you a walk back to your desk, a ⭐ helps other Remote Control users find it.
+
+## It will not type into a session that is working
+
+This is the whole design problem. A watchdog that types into your terminal on a timer is a liability unless it is certain the moment is safe. Every one of these is enforced, and [tested](test/):
+
+- **Never during a turn.** The pane is captured twice, two seconds apart. A running turn animates a spinner and a token counter, so identical captures mean nothing is happening. Different ones mean hands off.
+- **Never into a dialog.** Permission prompts and pickers turn Enter into a selection. If a selection marker is on screen, the pass is skipped.
+- **Never into the panel you opened.** `/remote-control` opens a status panel with a QR code. cckeep only presses Enter there when it opened the panel itself.
+- **Never a session you turned off.** Only panes seen connected at least once are ever chased. Disable Remote Control deliberately and it stays off.
+- **Never in a tight loop.** One action per pane per 5 minutes.
+- **Re-checked at the last moment.** The decision is made from one capture, then re-verified after the idle wait — if the pane reconnected or opened a dialog in between, nothing is sent.
+
+`--dry-run` prints what it would do and sends nothing.
+
+## What it watches for
+
+| State on screen | What it means | What cckeep does |
+|---|---|---|
+| `/rc active` | connected | remembers the pane, nothing else |
+| `/rc reconnecting` | inside the 31-second budget | waits — this usually resolves |
+| `/rc reconnecting`, 2 minutes on | wedged ([#34255](https://github.com/anthropics/claude-code/issues/34255)) | cycles the bridge: opens the panel, disconnects, reconnects |
+| `Remote Control disconnected` | gave up | re-arms immediately |
+| no indicator, on a pane that had one | notification scrolled away | re-arms after 4 quiet checks |
+| no indicator, on a pane that never had one | not your setup | nothing, ever |
+
+## Commands
+
+```
+cckeep                 # status: one line per Claude Code pane
+cckeep watch           # run in the foreground instead of scheduling
+cckeep once            # a single pass — what the scheduler runs
+cckeep install         # register the background job
+cckeep uninstall       # remove it
+cckeep doctor          # tmux, panes, scheduler, paths
+cckeep logs            # what it has done
+```
+
+Options: `--dry-run`, `--json`, `--interval <s>`, `--lang en|ja` (auto-detected from `LANG`).
+
+## Running Claude Code in tmux
+
+cckeep reads and types into tmux panes. That is the only channel a separate process has into a live Claude Code session — and it is why the session must be started inside tmux. Restarting the process is not an alternative: it would end the conversation, which is exactly what you are trying to save.
+
+The smallest change is a shell function that wraps interactive launches only, so `claude update`, `claude doctor` and `claude -p` still behave normally:
+
+```sh
+cc() {
+  local a
+  for a in "$@"; do
+    case "$a" in
+      -p|--print|-v|--version|-h|--help|--bg|--background|--output-format) command claude "$@"; return ;;
+      agents|auth|doctor|install|mcp|plugin|project|setup-token|update|upgrade|remote-control|rc|config)
+        command claude "$@"; return ;;
+      -*) ;;
+      *) break ;;
+    esac
+  done
+  local session="claude-$(basename "$PWD")-$(printf '%s' "$PWD" | cksum | cut -d' ' -f1)"
+  if [ -n "$TMUX" ]; then command claude "$@"
+  elif tmux has-session -t "=$session" 2>/dev/null; then tmux attach-session -t "=$session"
+  else tmux new-session -s "$session" -c "$PWD" claude "$@"
+  fi
+}
+```
+
+Claude Code also needs two lines in `~/.tmux.conf`, or Shift+Enter and desktop notifications break inside tmux ([official guidance](https://code.claude.com/docs/en/terminal-config#configure-tmux)):
+
+```sh
+set -g allow-passthrough on
+set -s extended-keys on
+set -as terminal-features 'xterm*:extkeys'
+```
+
+Ctrl+B needs no fix: Claude Code detects tmux and rebinds its own shortcut to `Ctrl+B Ctrl+B`.
+
+## Configuration
+
+Defaults are tuned so you never notice it. Override in `~/.cckeep/config.json`, by environment variable, or per-run flag — later wins. A malformed config is a hard error rather than a silent half-load.
+
+```json
+{
+  "interval": 15,
+  "cooldown": 300,
+  "stuckLimit": 8,
+  "missLimit": 4,
+  "settle": 2000,
+  "paneCommand": "claude"
+}
+```
+
+- `interval` — seconds between passes (also what `install` schedules)
+- `cooldown` — seconds before the same pane may be acted on again
+- `stuckLimit` — checks in `reconnecting` before the bridge is treated as wedged
+- `missLimit` — checks with no indicator before re-arming a pane that had one
+- `settle` — milliseconds between the two captures of the idle check; raise it on a slow machine
+- `paneCommand` — foreground process name that marks a pane as Claude Code
+
+Every key has an env twin: `CCKEEP_INTERVAL`, `CCKEEP_COOLDOWN`, `CCKEEP_STUCK_LIMIT`, `CCKEEP_MISS_LIMIT`, `CCKEEP_SETTLE`, `CCKEEP_PANE_COMMAND`. `CCKEEP_HOME` moves state, config and log off `~/.cckeep`.
+
+## Scope
+
+cckeep re-arms the connection. It does **not** raise Claude Code's retry budget — that is a constant inside a closed-source binary, and only Anthropic can change it. If [#34255](https://github.com/anthropics/claude-code/issues/34255) is fixed, this tool becomes unnecessary, which is the right outcome. Until then, a 👍 there is worth more than a star here.
+
+Out of reach by design:
+
+- **Sessions outside tmux** — no channel to type into
+- **The VS Code extension** — not a terminal TUI; tmux cannot wrap it
+- **Server mode** (`claude remote-control`) — that one is a process you own, so supervise it with launchd/systemd directly, or a `while true` loop
+- **Outages past ~10 minutes** — Claude Code exits the session itself; there is nothing left to re-arm
+
+## Privacy
+
+cckeep reads the visible text of your tmux panes to decide whether a pane is connected. That text is your conversation. Therefore:
+
+- everything stays on your machine; there is no network code in this package
+- no telemetry, no account, no phone-home
+- pane text is matched against a handful of indicator strings and thrown away — only pane labels and verdicts reach the log
+- the log lives at `~/.cckeep/cckeep.log`; `cckeep logs` prints it
+
+## How it works
+
+Claude Code paints a Remote Control indicator in its footer: `/rc active` when connected, `/rc reconnecting` while retrying, and a `Remote Control disconnected` notification when it gives up. cckeep asks tmux for every pane whose foreground process is `claude`, reads those indicators out of `tmux capture-pane`, and keeps a small per-pane counter in `~/.cckeep/state.json`.
+
+The decision layer (`src/detect.js`) is a pure function of screen text plus prior state, which is why the safety rules can be tested exhaustively without a terminal. The runner (`src/run.js`) does the I/O: the idle check, the last-moment re-check, and the keystrokes.
+
+None of this is a published API — the indicator strings are UI text and can change. When they do, cckeep stops acting rather than acting wrongly: a pane it cannot read looks "never connected", and panes it has never seen connected are never touched.
+
+## Development
+
+```sh
+git clone https://github.com/kamihork/cckeep.git && cd cckeep
+npm test                       # 36 tests, no network, no tmux required
+node bin/cckeep.js doctor
+```
+
+The test suite fakes tmux, so it runs anywhere. Contributions welcome — especially indicator strings from Claude Code versions or terminals where detection misses. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © [kamihork](https://github.com/kamihork)

package/bin/cckeep.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { platform } from 'node:os';
+import { runPass } from '../src/run.js';
+import { loadConfig, configPath } from '../src/config.js';
+import { logPath, statePath, homeDir } from '../src/state.js';
+import * as tmux from '../src/tmux.js';
+import * as scheduler from '../src/scheduler.js';
+import { pickLang, strings } from '../src/i18n.js';
+
+const HELP = `cckeep — keep Claude Code Remote Control from silently going dead
+
+USAGE
+  cckeep [command] [options]
+
+COMMANDS
+  status          what cckeep sees right now (default)
+  watch           run in the foreground, one pass every --interval seconds
+  once            a single pass — what the scheduler runs
+  install         register a background job (launchd on macOS, systemd on Linux)
+  uninstall       remove it
+  doctor          check tmux, Claude Code panes, and the scheduler
+  logs            show recent actions
+
+OPTIONS
+  --interval <s>  seconds between passes (default 15)
+  --dry-run       report what would be sent, send nothing
+  --json          machine-readable output
+  --lang en|ja    output language (default: from LANG)
+  -h, --help      this text
+  -v, --version   print version
+
+Remote Control retries 5 times over ~31 seconds and then gives up for good.
+cckeep watches tmux panes running Claude Code and types /remote-control
+into the ones that went dead — never into one that is busy or showing a dialog.
+`;
+
+function parseArgs(argv) {
+  const opts = { command: null, dryRun: false, json: false, lang: null, interval: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--lang') opts.lang = argv[++i];
+    else if (a === '--interval') opts.interval = Number(argv[++i]);
+    else if (a === '-h' || a === '--help') opts.command = 'help';
+    else if (a === '-v' || a === '--version') opts.command = 'version';
+    else if (!a.startsWith('-') && !opts.command) opts.command = a;
+  }
+  return opts;
+}
+
+function version() {
+  const p = new URL('../package.json', import.meta.url);
+  return JSON.parse(readFileSync(p, 'utf8')).version;
+}
+
+const REASON_KEY = {
+  connected: 'connected',
+  retrying: 'retrying',
+  waiting: 'waiting',
+  'never-connected': 'neverConnected',
+  dialog: 'dialog',
+  cooldown: 'cooldown',
+  busy: 'busy',
+  recovered: 'recovered',
+};
+
+function describe(result, t) {
+  if (result.action === 'rearm') return `${t.rearmed} (${result.reason})`;
+  if (result.action === 'confirm-panel') return t.confirmed;
+  if (result.action === 'would-rearm') return `${t.wouldRearm} (${result.reason})`;
+  if (result.action === 'would-confirm-panel') return t.wouldConfirm;
+  return t[REASON_KEY[result.reason]] ?? result.reason;
+}
+
+function render(out, t, opts) {
+  if (opts.json) {
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+  if (out.error === 'no-tmux') return console.log(t.noTmux);
+  if (out.error === 'no-server') return console.log(t.noServer);
+  if (!out.results.length) {
+    console.log(t.noPanes);
+    console.log(t.hintOutside);
+    return;
+  }
+  for (const r of out.results) {
+    console.log(`${r.pane.padEnd(14)}${describe(r, t)}`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const lang = pickLang(opts.lang);
+  const t = strings(lang);
+
+  if (opts.command === 'help') return console.log(HELP);
+  if (opts.command === 'version') return console.log(version());
+
+  let config;
+  try {
+    config = loadConfig(opts.interval ? { interval: opts.interval } : {});
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  switch (opts.command ?? 'status') {
+    case 'status': {
+      const out = await runPass({ config, dryRun: true });
+      render(out, t, opts);
+      break;
+    }
+    case 'once': {
+      const out = await runPass({ config, dryRun: opts.dryRun });
+      render(out, t, opts);
+      break;
+    }
+    case 'watch': {
+      if (!opts.json) console.log(t.watching(config.interval));
+      for (;;) {
+        const out = await runPass({ config, dryRun: opts.dryRun });
+        for (const r of out.results) {
+          if (r.action !== 'none') console.log(`${new Date().toISOString().slice(11, 19)}  ${r.pane}  ${describe(r, t)}`);
+        }
+        await new Promise((r) => setTimeout(r, config.interval * 1000));
+      }
+    }
+    case 'install': {
+      const res = scheduler.install({ interval: config.interval });
+      if (res.kind === 'unsupported') {
+        console.log(t.unsupported);
+        process.exit(1);
+      }
+      console.log(res.ok ? t.installed(res.kind, res.path) : t.installFailed(res.kind));
+      if (!res.ok) process.exit(1);
+      break;
+    }
+    case 'uninstall': {
+      const res = scheduler.uninstall();
+      if (res.kind === 'unsupported') return console.log(t.unsupported);
+      console.log(t.uninstalled(res.kind));
+      break;
+    }
+    case 'doctor': {
+      const bin = tmux.tmuxPath();
+      const panes = bin && tmux.hasServer() ? tmux.listPanes() : [];
+      const claudePanes = panes.filter((p) => p.command === config.paneCommand);
+      const rows = [
+        ['platform', platform()],
+        ['node', process.version],
+        ['tmux', bin || t.doctorFail],
+        ['tmux server', bin && tmux.hasServer() ? t.doctorOk : t.doctorFail],
+        ['claude panes', String(claudePanes.length)],
+        ['scheduler', scheduler.isInstalled() ? t.doctorOk : t.doctorFail],
+        ['home', homeDir()],
+        ['config', existsSync(configPath()) ? configPath() : `${configPath()} (defaults)`],
+        ['state', statePath()],
+        ['log', logPath()],
+      ];
+      if (opts.json) console.log(JSON.stringify(Object.fromEntries(rows), null, 2));
+      else for (const [k, v] of rows) console.log(`${k.padEnd(14)}${v}`);
+      if (!bin) process.exitCode = 1;
+      break;
+    }
+    case 'logs': {
+      const p = logPath();
+      if (!existsSync(p)) return console.log(t.noLog);
+      const lines = readFileSync(p, 'utf8').trim().split('\n');
+      console.log(lines.slice(-40).join('\n'));
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${opts.command}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "cckeep",
+  "version": "0.1.0",
+  "description": "Keeps Claude Code Remote Control from silently going dead. Re-arms the sessions its 31-second retry budget gives up on — local, tmux-native, zero dependencies.",
+  "type": "module",
+  "bin": {
+    "cckeep": "bin/cckeep.js"
+  },
+  "main": "src/detect.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "claude-code",
+    "remote-control",
+    "tmux",
+    "watchdog",
+    "reconnect",
+    "coding-agent",
+    "agent",
+    "cli",
+    "launchd",
+    "systemd"
+  ],
+  "author": "kamihork <kmihoken@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamihork/cckeep.git"
+  },
+  "homepage": "https://github.com/kamihork/cckeep#readme",
+  "bugs": {
+    "url": "https://github.com/kamihork/cckeep/issues"
+  },
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,60 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homeDir } from './state.js';
+import { DEFAULTS } from './detect.js';
+
+export const BASE = {
+  ...DEFAULTS,
+  /** Seconds between passes in watch mode, and what `install` schedules. */
+  interval: 15,
+  /** Milliseconds between the two captures of the idle check. */
+  settle: 2000,
+  /** Milliseconds between typing the command and pressing Enter. */
+  keyDelay: 1000,
+  /** Foreground process name that marks a pane as Claude Code. */
+  paneCommand: 'claude',
+};
+
+const NUMERIC = new Set(['stuckLimit', 'missLimit', 'cooldown', 'interval', 'settle', 'keyDelay']);
+
+const ENV = {
+  CCKEEP_INTERVAL: 'interval',
+  CCKEEP_COOLDOWN: 'cooldown',
+  CCKEEP_STUCK_LIMIT: 'stuckLimit',
+  CCKEEP_MISS_LIMIT: 'missLimit',
+  CCKEEP_SETTLE: 'settle',
+  CCKEEP_KEY_DELAY: 'keyDelay',
+  CCKEEP_PANE_COMMAND: 'paneCommand',
+};
+
+export function configPath() {
+  return join(homeDir(), 'config.json');
+}
+
+/** Precedence: built-in defaults < config file < environment < CLI flags. */
+export function loadConfig(overrides = {}) {
+  let fromFile = {};
+  const p = configPath();
+  if (existsSync(p)) {
+    try {
+      fromFile = JSON.parse(readFileSync(p, 'utf8')) || {};
+    } catch (err) {
+      // Silently running with half the settings dropped is worse than stopping.
+      throw new Error(`${p} is not valid JSON: ${err.message}`);
+    }
+  }
+
+  const fromEnv = {};
+  for (const [key, name] of Object.entries(ENV)) {
+    const raw = process.env[key];
+    if (raw !== undefined && raw !== '') fromEnv[name] = raw;
+  }
+
+  const merged = { ...BASE, ...fromFile, ...fromEnv, ...overrides };
+  for (const key of NUMERIC) {
+    const value = Number(merged[key]);
+    if (!Number.isFinite(value) || value < 0) throw new Error(`config: ${key} must be a non-negative number`);
+    merged[key] = value;
+  }
+  return merged;
+}

package/src/detect.js

@@ -0,0 +1,136 @@
+// The decision core. Deliberately pure: it takes what is on screen plus what we
+// remembered about a pane, and returns what to do. No tmux, no clock, no disk —
+// so every rule below is directly testable, which matters a lot for a tool whose
+// failure mode is typing into someone's terminal at the wrong moment.
+
+/** Indicators Claude Code paints in the footer for the Remote Control link. */
+const CONNECTED = '/rc active';
+const RETRYING = '/rc reconnecting';
+const FAILED = /Remote Control disconnected|Remote Control failed|\/rc failed/;
+
+/** The /remote-control status panel — its first entry is "Disconnect this session". */
+const PANEL = /Disconnect this session|(?:Show|Hide) QR code/;
+
+/**
+ * Anything that turns Enter or a slash command into a selection: permission
+ * prompts, pickers, confirmations. Typing into one of these picks an option.
+ */
+const MODAL = /(?:❯|›)\s*(?:\d+\.|Yes|No)|Do you want|\(y\/n\)/;
+
+export const DEFAULTS = {
+  /** Consecutive checks stuck in "reconnecting" before we treat the bridge as wedged. */
+  stuckLimit: 8,
+  /** Consecutive checks with no indicator at all before re-arming a pane that had one. */
+  missLimit: 4,
+  /** Seconds before the same pane may be acted on again. */
+  cooldown: 300,
+};
+
+export function emptyState() {
+  return { seen: false, miss: 0, stuck: 0, panelPending: false, lastActionAt: 0 };
+}
+
+/**
+ * Reduce a captured pane to the handful of signals the rules care about.
+ * @param {string} screen raw `tmux capture-pane -p` output
+ */
+export function readScreen(screen) {
+  return {
+    connected: screen.includes(CONNECTED),
+    retrying: screen.includes(RETRYING),
+    failed: FAILED.test(screen),
+    panel: PANEL.test(screen),
+    modal: MODAL.test(screen),
+  };
+}
+
+/**
+ * Decide what to do with one pane.
+ *
+ * Returns `{ action, reason, state }` where action is one of:
+ *   'none'          — leave the pane alone
+ *   'confirm-panel' — press Enter on the /remote-control panel we opened, which
+ *                     selects "Disconnect this session" and tears down the
+ *                     wedged bridge so the next pass can build a fresh one
+ *   'rearm'         — type /remote-control
+ *
+ * `rearm` is a recommendation, not a green light: the caller must still confirm
+ * the pane is idle (see isIdle in run.js) before typing, because a running turn
+ * would swallow the command as a chat message.
+ */
+export function decide({ screen, state = emptyState(), now = 0, config = {} }) {
+  const cfg = { ...DEFAULTS, ...config };
+  const s = readScreen(screen);
+  const next = { ...state };
+
+  // Step two of the wedged-bridge recovery. We opened the panel on an earlier
+  // pass, so "Disconnect this session" should now be focused. Confirm it from
+  // the text actually on screen rather than by counting arrow keys — and only
+  // when we are the one who opened it, since the user may have opened the same
+  // panel to read the QR code.
+  if (next.panelPending) {
+    next.panelPending = false;
+    if (s.panel && !s.modal) {
+      next.lastActionAt = 0; // let the next pass re-arm without waiting out the cooldown
+      return { action: 'confirm-panel', reason: 'stuck-cycle', state: next };
+    }
+    // The panel never appeared: the command we sent probably reconnected
+    // directly. Fall through and judge the pane on what it shows now.
+  }
+
+  if (s.connected) {
+    next.seen = true;
+    next.miss = 0;
+    next.stuck = 0;
+    return { action: 'none', reason: 'connected', state: next };
+  }
+
+  let dead = null;
+
+  if (s.retrying) {
+    // Claude Code's own retry budget is 5 attempts over roughly 31 seconds, and
+    // a healthy reconnect resolves well inside that. Sitting in "reconnecting"
+    // far past it is the wedge from anthropics/claude-code#34255, which never
+    // recovers on its own.
+    next.stuck += 1;
+    if (next.stuck < cfg.stuckLimit) {
+      return { action: 'none', reason: 'retrying', state: next };
+    }
+    next.stuck = 0;
+    dead = 'stuck';
+  } else {
+    next.stuck = 0;
+    if (s.failed) {
+      next.miss = 0;
+      dead = 'disconnected';
+    } else if (!next.seen) {
+      // Never seen connected. Could be a session the user runs without Remote
+      // Control on purpose — not ours to switch on.
+      return { action: 'none', reason: 'never-connected', state: next };
+    } else {
+      next.miss += 1;
+      if (next.miss < cfg.missLimit) {
+        return { action: 'none', reason: 'waiting', state: next };
+      }
+      next.miss = 0;
+      dead = 'silent';
+    }
+  }
+
+  if (s.modal || s.panel) {
+    return { action: 'none', reason: 'dialog', state: next };
+  }
+
+  if (state.lastActionAt && now - state.lastActionAt < cfg.cooldown) {
+    return { action: 'none', reason: 'cooldown', state: next };
+  }
+
+  next.lastActionAt = now;
+  if (dead === 'stuck') {
+    // A wedged bridge still believes it is connecting, so /remote-control opens
+    // the status panel instead of retrying. Remember that, and finish the cycle
+    // next pass once the panel is visible.
+    next.panelPending = true;
+  }
+  return { action: 'rearm', reason: dead, state: next };
+}

package/src/i18n.js

@@ -0,0 +1,65 @@
+const en = {
+  noTmux: 'tmux not found. cckeep reads and types into tmux panes, so tmux is required.',
+  noServer: 'No tmux server is running — nothing to watch.',
+  noPanes: 'No tmux pane is running Claude Code.',
+  hintOutside: 'Claude Code started outside tmux cannot be reached: there is no way to type into it from another process.',
+  header: 'pane          state          detail',
+  connected: 'connected',
+  retrying: 'retrying',
+  waiting: 'no indicator',
+  neverConnected: 'not connected',
+  dialog: 'dialog open',
+  cooldown: 'cooling down',
+  busy: 'busy',
+  recovered: 'recovered',
+  rearmed: 're-armed',
+  confirmed: 'bridge cycled',
+  wouldRearm: 'would re-arm',
+  wouldConfirm: 'would cycle bridge',
+  watching: (n) => `Watching every ${n}s. Ctrl+C to stop.`,
+  installed: (kind, path) => `Installed (${kind}): ${path}`,
+  installFailed: (kind) => `Wrote the ${kind} unit, but could not load it. Load it manually, or run \`cckeep watch\` in a terminal.`,
+  uninstalled: (kind) => `Removed the ${kind} job.`,
+  unsupported: 'Automatic scheduling supports macOS (launchd) and Linux (systemd user timers). Elsewhere, run `cckeep watch` under your own supervisor.',
+  noLog: 'No log yet.',
+  doctorOk: 'ok',
+  doctorFail: 'missing',
+};
+
+const ja = {
+  noTmux: 'tmux が見つかりません。cckeep は tmux のペインを読んで入力するため、tmux が必須です。',
+  noServer: 'tmux サーバーが起動していません。監視対象がありません。',
+  noPanes: 'Claude Code が動いている tmux ペインがありません。',
+  hintOutside: 'tmux の外で起動した Claude Code には届きません。別プロセスから入力を送る手段がないためです。',
+  header: 'ペイン        状態           詳細',
+  connected: '接続中',
+  retrying: '再試行中',
+  waiting: '表示なし',
+  neverConnected: '未接続',
+  dialog: 'ダイアログ表示中',
+  cooldown: 'クールダウン中',
+  busy: '実行中',
+  recovered: '復帰済み',
+  rearmed: '再接続を送信',
+  confirmed: 'ブリッジを張り直し',
+  wouldRearm: '再接続を送信する',
+  wouldConfirm: 'ブリッジを張り直す',
+  watching: (n) => `${n} 秒ごとに監視します。Ctrl+C で停止。`,
+  installed: (kind, path) => `登録しました (${kind}): ${path}`,
+  installFailed: (kind) => `${kind} の定義は書きましたが、読み込みに失敗しました。手動で読み込むか、ターミナルで \`cckeep watch\` を実行してください。`,
+  uninstalled: (kind) => `${kind} のジョブを削除しました。`,
+  unsupported: '自動スケジュール登録は macOS (launchd) と Linux (systemd user timer) に対応しています。それ以外では `cckeep watch` を任意の常駐手段で動かしてください。',
+  noLog: 'ログはまだありません。',
+  doctorOk: 'ok',
+  doctorFail: '未検出',
+};
+
+export function pickLang(explicit) {
+  if (explicit === 'en' || explicit === 'ja') return explicit;
+  const env = process.env.CCKEEP_LANG || process.env.LC_ALL || process.env.LANG || '';
+  return /^ja/i.test(env) ? 'ja' : 'en';
+}
+
+export function strings(lang) {
+  return lang === 'ja' ? ja : en;
+}

package/src/run.js

@@ -0,0 +1,98 @@
+import { decide, readScreen } from './detect.js';
+import * as realTmux from './tmux.js';
+import { loadState, saveState, forPane, prune, appendLog } from './state.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Is the pane quiet enough to type into?
+ *
+ * A running turn animates a spinner and a token counter, so two byte-identical
+ * captures a couple of seconds apart is a cheap and reliable "nothing is
+ * happening here" signal — and it needs no knowledge of Claude Code's changing
+ * status-line wording.
+ */
+export async function isIdle(tmux, paneId, settle) {
+  const a = tmux.capture(paneId);
+  await sleep(settle);
+  const b = tmux.capture(paneId);
+  return a.length > 0 && a === b;
+}
+
+/**
+ * One pass over every tmux pane running Claude Code.
+ *
+ * @returns {Promise<{results: Array, acted: number}>} one result per candidate
+ *          pane, for the CLI to render. Nothing is written when dryRun is set.
+ */
+export async function runPass({ tmux = realTmux, config, dryRun = false, now = Math.floor(Date.now() / 1000) } = {}) {
+  const results = [];
+  if (!tmux.tmuxPath()) return { results, acted: 0, error: 'no-tmux' };
+  if (!tmux.hasServer()) return { results, acted: 0, error: 'no-server' };
+
+  const panes = tmux.listPanes();
+  const state = loadState();
+  let acted = 0;
+
+  for (const pane of panes) {
+    if (pane.command !== config.paneCommand) continue;
+
+    const screen = tmux.capture(pane.id);
+    if (!screen) continue;
+
+    const before = forPane(state, pane.id);
+    const { action, reason, state: after } = decide({ screen, state: before, now, config });
+    state[pane.id] = after;
+
+    const result = { pane: pane.label, id: pane.id, action, reason, signals: readScreen(screen) };
+
+    if (action === 'none') {
+      results.push(result);
+      continue;
+    }
+
+    if (dryRun) {
+      result.action = `would-${action}`;
+      results.push(result);
+      continue;
+    }
+
+    if (action === 'confirm-panel') {
+      tmux.sendEnter(pane.id);
+      appendLog(`${pane.label}: closing wedged bridge via panel`);
+      acted += 1;
+      results.push(result);
+      continue;
+    }
+
+    // action === 'rearm'. The decision was made from a single capture; make
+    // sure nothing has started running in the meantime before typing.
+    if (!(await isIdle(tmux, pane.id, config.settle))) {
+      result.action = 'none';
+      result.reason = 'busy';
+      state[pane.id] = { ...after, lastActionAt: before.lastActionAt, panelPending: before.panelPending };
+      results.push(result);
+      continue;
+    }
+
+    // Re-read: the pane may have reconnected or opened a dialog while we waited.
+    const recheck = readScreen(tmux.capture(pane.id));
+    if (recheck.connected || recheck.modal || recheck.panel) {
+      result.action = 'none';
+      result.reason = recheck.connected ? 'recovered' : 'dialog';
+      state[pane.id] = { ...after, lastActionAt: before.lastActionAt, panelPending: before.panelPending };
+      results.push(result);
+      continue;
+    }
+
+    tmux.sendText(pane.id, '/remote-control');
+    await sleep(config.keyDelay ?? 1000);
+    tmux.sendEnter(pane.id);
+    appendLog(`${pane.label}: re-arming Remote Control (${reason})`);
+    acted += 1;
+    results.push(result);
+  }
+
+  if (!dryRun) saveState(prune(state, panes.map((p) => p.id)));
+  return { results, acted };
+}

package/src/scheduler.js

@@ -0,0 +1,134 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const LABEL = 'io.github.kamihork.cckeep';
+
+function cliPath() {
+  return fileURLToPath(new URL('../bin/cckeep.js', import.meta.url));
+}
+
+function nodePath() {
+  return process.execPath;
+}
+
+export function plistPath() {
+  return join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+export function systemdDir() {
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'systemd', 'user');
+}
+
+export function renderPlist({ interval, node = nodePath(), cli = cliPath(), home }) {
+  const env = home
+    ? `    <key>EnvironmentVariables</key>\n    <dict>\n        <key>CCKEEP_HOME</key>\n        <string>${home}</string>\n    </dict>\n`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${node}</string>
+        <string>${cli}</string>
+        <string>once</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>${interval}</integer>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>ProcessType</key>
+    <string>Background</string>
+${env}</dict>
+</plist>
+`;
+}
+
+export function renderSystemdService({ node = nodePath(), cli = cliPath() }) {
+  return `[Unit]
+Description=cckeep — keep Claude Code Remote Control alive
+
+[Service]
+Type=oneshot
+ExecStart=${node} ${cli} once
+`;
+}
+
+export function renderSystemdTimer({ interval }) {
+  return `[Unit]
+Description=cckeep — keep Claude Code Remote Control alive
+
+[Timer]
+OnBootSec=${interval}s
+OnUnitActiveSec=${interval}s
+AccuracySec=1s
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+function run(cmd, args) {
+  try {
+    execFileSync(cmd, args, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function install({ interval }) {
+  const os = platform();
+  if (os === 'darwin') {
+    const p = plistPath();
+    mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
+    writeFileSync(p, renderPlist({ interval, home: process.env.CCKEEP_HOME }));
+    const uid = process.getuid();
+    run('launchctl', ['bootout', `gui/${uid}/${LABEL}`]);
+    const ok = run('launchctl', ['bootstrap', `gui/${uid}`, p]);
+    return { kind: 'launchd', path: p, ok };
+  }
+  if (os === 'linux') {
+    const dir = systemdDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'cckeep.service'), renderSystemdService({}));
+    writeFileSync(join(dir, 'cckeep.timer'), renderSystemdTimer({ interval }));
+    run('systemctl', ['--user', 'daemon-reload']);
+    const ok = run('systemctl', ['--user', 'enable', '--now', 'cckeep.timer']);
+    return { kind: 'systemd', path: dir, ok };
+  }
+  return { kind: 'unsupported', path: null, ok: false };
+}
+
+export function uninstall() {
+  const os = platform();
+  if (os === 'darwin') {
+    const p = plistPath();
+    run('launchctl', ['bootout', `gui/${process.getuid()}/${LABEL}`]);
+    if (existsSync(p)) unlinkSync(p);
+    return { kind: 'launchd', path: p, ok: true };
+  }
+  if (os === 'linux') {
+    const dir = systemdDir();
+    run('systemctl', ['--user', 'disable', '--now', 'cckeep.timer']);
+    for (const f of ['cckeep.timer', 'cckeep.service']) {
+      const p = join(dir, f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+    run('systemctl', ['--user', 'daemon-reload']);
+    return { kind: 'systemd', path: dir, ok: true };
+  }
+  return { kind: 'unsupported', path: null, ok: false };
+}
+
+export function isInstalled() {
+  const os = platform();
+  if (os === 'darwin') return existsSync(plistPath());
+  if (os === 'linux') return existsSync(join(systemdDir(), 'cckeep.timer'));
+  return false;
+}

package/src/state.js

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { emptyState } from './detect.js';
+
+export function homeDir() {
+  return process.env.CCKEEP_HOME || join(homedir(), '.cckeep');
+}
+
+export function statePath() {
+  return join(homeDir(), 'state.json');
+}
+
+export function logPath() {
+  return join(homeDir(), 'cckeep.log');
+}
+
+export function loadState() {
+  const p = statePath();
+  if (!existsSync(p)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    // A corrupt state file must never stop the watchdog: the worst it costs is
+    // one forgotten pane, and every counter rebuilds within a few passes.
+    return {};
+  }
+}
+
+export function saveState(state) {
+  const p = statePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(state, null, 2));
+}
+
+export function forPane(state, paneId) {
+  return { ...emptyState(), ...(state[paneId] || {}) };
+}
+
+/** Forget panes that no longer exist, so state.json cannot grow without bound. */
+export function prune(state, livePaneIds) {
+  const live = new Set(livePaneIds);
+  const out = {};
+  for (const [id, value] of Object.entries(state)) if (live.has(id)) out[id] = value;
+  return out;
+}
+
+export function appendLog(line) {
+  try {
+    const p = logPath();
+    mkdirSync(dirname(p), { recursive: true });
+    const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    writeFileSync(p, `[${stamp}] ${line}\n`, { flag: 'a' });
+  } catch {}
+}

package/src/tmux.js

@@ -0,0 +1,70 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+// Schedulers run with a minimal PATH — cron notoriously omits /opt/homebrew/bin,
+// and launchd is no better. Resolving tmux to an absolute path here is what
+// keeps a scheduled run from silently finding nothing to do.
+const CANDIDATES = [
+  '/opt/homebrew/bin/tmux',
+  '/usr/local/bin/tmux',
+  '/usr/bin/tmux',
+  '/bin/tmux',
+  '/opt/local/bin/tmux',
+  '/home/linuxbrew/.linuxbrew/bin/tmux',
+];
+
+let cached;
+
+export function tmuxPath() {
+  if (cached) return cached;
+  const fromEnv = process.env.CCKEEP_TMUX;
+  if (fromEnv && existsSync(fromEnv)) return (cached = fromEnv);
+  for (const p of CANDIDATES) if (existsSync(p)) return (cached = p);
+  try {
+    const found = execFileSync('command', ['-v', 'tmux'], { shell: true, encoding: 'utf8' }).trim();
+    if (found && existsSync(found)) return (cached = found);
+  } catch {}
+  return null;
+}
+
+function tmux(args, { allowFail = true } = {}) {
+  const bin = tmuxPath();
+  if (!bin) return null;
+  try {
+    return execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (err) {
+    if (allowFail) return null;
+    throw err;
+  }
+}
+
+export function hasServer() {
+  return tmux(['has-session']) !== null;
+}
+
+/** Every pane on the server, with the process currently in the foreground. */
+export function listPanes() {
+  const out = tmux(['list-panes', '-a', '-F', '#{pane_id}\t#{pane_current_command}\t#{session_name}\t#{window_index}\t#{pane_index}']);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [id, command, session, windowIndex, paneIndex] = line.split('\t');
+      return { id, command, session, windowIndex, paneIndex, label: `${session}:${windowIndex}.${paneIndex}` };
+    });
+}
+
+export function capture(paneId) {
+  return tmux(['capture-pane', '-p', '-t', paneId]) ?? '';
+}
+
+export function sendText(paneId, text) {
+  // -l sends the string literally, so a pane in some unexpected mode cannot
+  // reinterpret it as a key name.
+  tmux(['send-keys', '-l', '-t', paneId, text]);
+}
+
+export function sendEnter(paneId) {
+  tmux(['send-keys', '-t', paneId, 'Enter']);
+}