claude-mux 0.7.0

package/docs/state-transitions.md

@@ -0,0 +1,109 @@
+# Session State Transitions
+
+## States
+
+| State | Color | Description |
+|-------|-------|-------------|
+| `idle` | Yellow | Ready for new task |
+| `busy` | Green | Working (thinking, tool use) |
+| `waiting` | Red | Asking user a question |
+| `permission` | Red | Needs permission to proceed |
+
+## Transition Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle: SessionStart
+
+    idle --> busy: UserPromptSubmit (hook)
+
+    busy --> busy: PreToolUse (hook)\nupdates current_action
+    busy --> idle: Stop (hook)
+    busy --> idle: Polling: "Interrupted" in last message
+    busy --> permission: PermissionRequest (hook)
+    busy --> permission: Notification: permission_prompt
+    busy --> waiting: Notification: idle_prompt
+    busy --> waiting: Notification: elicitation_dialog
+
+    waiting --> idle: User answers\n(triggers new hooks)
+    waiting --> idle: Polling: "User declined" in last message
+
+    permission --> idle: User grants/denies\n(triggers new hooks)
+    permission --> idle: Polling: "User declined" in last message
+
+    idle --> [*]: SessionEnd
+```
+
+## Hooks
+
+| Hook | Transition | Description |
+|------|------------|-------------|
+| `SessionStart` | → `idle` | New session registered |
+| `UserPromptSubmit` | → `busy` | User submitted a prompt |
+| `PreToolUse` | stays `busy` | Updates `current_action` with tool name |
+| `PostToolUse` | stays `busy` | Clears tool-specific status |
+| `Stop` | → `idle` | Claude finished responding |
+| `PermissionRequest` | → `permission` | Needs permission for action |
+| `Notification: permission_prompt` | → `permission` | Permission dialog shown |
+| `Notification: idle_prompt` | → `waiting` | Question for user |
+| `Notification: elicitation_dialog` | → `waiting` | Menu/choice for user |
+| `SessionEnd` | (removed) | Session ended |
+
+## Polling Detection
+
+Polling runs every 2 seconds and checks tmux pane content for explicit interruption/cancellation signals.
+
+### Detection Logic
+
+| Signal | Action |
+|--------|--------|
+| Last Claude message contains "Interrupted" | Set state to `idle` |
+| Last Claude message contains "User declined to answer" | Set state to `idle` |
+| Otherwise | Trust hooks, don't change state |
+
+### Why Explicit Signals?
+
+Claude Code doesn't fire hooks when the user presses Escape to interrupt or cancel. Polling detects these cases by looking for explicit messages in the pane:
+
+**Interrupted** (user pressed Esc while Claude was working):
+```
+● Bash(ls)
+  ⎿  Interrupted · What should Claude do instead?
+
+─────────────────────────────────────────────────
+❯
+```
+
+**Declined** (user pressed Esc on a question/menu):
+```
+● User declined to answer questions
+
+─────────────────────────────────────────────────
+❯
+```
+
+### Scoped Detection
+
+To avoid false positives from older history in the scrollback, the detection algorithm:
+
+1. **Skip if active UI**: If "Esc to cancel", "Esc to interrupt", or "ctrl+c to interrupt" appears in the bottom 5 lines, there's an active menu or Claude is working - don't detect old interruptions
+2. **Find prompt separators**: Locate the two `─────` separator lines around the prompt area
+3. **Find interaction start**: Scan backwards from the TOP separator to find a line starting with `●` (Claude output) or `❯` (user prompt)
+4. **Check the slice**: Look for "Interrupted" or "User declined" only in the slice between the interaction start and the TOP separator
+
+```
+❯ run ls                    ← interaction start
+  ⎿  Interrupted...         ← signal in this slice
+
+─────────────────────────   ← TOP separator
+❯                           ← prompt area
+─────────────────────────   ← BOTTOM separator
+  status line
+```
+
+### Why This Works
+
+- **Active UI protection**: Menus and working states show "Esc to cancel/interrupt" at the bottom, so we skip detection entirely
+- **Scoped to last interaction**: We only check between the last `●`/`❯` and the separator, not the entire scrollback
+- **Hooks handle normal cases**: State transitions for normal completion, questions, and permissions are handled by hooks
+- **Polling only catches Escape**: The only case polling handles is when the user presses Escape (no hook fires)

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "claude-mux",
+  "version": "0.7.0",
+  "description": "Real-time web dashboard for monitoring and controlling multiple Claude Code sessions",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "claude-mux": "dist/cli.js"
+  },
+  "workspaces": [
+    "web"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/christinoleo/claude-mux.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run build:cli && bun run build:web",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "build:web": "cd web && bun run build",
+    "dev": "tsc -p tsconfig.cli.json --watch",
+    "dev:serve": "while true; do (cd web && bun run dev --host 0.0.0.0 --port 3456); echo 'Dev server crashed, restarting in 2s...'; sleep 2; done",
+    "start": "bun dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src tests --ext .ts,.tsx",
+    "format": "prettier --write 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+    "prepublishOnly": "bun run build",
+    "preuninstall": "claude-mux --cleanup || true",
+    "version": "bun -e \"const v=require('./package.json').version; require('fs').writeFileSync('src/utils/version.ts', '/**\\n * Central version constant for claude-watch.\\n * Keep in sync with package.json version.\\n */\\nexport const VERSION = \\\"'+v+'\\\";\\n')\" && git add src/utils/version.ts"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "web",
+    "dashboard",
+    "monitoring",
+    "websocket",
+    "sveltekit",
+    "tmux",
+    "real-time"
+  ],
+  "author": "Leonardo Christino",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ink": "^5.1.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "@vitest/coverage-istanbul": "^2.1.8",
+    "eslint": "^8.57.0",
+    "ink-testing-library": "^4.0.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/app.tsx

@@ -0,0 +1,188 @@
+import React, { useState, useEffect, useCallback } from "react";
+import { Box, useApp, useInput, useStdout } from "ink";
+import { Header, HelpDialog, SessionList, StatusBar } from "./components/index.js";
+import { getTotalItemCount, getItemAtIndex } from "./components/SessionList.js";
+import {
+  getAllSessions,
+  cleanupStaleSessions,
+  updateSession,
+  type Session,
+} from "./db/index.js";
+import { isInTmux, getAllTmuxSessions, getTmuxSessionName, type TmuxSession } from "./tmux/detect.js";
+import { switchToTarget } from "./tmux/navigate.js";
+import { checkForInterruption } from "./tmux/pane.js";
+
+const POLL_INTERVAL = 500; // ms
+const CLEANUP_INTERVAL = 5000; // ms
+const PANE_CHECK_INTERVAL = 500; // ms - check tmux panes for prompt
+
+export function App() {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [tmuxSessions, setTmuxSessions] = useState<TmuxSession[]>([]);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [showHelp, setShowHelp] = useState(false);
+  const [inTmux] = useState(() => isInTmux());
+  const [currentTmuxSession] = useState(() => getTmuxSessionName());
+
+  // Get terminal dimensions
+  const terminalHeight = stdout?.rows || 24;
+  const terminalWidth = stdout?.columns || 80;
+
+  // Load sessions from JSON files and tmux
+  const loadSessions = useCallback(() => {
+    try {
+      const loadedSessions = getAllSessions();
+
+      // Only update if sessions have changed (compare by JSON to detect actual changes)
+      setSessions((prev) => {
+        const prevJson = JSON.stringify(prev);
+        const newJson = JSON.stringify(loadedSessions);
+        return prevJson === newJson ? prev : loadedSessions;
+      });
+
+      // Also load tmux sessions (excluding the current session where claude-mux runs)
+      const loadedTmuxSessions = getAllTmuxSessions().filter(
+        (ts) => ts.name !== currentTmuxSession
+      );
+
+      // Only update if tmux sessions have changed
+      setTmuxSessions((prev) => {
+        const prevJson = JSON.stringify(prev);
+        const newJson = JSON.stringify(loadedTmuxSessions);
+        return prevJson === newJson ? prev : loadedTmuxSessions;
+      });
+
+      // Adjust selected index if out of bounds
+      const totalCount = getTotalItemCount(loadedSessions, loadedTmuxSessions);
+      if (selectedIndex >= totalCount) {
+        setSelectedIndex(Math.max(0, totalCount - 1));
+      }
+    } catch {
+      // Ignore errors, try again next poll
+    }
+  }, [selectedIndex, currentTmuxSession]);
+
+  // Poll for session updates
+  useEffect(() => {
+    loadSessions();
+    const interval = setInterval(loadSessions, POLL_INTERVAL);
+    return () => clearInterval(interval);
+  }, [loadSessions]);
+
+  // Cleanup stale sessions periodically
+  useEffect(() => {
+    const cleanup = () => {
+      try {
+        cleanupStaleSessions();
+      } catch {
+        // Ignore errors during cleanup
+      }
+    };
+
+    cleanup(); // Run on startup
+    const interval = setInterval(cleanup, CLEANUP_INTERVAL);
+    return () => clearInterval(interval);
+  }, []);
+
+  // Check tmux panes to sync state with what's actually shown
+  useEffect(() => {
+    if (!inTmux) return;
+
+    const checkPanes = () => {
+      try {
+        const allSessions = getAllSessions().filter((s) => s.tmux_target);
+
+        for (const session of allSessions) {
+          if (!session.tmux_target) continue;
+
+          const update = checkForInterruption(session.tmux_target);
+          if (update && session.state !== "idle") {
+            updateSession(session.id, update);
+          }
+        }
+      } catch {
+        // Ignore errors during pane check
+      }
+    };
+
+    const interval = setInterval(checkPanes, PANE_CHECK_INTERVAL);
+    return () => clearInterval(interval);
+  }, [inTmux]);
+
+  // Get total item count for navigation
+  const totalCount = getTotalItemCount(sessions, tmuxSessions);
+
+  // Calculate non-Claude tmux session count for header
+  const claudeTmuxSessions = new Set<string>();
+  for (const session of sessions) {
+    if (session.tmux_target) {
+      const sessionName = session.tmux_target.split(":")[0];
+      claudeTmuxSessions.add(sessionName);
+    }
+  }
+  const nonClaudeTmuxCount = tmuxSessions.filter(
+    (ts) => !claudeTmuxSessions.has(ts.name)
+  ).length;
+
+  // Handle keyboard input
+  useInput((input, key) => {
+    if (input === "q") {
+      exit();
+      return;
+    }
+
+    if (input === "h") {
+      setShowHelp((prev) => !prev);
+      return;
+    }
+
+    // Dismiss help on any other key
+    if (showHelp) {
+      setShowHelp(false);
+      return;
+    }
+
+    if (totalCount === 0) return;
+
+    // Navigation
+    if (key.upArrow || input === "k") {
+      setSelectedIndex((prev) => Math.max(0, prev - 1));
+    } else if (key.downArrow || input === "j") {
+      setSelectedIndex((prev) => Math.min(totalCount - 1, prev + 1));
+    }
+
+    // Jump to session
+    if (key.return && inTmux) {
+      const item = getItemAtIndex(sessions, tmuxSessions, selectedIndex);
+      if (item) {
+        if (item.type === "claude" && item.session.tmux_target) {
+          switchToTarget(item.session.tmux_target);
+        } else if (item.type === "tmux") {
+          // For tmux sessions, switch to the session (first window)
+          switchToTarget(item.tmuxSession.name + ":");
+        }
+      }
+    }
+  });
+
+  return (
+    <Box flexDirection="column" height={terminalHeight}>
+      <Header claudeCount={sessions.length} tmuxCount={nonClaudeTmuxCount} />
+      <Box borderStyle="single" borderTop={false} borderBottom={false} flexGrow={1}>
+        {showHelp ? (
+          <HelpDialog width={terminalWidth - 2} />
+        ) : (
+          <SessionList
+            sessions={sessions}
+            tmuxSessions={tmuxSessions}
+            selectedIndex={selectedIndex}
+            width={terminalWidth - 2}
+          />
+        )}
+      </Box>
+      <StatusBar inTmux={inTmux} />
+    </Box>
+  );
+}

package/src/cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import {
+  createServeCommand,
+  createSetupCommand,
+  createUninstallCommand,
+  runTui,
+  runServe,
+} from "./commands/index.js";
+import { runSetup, runCleanup } from "./setup/index.js";
+import { DEFAULT_SERVER_PORT } from "./utils/paths.js";
+import { VERSION } from "./utils/version.js";
+
+// Deprecation warning helper
+function deprecationWarning(oldFlag: string, newCommand: string): void {
+  console.warn(
+    `\x1b[33m⚠ Warning: --${oldFlag} is deprecated. Use "claude-mux ${newCommand}" instead.\x1b[0m`
+  );
+  console.warn("");
+}
+
+program
+  .name("claude-mux")
+  .description("TUI dashboard for monitoring Claude Code sessions")
+  .version(VERSION);
+
+// Register subcommands
+program.addCommand(createServeCommand());
+program.addCommand(createSetupCommand());
+program.addCommand(createUninstallCommand());
+
+// BACKWARD COMPATIBILITY: Support old flags on root command
+program
+  .option("--setup", "Run interactive setup wizard (deprecated: use 'setup' command)")
+  .option("--uninstall", "Remove hooks (deprecated: use 'uninstall' command)")
+  .option("--cleanup", "Remove hooks (alias for --uninstall)")
+  .option("--serve", "Start HTTP server alongside TUI (use with --serve-port, --serve-host)")
+  .option("--serve-only", "Run HTTP server only (deprecated: use 'serve' command)")
+  .option("--serve-port <number>", "Server port for --serve/--serve-only", String(DEFAULT_SERVER_PORT))
+  .option("--serve-host <address>", "Server host for --serve/--serve-only", "127.0.0.1");
+
+// Hide deprecated options from help
+program.options.forEach((opt) => {
+  if (["--setup", "--uninstall", "--cleanup", "--serve-only", "--serve-port", "--serve-host"].includes(opt.long || "")) {
+    opt.hidden = true;
+  }
+});
+
+// Default action: handle deprecated flags or run TUI
+program.action(async (options) => {
+  // Handle deprecated --setup flag
+  if (options.setup) {
+    deprecationWarning("setup", "setup");
+    await runSetup();
+    process.exit(0);
+  }
+
+  // Handle deprecated --uninstall or --cleanup flag
+  if (options.uninstall || options.cleanup) {
+    if (options.uninstall) {
+      deprecationWarning("uninstall", "uninstall");
+    }
+    await runCleanup();
+    process.exit(0);
+  }
+
+  // Handle deprecated --serve-only flag
+  if (options.serveOnly) {
+    deprecationWarning("serve-only", "serve");
+    await runServe({ port: options.servePort, host: options.serveHost });
+    return;
+  }
+
+  // Default: run TUI (with optional --serve)
+  await runTui({
+    serve: options.serve,
+    port: options.servePort,
+    host: options.serveHost,
+  });
+});
+
+program.parse();

package/src/commands/index.ts

@@ -0,0 +1,4 @@
+export { createTuiCommand, runTui } from "./tui.js";
+export { createServeCommand, runServe } from "./serve.js";
+export { createSetupCommand } from "./setup.js";
+export { createUninstallCommand } from "./uninstall.js";

package/src/commands/serve.ts

@@ -0,0 +1,75 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { CLAUDE_WATCH_DIR, SESSIONS_DIR, DEFAULT_SERVER_PORT } from "../utils/paths.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface ServeOptions {
+  port: string;
+  host: string;
+}
+
+export async function runServe(options: ServeOptions): Promise<void> {
+  // Auto-create data directories if needed
+  if (!existsSync(CLAUDE_WATCH_DIR)) {
+    mkdirSync(CLAUDE_WATCH_DIR, { recursive: true });
+  }
+  if (!existsSync(SESSIONS_DIR)) {
+    mkdirSync(SESSIONS_DIR, { recursive: true });
+  }
+
+  // Path to built SvelteKit handler
+  const handlerPath = join(__dirname, "..", "web", "handler.js");
+
+  if (!existsSync(handlerPath)) {
+    console.error(`SvelteKit handler not found at: ${handlerPath}`);
+    console.error("Run 'bun run build' first.");
+    process.exit(1);
+  }
+
+  // Import the handler module
+  const { getHandler } = await import(handlerPath);
+  const { fetch: handlerFetch, websocket } = getHandler();
+
+  // Start server with WebSocket compression enabled
+  const server = Bun.serve({
+    port: Number(options.port),
+    hostname: options.host,
+    fetch: handlerFetch,
+    // Enable perMessageDeflate for WebSocket compression (RFC 7692)
+    // This typically achieves 70-80% compression on JSON/text messages
+    ...(websocket
+      ? {
+          websocket: {
+            ...websocket,
+            perMessageDeflate: true,
+          },
+        }
+      : {}),
+  });
+
+  console.log(
+    `Listening on ${server.url}${websocket ? " with WebSocket (compression enabled)" : ""}`
+  );
+
+  // Graceful shutdown
+  const gracefulShutdown = async (signal: string): Promise<void> => {
+    console.info(`\nReceived ${signal}, stopping server...`);
+    await server.stop(true);
+    console.info("Server stopped");
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+  process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+}
+
+export function createServeCommand(): Command {
+  return new Command("serve")
+    .description("Start HTTP server only (no TUI, no tmux required)")
+    .option("--port <number>", "Server port", String(DEFAULT_SERVER_PORT))
+    .option("--host <address>", "Server host (use 0.0.0.0 for LAN)", "127.0.0.1")
+    .action(runServe);
+}

package/src/commands/setup.ts

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+import { runSetup } from "../setup/index.js";
+
+export async function runSetupCommand(): Promise<void> {
+  await runSetup();
+  process.exit(0);
+}
+
+export function createSetupCommand(): Command {
+  return new Command("setup")
+    .description("Run interactive setup wizard")
+    .action(runSetupCommand);
+}