mob-coordinator 0.2.1 → 0.3.0

package/README.md

@@ -27,47 +27,33 @@ A local web dashboard for coordinating multiple Claude Code CLI sessions. Launch
 ## Quick Start
 
 ```bash
-git clone https://github.com/nickelbob/mob.git
-cd mob
-npm install
+npm install -g mob-coordinator
+mob
 ```
 
-If you see errors about missing native modules, run:
+Open `http://localhost:4040` in your browser.
 
-```bash
-npm run setup
-```
-
-This detects your platform and installs the correct native binaries for node-pty and rollup. It also runs automatically before `npm run dev` and `npm run build`.
-
-### Install Claude Code Hooks
-
-To enable status reporting (state, branch, auto-naming) from Claude instances launched by mob:
+Claude Code hooks are installed automatically on first launch. These enable status reporting (state, branch, auto-naming) from Claude instances. To manually manage hooks:
 
 ```bash
-npm run install-hooks
+mob install-hooks      # Re-install hooks
+mob uninstall-hooks    # Remove hooks
 ```
 
-This adds hook entries to `~/.claude/settings.json` that report instance status back to the dashboard.
+### Development
 
-### Run
-
-**Development** (hot-reload):
+To contribute or run from source:
 
 ```bash
+git clone https://github.com/nickelbob/mob.git
+cd mob
+npm install
 npm run dev
 ```
 
 Opens the backend on `http://localhost:4040` and the Vite dev server on `http://localhost:4041`. Use port 4041 during development.
 
-**Production**:
-
-```bash
-npm run build
-npm start
-```
-
-Everything is served from `http://localhost:4040`.
+If you see errors about missing native modules, run `npm run setup` to auto-detect and install the correct platform-specific binaries.
 
 ## Usage
 
@@ -146,7 +132,7 @@ See `CLAUDE.md` for detailed architecture documentation.
 ## Uninstalling Hooks
 
 ```bash
-npm run uninstall-hooks
+mob uninstall-hooks
 ```
 
 ## Troubleshooting
@@ -172,7 +158,7 @@ MOB_PORT=4050 npm run dev
 
 ### Hooks not reporting status
 
-1. Make sure hooks are installed: `npm run install-hooks`
+1. Hooks are auto-installed on startup. To force re-install: `mob install-hooks`
 2. Check `~/.claude/settings.json` has entries for `PreToolUse`, `PostToolUse`, `Stop`, `UserPromptSubmit`, and `Notification`
 3. On Windows, ensure PowerShell can run the hook script (execution policy)
 
@@ -182,6 +168,18 @@ If hooks aren't firing (crash, subtask weirdness), the terminal state fallback s
 
 ## Changelog
 
+### 0.3.0
+
+- Auto-install Claude Code hooks on server startup — no manual setup required
+- Add `mob install-hooks` and `mob uninstall-hooks` CLI subcommands
+- Include hook scripts in npm package
+- Add landing page website for GitHub Pages
+
+### 0.2.1
+
+- Fix false "Needs Input" showing when Claude finishes a task (completion notifications no longer trigger waiting state)
+- npm package available: `npm install -g mob-coordinator`
+
 ### 0.2.0
 
 - Terminal-based state fallback when hooks are silent (detects running/waiting/idle from scrollback)

package/bin/mob.js

@@ -6,15 +6,26 @@ import { dirname, join } from 'path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = join(__dirname, '..');
-const serverEntry = join(root, 'dist', 'server', 'server', 'index.js');
 
-// Run the server, forwarding stdio and signals
-const child = spawn(process.execPath, [serverEntry], {
-  cwd: root,
-  stdio: 'inherit',
-  env: { ...process.env },
-});
+const subcommand = process.argv[2];
 
-child.on('exit', (code) => process.exit(code ?? 0));
-process.on('SIGINT', () => child.kill('SIGINT'));
-process.on('SIGTERM', () => child.kill('SIGTERM'));
+if (subcommand === 'install-hooks') {
+  const { installHooks } = await import(join(root, 'dist', 'server', 'server', 'hooks.js'));
+  installHooks(root);
+} else if (subcommand === 'uninstall-hooks') {
+  const { uninstallHooks } = await import(join(root, 'dist', 'server', 'server', 'hooks.js'));
+  uninstallHooks();
+} else {
+  const serverEntry = join(root, 'dist', 'server', 'server', 'index.js');
+
+  // Run the server, forwarding stdio and signals
+  const child = spawn(process.execPath, [serverEntry], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+  process.on('SIGINT', () => child.kill('SIGINT'));
+  process.on('SIGTERM', () => child.kill('SIGTERM'));
+}

package/dist/server/server/hooks.js

@@ -0,0 +1,119 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'UserPromptSubmit',
+    'Notification',
+];
+function getHookCommand(packageRoot) {
+    if (process.platform === 'win32') {
+        const hookScript = path.resolve(packageRoot, 'hooks', 'mob-status.ps1');
+        const psPath = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+        return `"${psPath}" -NoProfile -ExecutionPolicy Bypass -File "${hookScript}"`;
+    }
+    const hookScript = path.resolve(packageRoot, 'hooks', 'mob-status.sh');
+    return `bash "${hookScript}"`;
+}
+function readSettings() {
+    const settingsDir = path.dirname(CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(settingsDir)) {
+        fs.mkdirSync(settingsDir, { recursive: true });
+    }
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+        try {
+            return JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+        }
+        catch {
+            // Corrupted settings — start fresh
+        }
+    }
+    return {};
+}
+function writeSettings(settings) {
+    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+}
+function isMobHook(entry) {
+    // New format: { matcher, hooks: [{ type, command }] }
+    if (entry.hooks && Array.isArray(entry.hooks)) {
+        return entry.hooks.some((h) => h.type === 'command' && typeof h.command === 'string' && h.command.includes('mob-status'));
+    }
+    // Old format: { type, command }
+    if (entry.type === 'command' && typeof entry.command === 'string' && entry.command.includes('mob-status')) {
+        return true;
+    }
+    return false;
+}
+export function installHooks(packageRoot, quiet = false) {
+    const hookScript = process.platform === 'win32'
+        ? path.resolve(packageRoot, 'hooks', 'mob-status.ps1')
+        : path.resolve(packageRoot, 'hooks', 'mob-status.sh');
+    if (!fs.existsSync(hookScript)) {
+        if (!quiet)
+            console.error(`Hook script not found: ${hookScript}`);
+        return;
+    }
+    const settings = readSettings();
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hookCommand = getHookCommand(packageRoot);
+    for (const event of HOOK_EVENTS) {
+        if (!settings.hooks[event]) {
+            settings.hooks[event] = [];
+        }
+        // Remove any existing mob hooks (old or new format)
+        settings.hooks[event] = settings.hooks[event].filter((entry) => !isMobHook(entry));
+        // Add hook in current format
+        settings.hooks[event].push({
+            matcher: '',
+            hooks: [{ type: 'command', command: hookCommand }],
+        });
+    }
+    writeSettings(settings);
+    if (!quiet) {
+        console.log('Mob hooks installed successfully!');
+        console.log(`Hook script: ${hookScript}`);
+        console.log(`Events: ${HOOK_EVENTS.join(', ')}`);
+    }
+}
+export function uninstallHooks(quiet = false) {
+    if (!fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+        if (!quiet)
+            console.log('No Claude settings found, nothing to uninstall.');
+        return;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+    }
+    catch {
+        if (!quiet)
+            console.error('Could not parse settings.json');
+        return;
+    }
+    if (!settings.hooks) {
+        if (!quiet)
+            console.log('No hooks found in settings.');
+        return;
+    }
+    let removed = 0;
+    for (const event of Object.keys(settings.hooks)) {
+        if (Array.isArray(settings.hooks[event])) {
+            const before = settings.hooks[event].length;
+            settings.hooks[event] = settings.hooks[event].filter((entry) => !isMobHook(entry));
+            removed += before - settings.hooks[event].length;
+            if (settings.hooks[event].length === 0) {
+                delete settings.hooks[event];
+            }
+        }
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    writeSettings(settings);
+    if (!quiet)
+        console.log(`Removed ${removed} mob hook(s) from Claude settings.`);
+}

package/dist/server/server/index.js

@@ -9,6 +9,7 @@ import { ScrollbackBuffer } from './scrollback-buffer.js';
 import { SettingsManager } from './settings-manager.js';
 import { ensureDir, getMobDir, getInstancesDir, getSessionsDir, getScrollbackDir } from './util/platform.js';
 import { DEFAULT_PORT } from '../shared/constants.js';
+import { installHooks } from './hooks.js';
 const port = parseInt(process.env.MOB_PORT || '', 10) || DEFAULT_PORT;
 const host = process.env.MOB_HOST || '127.0.0.1';
 // Ensure directories exist
@@ -16,6 +17,9 @@ ensureDir(getMobDir());
 ensureDir(getInstancesDir());
 ensureDir(getSessionsDir());
 ensureDir(getScrollbackDir());
+// Auto-install Claude Code hooks so external instances are discovered
+const packageRoot = new URL('../../..', import.meta.url).pathname;
+installHooks(packageRoot, true);
 const settingsManager = new SettingsManager();
 const ptyManager = new PtyManager();
 const discovery = new DiscoveryService();

package/hooks/mob-status.ps1

@@ -0,0 +1,151 @@
+# Mob status hook for Claude Code (Windows PowerShell)
+# Reads hook event from stdin, writes instance status to ~/.mob/instances/{id}.json
+
+$MobDir = Join-Path $env:USERPROFILE ".mob"
+$InstancesDir = Join-Path $MobDir "instances"
+$LogFile = Join-Path $MobDir "hook-debug.log"
+$MobPort = if ($env:MOB_PORT) { $env:MOB_PORT } else { "4040" }
+
+New-Item -ItemType Directory -Force -Path $InstancesDir | Out-Null
+
+function Log($msg) {
+    $ts = Get-Date -Format "HH:mm:ss.fff"
+    "$ts $msg" | Out-File -Append -FilePath $LogFile -Encoding UTF8
+}
+
+Log "=== Hook started (PID=$PID) ==="
+
+# Only report for mob-launched instances
+if (-not $env:MOB_INSTANCE_ID) {
+    Log "No MOB_INSTANCE_ID, skipping"
+    exit 0
+}
+
+# Read JSON from stdin
+try {
+    $RawInput = [Console]::In.ReadToEnd()
+} catch {
+    Log "stdin read FAILED: $_"
+    exit 0
+}
+
+if (-not $RawInput -or $RawInput.Trim().Length -eq 0) {
+    Log "Empty stdin, exiting"
+    exit 0
+}
+
+try {
+    $Data = $RawInput | ConvertFrom-Json
+} catch {
+    Log "JSON parse FAILED: $_"
+    exit 0
+}
+
+# Claude Code uses hook_event_name, not event
+$HookEvent = if ($Data.hook_event_name) { "$($Data.hook_event_name)" }
+             elseif ($Data.event) { "$($Data.event)" }
+             else { "" }
+Log "Event=$HookEvent"
+
+# Determine instance ID
+$InstanceId = if ($env:MOB_INSTANCE_ID) { $env:MOB_INSTANCE_ID }
+              elseif ($Data.session_id) { "$($Data.session_id)" }
+              else { "ext-$PID" }
+Log "InstanceId=$InstanceId"
+
+$Cwd = if ($Data.cwd) { "$($Data.cwd)" } else { (Get-Location).Path }
+
+# Git branch
+$GitBranch = ""
+try { $GitBranch = git -C "$Cwd" branch --show-current 2>$null } catch {}
+
+# State from event
+$State = switch ($HookEvent) {
+    "SessionStart" { "running" }
+    "SessionEnd"   { "stopped" }
+    "Stop"         { "idle" }
+    "PreToolUse"   { "running" }
+    "PostToolUse"  { "running" }
+    "Notification" { "waiting" }
+    "UserPromptSubmit" { "idle" }
+    default        { "running" }
+}
+Log "State=$State"
+
+$ToolName = if ($Data.tool_name) { "$($Data.tool_name)" } else { "" }
+
+# Extract user prompt from UserPromptSubmit for auto-naming
+# Claude Code sends the prompt in the "prompt" field
+$Topic = ""
+if ($HookEvent -eq "UserPromptSubmit" -and $Data.prompt) {
+    $Topic = ("$($Data.prompt)" -split "`n")[0]
+    if ($Topic.Length -gt 80) { $Topic = $Topic.Substring(0, 80) }
+    Log "Topic=$Topic"
+}
+
+# Task metadata
+$Ticket = ""
+$Subtask = ""
+$Progress = $null
+$TicketStatus = ""
+$TaskFile = Join-Path $Cwd ".mob-task.json"
+if (Test-Path $TaskFile) {
+    $Task = Get-Content $TaskFile | ConvertFrom-Json
+    $Ticket = if ($Task.ticket) { "$($Task.ticket)" } else { "" }
+    $Subtask = if ($Task.subtask) { "$($Task.subtask)" } else { "" }
+    $Progress = $Task.progress
+    $TicketStatus = if ($Task.ticketStatus) { "$($Task.ticketStatus)" } else { "" }
+}
+
+$Timestamp = [long](Get-Date -UFormat %s) * 1000
+
+$Status = @{
+    id = $InstanceId
+    cwd = "$Cwd"
+    gitBranch = "$GitBranch"
+    state = "$State"
+    hookEvent = "$HookEvent"
+    ticket = "$Ticket"
+    ticketStatus = "$TicketStatus"
+    subtask = "$Subtask"
+    currentTool = "$ToolName"
+    lastUpdated = $Timestamp
+    sessionId = "$InstanceId"
+    topic = "$Topic"
+}
+if ($null -ne $Progress) { $Status.progress = $Progress }
+
+$Json = $Status | ConvertTo-Json -Compress
+Log "JSON=$Json"
+
+# Atomic write
+try {
+    $TmpFile = Join-Path $InstancesDir ".tmp.$InstanceId.json"
+    $FinalFile = Join-Path $InstancesDir "$InstanceId.json"
+    $Json | Out-File -FilePath $TmpFile -Encoding UTF8 -NoNewline
+    Move-Item -Force $TmpFile $FinalFile
+    Log "File written OK"
+} catch {
+    Log "File write FAILED: $_"
+}
+
+# Best-effort POST (bypass system proxy, use 127.0.0.1 to avoid IPv6)
+try {
+    $wc = New-Object System.Net.WebClient
+    $wc.Proxy = $null
+    $wc.Headers.Add("Content-Type", "application/json")
+    $wc.UploadString("http://127.0.0.1:${MobPort}/api/hook", $Json) | Out-Null
+    Log "POST OK"
+} catch {
+    Log "POST failed: $_"
+}
+
+# Clean up on stop
+if ($State -eq "stopped") {
+    Start-Job -ScriptBlock {
+        Start-Sleep -Seconds 5
+        Remove-Item -Force $using:FinalFile
+    } | Out-Null
+}
+
+Log "=== Hook finished ==="

package/hooks/mob-status.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Mob status hook for Claude Code
+# Reads hook event from stdin, writes instance status to ~/.mob/instances/{id}.json
+# and POSTs to the dashboard for instant updates.
+
+set -euo pipefail
+
+MOB_DIR="$HOME/.mob"
+INSTANCES_DIR="$MOB_DIR/instances"
+MOB_PORT="${MOB_PORT:-4040}"
+
+mkdir -p "$INSTANCES_DIR"
+
+# Only report for mob-launched instances
+if [ -z "${MOB_INSTANCE_ID:-}" ]; then
+  exit 0
+fi
+
+# Read JSON from stdin
+INPUT=$(cat)
+
+# Determine instance ID
+if [ -n "${MOB_INSTANCE_ID:-}" ]; then
+  INSTANCE_ID="$MOB_INSTANCE_ID"
+else
+  INSTANCE_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
+  if [ -z "$INSTANCE_ID" ]; then
+    INSTANCE_ID="ext-$$"
+  fi
+fi
+
+# Extract fields from hook input
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || pwd)
+[ -z "$CWD" ] && CWD=$(pwd)
+
+# Try to get git branch
+GIT_BRANCH=""
+if command -v git &>/dev/null && [ -d "$CWD/.git" ] || git -C "$CWD" rev-parse --git-dir &>/dev/null 2>&1; then
+  GIT_BRANCH=$(git -C "$CWD" branch --show-current 2>/dev/null || echo "")
+fi
+
+# Determine state from hook event type
+# Claude Code uses hook_event_name, fall back to event for compatibility
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // .event // empty' 2>/dev/null || echo "")
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+case "$HOOK_EVENT" in
+  "SessionStart") STATE="running" ;;
+  "SessionEnd")   STATE="stopped" ;;
+  "Stop")         STATE="idle" ;;
+  "PreToolUse")   STATE="running" ;;
+  "PostToolUse")  STATE="running" ;;
+  "Notification") STATE="waiting" ;;
+  "UserPromptSubmit") STATE="idle" ;;
+  *)              STATE="running" ;;
+esac
+
+# Extract user prompt from UserPromptSubmit for auto-naming
+TOPIC=""
+if [ "$HOOK_EVENT" = "UserPromptSubmit" ]; then
+  RAW_MSG=$(echo "$INPUT" | jq -r '.prompt // .message // empty' 2>/dev/null || echo "")
+  if [ -n "$RAW_MSG" ]; then
+    # Truncate to first 80 chars, first line only
+    TOPIC=$(echo "$RAW_MSG" | head -1 | cut -c1-80)
+  fi
+fi
+
+# Extract session_id from hook input
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
+
+# Read optional task metadata from .mob-task.json in working directory
+TICKET=""
+SUBTASK=""
+PROGRESS=""
+TICKET_STATUS=""
+if [ -f "$CWD/.mob-task.json" ]; then
+  TICKET=$(jq -r '.ticket // empty' "$CWD/.mob-task.json" 2>/dev/null || echo "")
+  SUBTASK=$(jq -r '.subtask // empty' "$CWD/.mob-task.json" 2>/dev/null || echo "")
+  PROGRESS=$(jq -r '.progress // empty' "$CWD/.mob-task.json" 2>/dev/null || echo "")
+  TICKET_STATUS=$(jq -r '.ticketStatus // empty' "$CWD/.mob-task.json" 2>/dev/null || echo "")
+fi
+
+TIMESTAMP=$(date +%s)000
+
+# Build JSON status
+STATUS_JSON=$(cat <<ENDJSON
+{
+  "id": "$INSTANCE_ID",
+  "cwd": "$CWD",
+  "gitBranch": "$GIT_BRANCH",
+  "state": "$STATE",
+  "hookEvent": "$HOOK_EVENT",
+  "ticket": "$TICKET",
+  "ticketStatus": "$TICKET_STATUS",
+  "subtask": "$SUBTASK",
+  "topic": "$TOPIC",
+  $([ -n "$PROGRESS" ] && echo "\"progress\": $PROGRESS," || echo "")
+  "currentTool": "$TOOL_NAME",
+  "lastUpdated": $TIMESTAMP,
+  "sessionId": "${SESSION_ID:-$INSTANCE_ID}"
+}
+ENDJSON
+)
+
+# Atomic write via tmp+rename
+TMP_FILE="$INSTANCES_DIR/.tmp.${INSTANCE_ID}.json"
+echo "$STATUS_JSON" > "$TMP_FILE"
+mv "$TMP_FILE" "$INSTANCES_DIR/${INSTANCE_ID}.json"
+
+# Best-effort POST to dashboard (non-blocking)
+if command -v curl &>/dev/null; then
+  curl -s -X POST "http://localhost:${MOB_PORT}/api/hook" \
+    -H "Content-Type: application/json" \
+    -d "$STATUS_JSON" &>/dev/null &
+fi
+
+# If session ended, clean up the status file after a delay
+if [ "$STATE" = "stopped" ]; then
+  (sleep 5 && rm -f "$INSTANCES_DIR/${INSTANCE_ID}.json") &
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mob-coordinator",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local web dashboard for coordinating multiple Claude Code CLI sessions",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
   "files": [
     "bin/",
     "dist/",
+    "hooks/",
     "scripts/postinstall.cjs",
     "package.json",
     "README.md"