@atercates/claude-deck 0.2.3 → 0.2.4

package/lib/claude/watcher.ts

@@ -3,6 +3,8 @@ import path from "path";
 import os from "os";
 import { WebSocket } from "ws";
 import { invalidateProject, invalidateAll } from "./jsonl-cache";
+import { onStateFileChange, invalidateSessionName } from "../status-monitor";
+import { STATES_DIR } from "../hooks/setup";
 
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
 
@@ -13,7 +15,7 @@ export function addUpdateClient(ws: WebSocket): void {
   ws.on("close", () => updateClients.delete(ws));
 }
 
-function broadcast(msg: object): void {
+export function broadcast(msg: object): void {
   const data = JSON.stringify(msg);
   for (const ws of updateClients) {
     if (ws.readyState === WebSocket.OPEN) {
@@ -44,14 +46,21 @@ function handleFileChange(filePath: string): void {
 
 export function startWatcher(): void {
   try {
-    const watcher = watch(CLAUDE_PROJECTS_DIR, {
+    // Watch Claude projects for session list updates
+    const projectsWatcher = watch(CLAUDE_PROJECTS_DIR, {
       ignoreInitial: true,
       depth: 2,
       ignored: [/node_modules/, /\.git/, /subagents/],
     });
 
-    watcher.on("change", handleFileChange);
-    watcher.on("add", (fp) => {
+    projectsWatcher.on("change", (fp) => {
+      handleFileChange(fp);
+      if (fp.endsWith(".jsonl")) {
+        const sessionId = path.basename(fp, ".jsonl");
+        invalidateSessionName(sessionId);
+      }
+    });
+    projectsWatcher.on("add", (fp) => {
       handleFileChange(fp);
       const relative = path.relative(CLAUDE_PROJECTS_DIR, fp);
       if (!relative.includes(path.sep)) {
@@ -59,12 +68,26 @@ export function startWatcher(): void {
         broadcast({ type: "projects-changed" });
       }
     });
-    watcher.on("addDir", () => {
+    projectsWatcher.on("addDir", () => {
       invalidateAll();
       broadcast({ type: "projects-changed" });
     });
 
     console.log("> File watcher started on ~/.claude/projects/");
+
+    // Watch session state files written by hooks
+    const statesWatcher = watch(STATES_DIR, {
+      ignoreInitial: true,
+      depth: 0,
+    });
+
+    statesWatcher.on("change", onStateFileChange);
+    statesWatcher.on("add", onStateFileChange);
+    statesWatcher.on("unlink", onStateFileChange);
+
+    console.log(
+      "> State file watcher started on ~/.claude-deck/session-states/"
+    );
   } catch (err) {
     console.error("Failed to start file watcher:", err);
   }

package/lib/hooks/reporter.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook reporter.
+ *
+ * Invoked by Claude Code hooks on state transitions. Reads JSON from stdin
+ * and writes a session state file to ~/.claude-deck/session-states/{session_id}.json.
+ *
+ * Installed to ~/.claude-deck/hooks/state-reporter by the setup module.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const STATES_DIR = path.join(os.homedir(), ".claude-deck", "session-states");
+
+interface HookInput {
+  session_id: string;
+  hook_event_name: string;
+  tool_name?: string;
+  tool_input?: unknown;
+  last_assistant_message?: string;
+  stop_hook_active?: boolean;
+  reason?: string;
+}
+
+interface StateFile {
+  status: "running" | "waiting" | "idle";
+  lastLine: string;
+  waitingContext?: string;
+  ts: number;
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => resolve(data));
+    // Safety timeout — don't hang if stdin never closes
+    setTimeout(() => resolve(data), 1000);
+  });
+}
+
+function getStatePath(sessionId: string): string {
+  return path.join(STATES_DIR, `${sessionId}.json`);
+}
+
+function writeState(sessionId: string, state: StateFile): void {
+  fs.mkdirSync(STATES_DIR, { recursive: true });
+  fs.writeFileSync(getStatePath(sessionId), JSON.stringify(state));
+}
+
+function deleteState(sessionId: string): void {
+  try {
+    fs.unlinkSync(getStatePath(sessionId));
+  } catch {
+    // file may not exist
+  }
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  if (!raw.trim()) return;
+
+  let input: HookInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const { session_id, hook_event_name } = input;
+  if (!session_id) return;
+
+  switch (hook_event_name) {
+    case "SessionEnd":
+      deleteState(session_id);
+      break;
+
+    case "PermissionRequest":
+      writeState(session_id, {
+        status: "waiting",
+        lastLine: `Waiting: ${input.tool_name || "permission"}`,
+        waitingContext: input.tool_name
+          ? `Permission requested for ${input.tool_name}`
+          : "Permission requested",
+        ts: Date.now(),
+      });
+      break;
+
+    case "Stop":
+      // Only transition to idle if not in a stop-hook re-run loop
+      if (!input.stop_hook_active) {
+        writeState(session_id, {
+          status: "idle",
+          lastLine: input.last_assistant_message?.slice(0, 200) || "",
+          ts: Date.now(),
+        });
+      }
+      break;
+
+    default:
+      // UserPromptSubmit, SessionStart, PreToolUse, PostToolUse, PermissionDenied
+      writeState(session_id, {
+        status: "running",
+        lastLine: input.tool_name
+          ? `Running: ${input.tool_name}`
+          : "Running...",
+        ts: Date.now(),
+      });
+      break;
+  }
+}
+
+main().catch(() => process.exit(0));

package/lib/hooks/setup.ts

@@ -0,0 +1,164 @@
+/**
+ * Hooks setup module.
+ *
+ * Installs the state-reporter script to ~/.claude-deck/hooks/ and
+ * merges hook configuration into ~/.claude/settings.json idempotently.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const CLAUDE_DECK_DIR = path.join(os.homedir(), ".claude-deck");
+const HOOKS_DIR = path.join(CLAUDE_DECK_DIR, "hooks");
+const STATES_DIR = path.join(CLAUDE_DECK_DIR, "session-states");
+const REPORTER_PATH = path.join(HOOKS_DIR, "state-reporter");
+const SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+
+// Events we hook into and whether they run async
+const HOOK_EVENTS: Array<{ event: string; async: boolean }> = [
+  { event: "UserPromptSubmit", async: true },
+  { event: "PreToolUse", async: true },
+  { event: "PermissionRequest", async: false },
+  { event: "Elicitation", async: false },
+  { event: "Stop", async: true },
+  { event: "SessionStart", async: true },
+  { event: "SessionEnd", async: true },
+];
+
+// The reporter is a self-contained Node.js script (no tsx, no ESM, no deps)
+const REPORTER_SCRIPT = `#!/usr/bin/env node
+"use strict";
+var fs = require("fs");
+var path = require("path");
+var os = require("os");
+var STATES_DIR = path.join(os.homedir(), ".claude-deck", "session-states");
+
+var data = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", function(c) { data += c; });
+process.stdin.on("end", function() {
+  try {
+    var input = JSON.parse(data);
+    var id = input.session_id;
+    if (!id) return;
+    fs.mkdirSync(STATES_DIR, { recursive: true });
+    var fp = path.join(STATES_DIR, id + ".json");
+    var evt = input.hook_event_name;
+
+    if (evt === "SessionEnd") {
+      try { fs.unlinkSync(fp); } catch(e) {}
+      return;
+    }
+
+    var status = "running";
+    var lastLine = input.tool_name ? "Running: " + input.tool_name : "Running...";
+    var state = { status: status, lastLine: lastLine, ts: Date.now() };
+
+    if (evt === "SessionStart") {
+      state.status = "idle";
+      state.lastLine = "";
+    } else if (evt === "PermissionRequest" || evt === "Elicitation") {
+      state.status = "waiting";
+      state.lastLine = "Waiting: " + (input.tool_name || "input required");
+      state.waitingContext = input.tool_name
+        ? "Permission requested for " + input.tool_name
+        : "Input required";
+    } else if (evt === "Stop" && !input.stop_hook_active) {
+      state.status = "idle";
+      state.lastLine = (input.last_assistant_message || "").slice(0, 200);
+    }
+
+    fs.writeFileSync(fp, JSON.stringify(state));
+  } catch(e) {}
+});
+setTimeout(function() { process.exit(0); }, 2000);
+`;
+
+function installReporterScript(): void {
+  fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  fs.mkdirSync(STATES_DIR, { recursive: true });
+  fs.writeFileSync(REPORTER_PATH, REPORTER_SCRIPT, { mode: 0o755 });
+}
+
+interface HookCommand {
+  type: "command";
+  command: string;
+  async?: boolean;
+}
+
+interface HookMatcher {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+
+type SettingsHooks = Record<string, HookMatcher[]>;
+
+interface Settings {
+  hooks?: SettingsHooks;
+  [key: string]: unknown;
+}
+
+function isOurHook(hook: HookCommand): boolean {
+  return hook.command === REPORTER_PATH;
+}
+
+function mergeHooksIntoSettings(): void {
+  let settings: Settings = {};
+
+  try {
+    const raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+    settings = JSON.parse(raw);
+  } catch {
+    // File doesn't exist or is invalid
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  let changed = false;
+
+  for (const { event, async: isAsync } of HOOK_EVENTS) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    const eventHooks = settings.hooks[event];
+    const alreadyInstalled = eventHooks.some((matcher) =>
+      matcher.hooks?.some((h) => isOurHook(h))
+    );
+
+    if (!alreadyInstalled) {
+      const hookDef: HookCommand = {
+        type: "command",
+        command: REPORTER_PATH,
+      };
+      if (isAsync) {
+        hookDef.async = true;
+      }
+      eventHooks.push({ hooks: [hookDef] });
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+    fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+    console.log("> Hooks configured in ~/.claude/settings.json");
+  }
+}
+
+export function setupHooks(): void {
+  try {
+    installReporterScript();
+    mergeHooksIntoSettings();
+    console.log(
+      "> Hook reporter installed at ~/.claude-deck/hooks/state-reporter"
+    );
+  } catch (err) {
+    console.error("Failed to setup hooks:", err);
+  }
+}
+
+export { STATES_DIR };

package/lib/orchestration.ts

@@ -12,7 +12,8 @@ import { queries, type Session } from "./db";
 import { createWorktree, deleteWorktree } from "./worktrees";
 import { setupWorktree } from "./env-setup";
 import { type AgentType, getProvider } from "./providers";
-import { statusDetector } from "./status-detector";
+import { getStatusSnapshot } from "./status-monitor";
+import { getSessionIdFromName } from "./providers/registry";
 import { wrapWithBanner } from "./banner";
 import { runInBackground } from "./async-operations";
 
@@ -273,13 +274,10 @@ export async function getWorkers(
     const provider = getProvider(worker.agent_type || "claude");
     const tmuxSessionName = worker.tmux_name || `${provider.id}-${worker.id}`;
 
-    // Get live status from tmux
-    let liveStatus: string;
-    try {
-      liveStatus = await statusDetector.getStatus(tmuxSessionName);
-    } catch {
-      liveStatus = "dead";
-    }
+    // Get live status from cached monitor snapshot
+    const sessionId = getSessionIdFromName(tmuxSessionName);
+    const snapshot = getStatusSnapshot();
+    const liveStatus = snapshot[sessionId]?.status || "dead";
 
     // Combine DB status with live status
     let status: WorkerInfo["status"];

package/lib/providers/registry.ts

@@ -53,7 +53,7 @@ export function isValidProviderId(value: string): value is ProviderId {
 }
 
 export function getManagedSessionPattern(): RegExp {
-  return /^claude-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  return /^claude-(new-)?[0-9a-z]{4,}/i;
 }
 
 export function getProviderIdFromSessionName(

package/lib/status-monitor.ts

@@ -0,0 +1,278 @@
+/**
+ * Session status monitor — hook-based detection.
+ *
+ * Claude Code hooks write state files to ~/.claude-deck/session-states/.
+ * This module reads those files and pushes updates to the frontend via WebSocket.
+ *
+ * The only periodic work is `tmux list-sessions` every 3s to detect dead sessions.
+ * All state transitions are event-driven via Chokidar watching the state files dir.
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getManagedSessionPattern,
+  getSessionIdFromName,
+  getProviderIdFromSessionName,
+} from "./providers/registry";
+import type { AgentType } from "./providers";
+import { broadcast } from "./claude/watcher";
+import { getDb } from "./db";
+import { STATES_DIR } from "./hooks/setup";
+import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+
+const execAsync = promisify(exec);
+
+const TICK_INTERVAL_MS = 3000;
+const SESSION_NAME_CACHE_TTL = 10_000;
+const UUID_PATTERN = getManagedSessionPattern();
+
+// Cache for session display names (summary from SDK)
+const sessionNameCache = new Map<string, { name: string; cachedAt: number }>();
+
+// --- Types ---
+
+export type SessionStatus = "running" | "waiting" | "idle" | "dead";
+
+interface StateFile {
+  status: "running" | "waiting" | "idle";
+  lastLine: string;
+  waitingContext?: string;
+  ts: number;
+}
+
+export interface SessionStatusSnapshot {
+  sessionName: string;
+  status: SessionStatus;
+  lastLine: string;
+  waitingContext?: string;
+  claudeSessionId: string | null;
+  agentType: AgentType;
+}
+
+// --- State ---
+
+let currentSnapshot: Record<string, SessionStatusSnapshot> = {};
+let monitorTimer: ReturnType<typeof setInterval> | null = null;
+
+// --- State file reading ---
+
+function readStateFile(sessionId: string): StateFile | null {
+  try {
+    const filePath = path.join(STATES_DIR, `${sessionId}.json`);
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function listStateFiles(): Map<string, StateFile> {
+  const map = new Map<string, StateFile>();
+  try {
+    for (const file of fs.readdirSync(STATES_DIR)) {
+      if (!file.endsWith(".json")) continue;
+      const sessionId = file.replace(".json", "");
+      const state = readStateFile(sessionId);
+      if (state) map.set(sessionId, state);
+    }
+  } catch {
+    // dir may not exist yet
+  }
+  return map;
+}
+
+// --- tmux ---
+
+async function listTmuxSessions(): Promise<Map<string, string>> {
+  // Returns Map<sessionId, sessionName>
+  try {
+    const { stdout } = await execAsync(
+      "tmux list-sessions -F '#{session_name}' 2>/dev/null || echo \"\""
+    );
+    const map = new Map<string, string>();
+    for (const name of stdout.trim().split("\n")) {
+      if (!name || !UUID_PATTERN.test(name)) continue;
+      map.set(getSessionIdFromName(name), name);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+// --- Session display name resolution ---
+
+async function resolveSessionDisplayName(sessionId: string): Promise<string> {
+  const cached = sessionNameCache.get(sessionId);
+  if (cached && Date.now() - cached.cachedAt < SESSION_NAME_CACHE_TTL) {
+    return cached.name;
+  }
+
+  try {
+    const info = await getSessionInfo(sessionId);
+    if (info) {
+      const name = info.customTitle || info.summary || sessionId.slice(0, 8);
+      sessionNameCache.set(sessionId, { name, cachedAt: Date.now() });
+      return name;
+    }
+  } catch {
+    // SDK lookup failed — use short ID
+  }
+
+  const fallback = sessionId.slice(0, 8);
+  sessionNameCache.set(sessionId, { name: fallback, cachedAt: Date.now() });
+  return fallback;
+}
+
+// --- Snapshot building ---
+
+async function buildSnapshot(
+  tmuxSessions: Map<string, string>,
+  stateFiles: Map<string, StateFile>
+): Promise<Record<string, SessionStatusSnapshot>> {
+  const snap: Record<string, SessionStatusSnapshot> = {};
+
+  const entries = await Promise.all(
+    [...tmuxSessions.entries()].map(async ([sessionId, tmuxName]) => {
+      const displayName = await resolveSessionDisplayName(sessionId);
+      return { sessionId, tmuxName, displayName };
+    })
+  );
+
+  for (const { sessionId, tmuxName, displayName } of entries) {
+    const agentType = getProviderIdFromSessionName(tmuxName) || "claude";
+    const state = stateFiles.get(sessionId);
+
+    snap[sessionId] = {
+      sessionName: displayName,
+      status: state?.status || "idle",
+      lastLine: state?.lastLine || "",
+      ...(state?.status === "waiting" && state.waitingContext
+        ? { waitingContext: state.waitingContext }
+        : {}),
+      claudeSessionId: sessionId,
+      agentType,
+    };
+  }
+
+  return snap;
+}
+
+function snapshotChanged(
+  prev: Record<string, SessionStatusSnapshot>,
+  next: Record<string, SessionStatusSnapshot>
+): boolean {
+  const prevKeys = Object.keys(prev);
+  const nextKeys = Object.keys(next);
+  if (prevKeys.length !== nextKeys.length) return true;
+  for (const id of nextKeys) {
+    const p = prev[id];
+    const n = next[id];
+    if (
+      !p ||
+      p.status !== n.status ||
+      p.lastLine !== n.lastLine ||
+      p.sessionName !== n.sessionName
+    )
+      return true;
+  }
+  return false;
+}
+
+function updateDb(
+  prev: Record<string, SessionStatusSnapshot>,
+  next: Record<string, SessionStatusSnapshot>
+): void {
+  try {
+    const db = getDb();
+    for (const [id, snap] of Object.entries(next)) {
+      if (prev[id]?.status === snap.status) continue;
+      db.prepare(
+        "UPDATE sessions SET updated_at = datetime('now') WHERE id = ?"
+      ).run(id);
+      if (snap.claudeSessionId) {
+        db.prepare(
+          "UPDATE sessions SET claude_session_id = ? WHERE id = ? AND (claude_session_id IS NULL OR claude_session_id != ?)"
+        ).run(snap.claudeSessionId, id, snap.claudeSessionId);
+      }
+    }
+  } catch {
+    // DB errors shouldn't break the monitor
+  }
+}
+
+// --- Core tick (only for dead detection + state file sync) ---
+
+async function tick(): Promise<void> {
+  const tmuxSessions = await listTmuxSessions();
+  const stateFiles = listStateFiles();
+
+  // Clean up state files for sessions that no longer exist in tmux
+  for (const sessionId of stateFiles.keys()) {
+    if (!tmuxSessions.has(sessionId)) {
+      try {
+        fs.unlinkSync(path.join(STATES_DIR, `${sessionId}.json`));
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  const newSnapshot = await buildSnapshot(tmuxSessions, stateFiles);
+
+  if (snapshotChanged(currentSnapshot, newSnapshot)) {
+    updateDb(currentSnapshot, newSnapshot);
+    currentSnapshot = newSnapshot;
+    broadcast({ type: "session-statuses", statuses: newSnapshot });
+  }
+}
+
+// --- Public API ---
+
+export function getStatusSnapshot(): Record<string, SessionStatusSnapshot> {
+  return currentSnapshot;
+}
+
+export function acknowledge(_sessionName: string): void {
+  // With hook-based detection, acknowledge is a no-op.
+  // Status is determined by Claude Code's hook events, not by us.
+}
+
+/**
+ * Called by Chokidar when a state file in ~/.claude-deck/session-states/ changes.
+ * Triggers an immediate re-read and broadcast.
+ */
+export function onStateFileChange(): void {
+  tick().catch(console.error);
+}
+
+export function invalidateSessionName(sessionId: string): void {
+  sessionNameCache.delete(sessionId);
+}
+
+export function startStatusMonitor(): void {
+  if (monitorTimer) return;
+
+  // Ensure states directory exists
+  fs.mkdirSync(STATES_DIR, { recursive: true });
+
+  // Initial tick
+  setTimeout(() => tick().catch(console.error), 500);
+
+  // Periodic fallback (catches tmux session death, missed events)
+  monitorTimer = setInterval(() => {
+    tick().catch(console.error);
+  }, TICK_INTERVAL_MS);
+
+  console.log("> Status monitor started (hook-based, 3s fallback tick)");
+}
+
+export function stopStatusMonitor(): void {
+  if (monitorTimer) {
+    clearInterval(monitorTimer);
+    monitorTimer = null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atercates/claude-deck",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "claude-deck": "./scripts/claude-deck"

package/server.ts

@@ -5,6 +5,8 @@ import { WebSocketServer, WebSocket } from "ws";
 import * as pty from "node-pty";
 import { initDb } from "./lib/db";
 import { startWatcher, addUpdateClient } from "./lib/claude/watcher";
+import { startStatusMonitor } from "./lib/status-monitor";
+import { setupHooks } from "./lib/hooks/setup";
 import {
   validateSession,
   parseCookies,
@@ -166,7 +168,9 @@ app.prepare().then(async () => {
   await initDb();
   console.log("> Database initialized");
 
+  setupHooks();
   startWatcher();
+  startStatusMonitor();
 
   server.listen(port, () => {
     console.log(`> ClaudeDeck ready on http://${hostname}:${port}`);