cloudcli-claude-watch

日本語版は下にあります / Japanese version below.

A CloudCLI UI plugin that wraps @satsuki0710624/claude-watch to surface hang detection as a tab inside CloudCLI UI (siteboon/claudecodeui).

Heads-up — terminology. "Plugin" in this repository always means a CloudCLI UI plugin (the manifest.json + mount/unmount + subprocess system shipped by siteboon/claudecodeui). It is not Anthropic's official Claude Code Plugin (.claude-plugin/plugin.json, skills / agents / hooks / commands). The two systems share a name but are otherwise unrelated.

What it does

claude-watch already exists as a host-app-agnostic npm package that reads a watchdog log, surfaces stall events through an Express router, and provides React components for the UI. cloudcli-claude-watch is a thin adapter that fits this into the CloudCLI UI plugin contract:

• the plugin's compiled backend (dist/server.js) is spawned by the CloudCLI host as a subprocess, brings up an Express app with createRouter({ monitor }) mounted inside, and emits the {"ready": true, "port": <int>} readiness line on stdout;
• the plugin's compiled frontend (dist/index.js) renders inside a CloudCLI tab via mount(container, api) and reaches the backend through api.rpc('GET', '/status') (and the kill route).

The original claude-watch package is consumed as an unmodified npm dependency; this repository contains only the adapter glue.

The tab renders the stall list with cmdline / cwd / uid / started / git panels and SIGTERM / SIGKILL buttons; see the full screenshot set for the empty state, the SIGTERM confirm dialog, and the in-project highlight.

Status

1.0.0 — Phase 4 published & dogfooded. All adapter glue (backend subprocess, frontend tab, stall list, expand / SIGTERM / SIGKILL, theme follow, in-project highlight) is implemented and covered end-to-end by the smoke harness (npm run smoke). Session 6 closed the dogfooding gap: the plugin was installed into a local siteboon/claudecodeui (v1.31.5) checkout via Settings → Plugins, the stall row → expand → SIGTERM → in-project highlight flow was confirmed in the browser, and the screenshots under docs/screenshots/ are real captures from that run.

Install

1. Open CloudCLI UI and go to Settings → Plugins.
2. Paste the git URL of this repository:

   https://github.com/satsuki19980613/cloudcli-claude-watch.git
   

   CloudCLI will git clone it under ~/.claude-code-ui/plugins/, run npm install --ignore-scripts, run npm run build, and spawn dist/server.js as the plugin backend.
3. Enable the plugin. A "Claude Watch" tab appears.

Prerequisites

• CloudCLI UI ≥ a version that supports the manifest.json plugin contract (any recent siteboon/claudecodeui main). The plugin expects slot: "tab" and type: "module".
• A working watchdog log at ~/.claude/watchdog.log (see "logPath" below). The file may be empty or absent at start — the backend will poll it and surface stalls as the watchdog appends events.
• Linux. The underlying claude-watch package reads /proc/<pid>/* and sends Unix signals; macOS / Windows are not supported.

logPath — currently hard-coded

The plugin's backend monitors ~/.claude/watchdog.log unconditionally. There is no userConfig / Settings field for the path yet because the CloudCLI manifest schema for user-supplied config has not been confirmed (see docs/open-questions.md Q4 and docs/design-decisions.md D2). If your watchdog writes elsewhere, symlink it:

mkdir -p ~/.claude
ln -s /actual/path/to/watchdog.log ~/.claude/watchdog.log

CW_LOGPATH env var also works, but CloudCLI strips env on subprocess spawn, so it only takes effect in local development / smoke runs (docs/design-decisions.md D4).

Verifying it works

After enabling the plugin and clicking the "Claude Watch" tab:

• An empty state (No active stalls.) is normal when the log has no recent stall blocks.
• Append a stall block to the log to test:

  cat >> ~/.claude/watchdog.log <<'EOF'
  
  2026-01-01T00:00:00Z ALERT: Stale session detected
  session_jsonl: /tmp/session.jsonl
  last_update: 2026-01-01T00:00:00Z (10m stale)
  pid: <some_running_pid_you_can_kill>
  
  EOF

• Within a few seconds the tab shows a row for pid <pid>. Click it to expand cmdline / cwd / uid / started / git, then click SIGTERM or SIGKILL. The row disappears on the next poll.

How it relates to claude-watch

Layer	claude-watch	cloudcli-claude-watch
Watchdog log tailing	Yes (createMonitor)	re-uses upstream
Express routes	Yes (createRouter)	re-uses upstream
React UI components	Yes (HangBanner etc.)	not used — DOM rendered inline (D3 / D5)
Host integration	Generic Express + React	CloudCLI Plugin (manifest.json + mount/unmount + subprocess)

claude-watch is consumed as @satsuki0710624/claude-watch@^1.0.1. Major upstream bumps will require a coordinated major bump here.

Maintainer notes

This repository does not ship a CLAUDE.md. Claude Code session policy (Japanese chat, session bookkeeping) lives in the maintainer's auto-memory and the Session N start/end prompts under docs/; the project-level CLAUDE.md found in the parent claude-watch repository is not duplicated here on purpose (see docs/open-questions.md Q7, resolved as "no" in Session 5).

License

MIT — see LICENSE. claude-watch itself is also MIT. CloudCLI UI is AGPL-3.0-or-later; this plugin does not modify CloudCLI UI source, it only attaches via the published plugin contract, so the MIT license stands on its own. Users who self-host a modified CloudCLI UI must follow AGPL on their side.

---

cloudcli-claude-watch (日本語)

CloudCLI UI (siteboon/claudecodeui) の plugin として、汎用ハング検知プラグイン @satsuki0710624/claude-watch を tab 形式で表示するための薄いアダプタ。

用語注意。 本リポジトリで「plugin」と書く場合は常に CloudCLI UI plugin (manifest.json + mount/unmount + subprocess の仕組み) を指す。 Anthropic 公式の Claude Code Plugin (.claude-plugin/plugin.json を 持つ skills / agents / hooks / commands エコシステム) とは名前が衝突して いるだけで別物。

概要

claude-watch は既に「watchdog log を読む → Express router で公開 → React コンポーネントで描画」という形で host-app-agnostic な npm パッケージ として完成している。cloudcli-claude-watch はその設計を CloudCLI UI の plugin contract に合わせるアダプタ層に徹する:

• compile 後の backend (dist/server.js) は CloudCLI host が subprocess として起動し、その中で Express app を立てて createRouter({ monitor }) を mount、stdout に {"ready": true, "port": <int>} を出す;
• compile 後の frontend (dist/index.js) は CloudCLI tab の中で mount(container, api) から起動し、api.rpc('GET','/status') 等で backend を叩いて stall を描画する。

claude-watch 本体は npm 依存として 無修正 で取り込み、本リポジトリは アダプタ層のみを持つ。

tab は stall リスト + cmdline / cwd / uid / started / git パネル + SIGTERM / SIGKILL ボタンを描画する。空状態 / SIGTERM 確認 ダイアログ / in-project 強調 を含む全画面集は docs/screenshots/ 参照。

ステータス

1.0.0 — Phase 4 公開済み & dogfood 済み。 アダプタの全実装 (backend subprocess、frontend tab、stall リスト表示、行展開、 SIGTERM / SIGKILL、theme 追随、project 内 stall 強調) が完了し、 npm run smoke で end-to-end 検証済み。Session 6 で実際の siteboon/claudecodeui (v1.31.5) に Settings → Plugins 経由で install し、ブラウザ上で stall 行→展開→SIGTERM→in-project 強調 の 全フローを確認済み。docs/screenshots/ 配下の画像は (mockup ではなく) その実機キャプチャ。

インストール

1. CloudCLI UI を起動し、Settings → Plugins を開く。
2. 本リポジトリの git URL を貼り付ける:

   https://github.com/satsuki19980613/cloudcli-claude-watch.git
   

   CloudCLI が ~/.claude-code-ui/plugins/ 配下に git clone し、 npm install --ignore-scripts → npm run build を回し、 dist/server.js を backend subprocess として spawn する。
3. Enable すると「Claude Watch」タブが現れる。

前提

• CloudCLI UI は manifest.json plugin contract に対応したバージョン (= siteboon/claudecodeui の最近の main)。本 plugin は slot: "tab" / type: "module" を前提。
• watchdog log が ~/.claude/watchdog.log に存在すること (下記の 「logPath」参照)。空ファイル / 未作成でも backend は poll し続け、 watchdog が append した時点で stall が tab に現れる。
• Linux 限定。claude-watch 本体が /proc/<pid>/* 読み取りと Unix signal 送信に依存しているため、macOS / Windows は非対応。

logPath — 現状はハードコード

backend は ~/.claude/watchdog.log を 無条件に 監視する。 userConfig / Settings 経由でパスを差し替える仕組みは未実装で、 CloudCLI の userConfig schema が確定していないことが理由 (docs/open-questions.md Q4 / docs/design-decisions.md D2)。 別の場所に watchdog log を書いている場合はシンボリックリンクで ごまかす:

mkdir -p ~/.claude
ln -s /actual/path/to/watchdog.log ~/.claude/watchdog.log

CW_LOGPATH env による上書きも実装されているが、CloudCLI host は subprocess の env を whitelist するため、これは smoke / ローカル開発時 専用 (docs/design-decisions.md D4)。

動作確認

「Claude Watch」タブをクリックして:

• log に最近の stall ブロックが無ければ No active stalls. の空状態が 正常。
• 動作確認には stall ブロックを log に追記する:

  cat >> ~/.claude/watchdog.log <<'EOF'
  
  2026-01-01T00:00:00Z ALERT: Stale session detected
  session_jsonl: /tmp/session.jsonl
  last_update: 2026-01-01T00:00:00Z (10m stale)
  pid: <kill して問題ない PID>
  
  EOF

• 数秒以内に pid <pid> の行が現れる。行をクリックすると cmdline / cwd / uid / started / git が展開される。 SIGTERM / SIGKILL ボタンで kill すれば、次の polling tick で 行が消える。

claude-watch 本体との関係

レイヤ	claude-watch	cloudcli-claude-watch
watchdog log tail	あり (createMonitor)	上流をそのまま利用
Express ルート	あり (createRouter)	上流をそのまま利用
React UI 部品	あり (HangBanner 等)	未使用 — 自前 DOM で描画 (D3 / D5)
ホスト統合	汎用 Express + React	CloudCLI Plugin (manifest.json + mount/unmount + subprocess)

claude-watch は @satsuki0710624/claude-watch@^1.0.1 として依存。 上流の major bump 時は本リポジトリも major bump で追従する。

メンテナノート

本リポジトリには CLAUDE.md を 置かない。Claude Code セッション ポリシー (日本語チャット、セッション運用ルール) はメンテナ側の auto-memory と docs/next-session-prompt.md に分散させており、 親リポジトリ claude-watch の CLAUDE.md は意図的に複製していない (docs/open-questions.md Q7、Session 5 で 「持たない」確定)。

ライセンス

MIT — LICENSE 参照。claude-watch 本体も MIT。CloudCLI UI は AGPL-3.0-or-later だが、本プラグインは CloudCLI UI のソースを変更 せず公開 plugin contract から接続するだけなので、本リポジトリの MIT ライセンスは独立して維持される。CloudCLI UI 本体を改変して self-host する場合、その改変側は AGPL に従う必要がある (本プロジェクトの責務外)。