claude-watch

日本語版は README.ja.md を参照。

A drop-in hang detection plugin for Node.js + React web apps on Linux.

claude-watch reads a watchdog log — an append-only file written by some external process supervisor — extracts stall events from it, and surfaces them through:

• a small Express router (/status, /process/:pid, /git/:pid, /kill/:pid) you mount inside your host app, and
• a few React components + a useHangDetector hook for the UI.

The package is host-app-agnostic. It does not assume any particular product; it only assumes:

1. Some watchdog writes stall events to a log file using a documented block format (configurable schema with a sensible default).
2. The web app runs on the same Linux host as the monitored processes (claude-watch reads /proc/<pid>/* and sends Unix signals).
3. The host app handles authentication and authorisation for the mounted routes. claude-watch enforces only one rule: a kill request is rejected unless the target PID is owned by the same Unix user as the Node process running claude-watch.

License: MIT.

Why this exists

Long-running CLI tools occasionally hang in ways the user notices only minutes after the process becomes unresponsive. If a separate watchdog is already monitoring the tool and writing detection events to a log, the log itself is enough signal to recover — what is missing is a user- facing surface that turns "the log says there's a stall" into "I can see the bad PID and kill it from my browser."

claude-watch is that surface, written as a plugin so any Node + React project can adopt it without restructuring.

Quick start

Install. The npm package is published under a scoped name (the unscoped claude-watch was rejected by npm's typosquatting protection — see docs/design-decisions.md D14):

npm install @satsuki0710624/claude-watch express
# GitHub URL form also works:
# npm install github:satsuki19980613/claude-watch express

Backend (Express host)

import express from 'express';
import {
  createMonitor,
  createRouter,
} from '@satsuki0710624/claude-watch/backend';

const app = express();
app.use(express.json());

const monitor = createMonitor({
  logPath: '/home/me/.cache/some-watchdog/events.log',
  pollInterval: 5000,
});

monitor.on('stall-detected', (event) => {
  console.warn('stall', event);
});

monitor.start();

app.use('/api/hang', createRouter({ monitor }));
app.listen(3000);

Frontend (React host)

import {
  HangBanner,
  useHangDetector,
} from '@satsuki0710624/claude-watch/frontend';

export function App() {
  const { stalls } = useHangDetector({
    endpoint: '/api/hang/status',
    pollInterval: 5000,
  });

  return (
    <>
      <HangBanner stalls={stalls} />
      {/* rest of your app */}
    </>
  );
}

The components are shipped as JSX source under src/frontend/. Your bundler (Vite, webpack + babel-loader, esbuild, etc.) must be able to transform JSX — i.e. the same setup any React app already has.

Try it end-to-end

A minimal runnable example is checked into the repo at examples/host-app/ — an Express + Vite + React host that mounts the plugin, with a README walking through both the full UI flow and a curl-only path. Useful for trying out the plugin end-to-end before integrating it into a real host.

Watchdog log format

Default schema, parsed line-block by line-block:

<ISO8601 timestamp> ALERT: Stale session detected
session_jsonl: <absolute path>
last_update: <ISO8601 timestamp> (<integer>m stale)
pid: <integer>

The header line (ALERT: Stale session detected) is the parser's anchor; the three lines that follow it are the event body. The schema is configurable — see docs/api-spec.md for the full parser configuration.

What this package does NOT do

• It does not kill processes automatically. Termination is always user-driven through the UI (kill button → confirmation dialog → signal).
• It does not authenticate requests. The host app is responsible for protecting the mounted routes (session middleware, auth proxy, etc.).
• It does not restart the killed process or "self-heal" in any way. Recovery is whatever your host workflow does after kill.
• It does not write to the watchdog log. It is read-only against that file.

These exclusions are deliberate. See docs/design-decisions.md for the rationale.

Status

1.0 — first stable release. Backend, frontend, tests, CI, and docs are complete; the mounted Express router and the React components are treated as a stable surface from this version onwards. Suitable for a host app that already has authentication and is run by a single Unix user.

Breaking changes from 1.0.0 follow Semantic Versioning — a major version bump rather than a minor release. See CHANGELOG.md and §9 of docs/implementation-plan.md for the release policy and the readiness criteria that were met.

The corresponding npm publish may not yet have landed at the moment you read this; if npm view @satsuki0710624/claude-watch still 404s, install via the GitHub URL form shown above (see docs/open-questions.md Q6).

Project layout

src/
  backend/      Node.js modules (Express router factory, log monitor, /proc reader, kill handler)
  frontend/    React components + useHangDetector hook
tests/         node:test unit tests for backend modules
docs/          api-spec.md, integration-guide.md, design-decisions.md

Contributing

This is an early-stage project. Issues and PRs welcome on the GitHub repository.

License

MIT — see LICENSE.