tanuki-telemetry 1.4.0 → 1.4.1

package/install.sh

@@ -7,7 +7,7 @@ set -e
 
 TANUKI_DIR="${TANUKI_DIR:-$HOME/.claude/mcp-servers/telemetry}"
 DATA_DIR="${DATA_DIR:-$HOME/.tanuki/data}"
-VERSION="1.1.0"
+VERSION="1.4.0"
 
 echo ""
 echo "  ┌─────────────────────────┐"
@@ -15,8 +15,8 @@ echo "  │  TANUKI  //  v${VERSION}     │"
 echo "  └─────────────────────────┘"
 echo ""
 
-# Check prerequisites
-command -v docker >/dev/null 2>&1 || { echo "Error: docker is required. Install Docker Desktop first."; exit 1; }
+# Check prerequisites (Node only — no Docker required)
+command -v node >/dev/null 2>&1 || { echo "Error: node is required. Install Node.js 18+ first."; exit 1; }
 command -v git >/dev/null 2>&1 || { echo "Error: git is required."; exit 1; }
 
 # Clone or update
@@ -27,58 +27,90 @@ if [ -d "$TANUKI_DIR/.git" ]; then
 else
   echo "[1/4] Cloning tanuki..."
   mkdir -p "$(dirname "$TANUKI_DIR")"
-  git clone https://github.com/anthropics/tanuki-telemetry.git "$TANUKI_DIR" 2>/dev/null || {
+  git clone https://github.com/ykim-24/tanuki-telemetry.git "$TANUKI_DIR" 2>/dev/null || {
     echo "  Repo not accessible — using local copy"
   }
 fi
 
 cd "$TANUKI_DIR"
 
-# Create data directory
-mkdir -p "$DATA_DIR"
+# Create data directories
+mkdir -p "$DATA_DIR/screenshots"
+mkdir -p "$DATA_DIR/artifacts"
+mkdir -p "$DATA_DIR/walkthrough-screenshots"
 
-# Build Docker images
-echo "[2/4] Building Docker images..."
-docker build -t telemetry-mcp:latest -t telemetry-dashboard:latest . -q
+# Install and build
+echo "[2/4] Building..."
+npm ci --silent 2>/dev/null || npm install --silent
+npm run build
 
-# Stop existing dashboard if running
+# Start dashboard (native Node, no Docker)
 echo "[3/4] Starting dashboard..."
-docker rm -f telemetry-dashboard 2>/dev/null || true
-docker run -d --rm \
-  --name telemetry-dashboard \
-  -p 3333:3333 \
-  -v "$DATA_DIR:/data" \
-  telemetry-dashboard:latest
+chmod +x start-dashboard.sh
+DATA_DIR="$DATA_DIR" ./start-dashboard.sh stop 2>/dev/null || true
+DATA_DIR="$DATA_DIR" ./start-dashboard.sh start
 
-# Configure Claude Code MCP
-echo "[4/4] Configuring Claude Code..."
+# Install skills
+echo "[4/5] Installing skills..."
+mkdir -p "$HOME/.claude/commands" "$HOME/.claude/scripts"
+for cmd in skills/commands/*.md; do
+  [ -f "$cmd" ] && cp "$cmd" "$HOME/.claude/commands/" && echo "  ✓ $(basename "$cmd")"
+done
+for script in skills/scripts/*; do
+  [ -f "$script" ] && cp "$script" "$HOME/.claude/scripts/" && chmod +x "$HOME/.claude/scripts/$(basename "$script")" && echo "  ✓ $(basename "$script")"
+done
+
+# Configure Claude Code MCP (native Node, no Docker)
+echo "[5/5] Configuring Claude Code..."
 CLAUDE_CONFIG="$HOME/.claude.json"
 if [ -f "$CLAUDE_CONFIG" ]; then
-  # Check if telemetry MCP is already configured
   if grep -q '"telemetry"' "$CLAUDE_CONFIG" 2>/dev/null; then
-    echo "  MCP already configured in .claude.json"
+    # Update to native mode
+    python3 -c "
+import json
+with open('$CLAUDE_CONFIG', 'r') as f:
+    config = json.load(f)
+config['mcpServers']['telemetry'] = {
+    'type': 'stdio',
+    'command': 'node',
+    'args': ['$TANUKI_DIR/dist/index.js'],
+    'env': {'DATA_DIR': '$DATA_DIR'}
+}
+with open('$CLAUDE_CONFIG', 'w') as f:
+    json.dump(config, f, indent=2)
+"
+    echo "  ✓ Updated MCP config to native mode"
   else
-    echo "  Add this to your .claude.json mcpServers:"
-    echo ""
-    echo '  "telemetry": {'
-    echo '    "type": "stdio",'
-    echo '    "command": "docker",'
-    echo '    "args": ["run", "--rm", "-i", "-v", "'$DATA_DIR':/data", "--entrypoint", "node", "telemetry-mcp:latest", "dist/index.js"]'
-    echo '  }'
-    echo ""
+    python3 -c "
+import json
+with open('$CLAUDE_CONFIG', 'r') as f:
+    config = json.load(f)
+if 'mcpServers' not in config:
+    config['mcpServers'] = {}
+config['mcpServers']['telemetry'] = {
+    'type': 'stdio',
+    'command': 'node',
+    'args': ['$TANUKI_DIR/dist/index.js'],
+    'env': {'DATA_DIR': '$DATA_DIR'}
+}
+with open('$CLAUDE_CONFIG', 'w') as f:
+    json.dump(config, f, indent=2)
+"
+    echo "  ✓ Added telemetry MCP to .claude.json"
   fi
 else
-  echo "  No .claude.json found — create one with:"
+  echo "  Add this to your .claude.json:"
   echo ""
-  echo '  { "mcpServers": { "telemetry": { "type": "stdio", "command": "docker", "args": ["run", "--rm", "-i", "-v", "'$DATA_DIR':/data", "--entrypoint", "node", "telemetry-mcp:latest", "dist/index.js"] } } }'
+  echo "  \"mcpServers\": { \"telemetry\": { \"type\": \"stdio\", \"command\": \"node\", \"args\": [\"$TANUKI_DIR/dist/index.js\"], \"env\": { \"DATA_DIR\": \"$DATA_DIR\" } } }"
   echo ""
 fi
 
-# Wait for dashboard to start
+# Verify
 sleep 2
-if curl -s http://localhost:3333/health | grep -q '"ok":true'; then
+if curl -s http://localhost:3333/health 2>/dev/null | grep -q '"ok":true'; then
   echo ""
-  echo "  Tanuki is running at http://localhost:3333"
+  echo "  ✓ Tanuki is running at http://localhost:3333"
+  echo "  ✓ Restart Claude Code to connect the MCP server"
   echo ""
 else
   echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanuki-telemetry",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Workflow monitor and telemetry dashboard for Claude Code autonomous agents",
   "type": "module",
   "bin": {

package/skills/commands/compare-image.md

@@ -0,0 +1,414 @@
+# Compare Image — Visual Diff with Qualitative Annotations
+
+Compare two sets of images (reference vs actual) with pixel-diff heatmaps and qualitative callouts. Works for any before/after image comparison: UI screenshots, design mockups, rendered templates, chart output, etc.
+
+## Usage
+
+```
+/compare-image <ref-dir> <actual-dir>
+/compare-image ./mockups ./screenshots
+/compare-image --ref ./expected --actual ./output --session-id=<existing-session>
+/compare-image --ref ./v1-screenshots --actual ./v2-screenshots --output-dir=./diffs
+```
+
+**Arguments:**
+- `ref-dir`: Directory containing reference (expected) images — PNGs, numbered or named.
+- `actual-dir`: Directory containing actual (generated/current) images to compare against.
+- `--session-id=<id>`: Attach to an existing telemetry session instead of creating a new one.
+- `--output-dir=<path>`: Override output directory (default: `$TANUKI_OUTPUTS/comparisons/`)
+- `--label=<name>`: Label for this comparison set (default: derived from directory names).
+
+---
+
+## Prerequisites
+
+- **Python packages:** `fitz` (PyMuPDF — only if comparing PDFs), `PIL` (Pillow), `numpy`
+- **agent-browser** via `npx agent-browser` (only if capturing live screenshots)
+
+---
+
+## Workflow
+
+### Phase 1: Setup & Discovery
+
+1. **Parse arguments** — extract directories and flags.
+2. **Create telemetry session** (unless `--session-id` provided):
+   ```
+   mcp__telemetry__log_session_start({ worktree_name: "image-comparison-<date>" })
+   ```
+3. **Discover image pairs** — match reference and actual images by filename or index:
+   - Sort both directories by filename
+   - Pair them 1:1 (ref-01.png ↔ actual-01.png, or by matching name stems)
+   - Report any unmatched images
+4. **Log event** with pair count and any mismatches.
+
+### Phase 2: Prepare Reference Images
+
+Depending on your source format, prepare reference PNGs:
+
+- **Already PNGs:** Use directly — no conversion needed.
+- **From PDF:** Render pages to PNGs via PyMuPDF:
+  ```python
+  import fitz
+  doc = fitz.open(pdf_path)
+  for i, page in enumerate(doc):
+      zoom = 1920 / page.rect.width
+      mat = fitz.Matrix(zoom, zoom)
+      pix = page.get_pixmap(matrix=mat)
+      pix.save(f'ref/image-{i+1:02d}.png')
+  ```
+- **From live URL:** Capture with agent-browser:
+  ```bash
+  npx agent-browser --url "http://localhost:3000/page" --width 1920 --height 1080 --output ref/page.png
+  ```
+
+### Phase 3: Prepare Actual Images
+
+Same as Phase 2 — get actual/generated images as PNGs by whatever method fits your use case (screenshots, renders, exports, etc.).
+
+### Phase 4: Qualitative Analysis (visual review)
+
+For each image pair, **read both images** and identify every meaningful difference. Think of this as a visual code review — call out specifics, not just "things changed."
+
+| Category | What to look for |
+|----------|-----------------|
+| **Layout** | Element positioning, spacing, alignment, column/grid structure |
+| **Text** | Content differences, missing text, placeholder values, truncation |
+| **Images/icons** | Missing assets, wrong variants, broken renders, placeholder boxes |
+| **Color/style** | Background, accent colors, borders, gradients, opacity |
+| **Typography** | Font size, weight, color, line height changes |
+| **Data** | Missing values, wrong numbers, empty states |
+| **Chrome/UI** | Headers, footers, navigation, page numbers, timestamps |
+
+**Severity classification:**
+- **CRITICAL** (red): Missing content, broken layout, data that should exist but doesn't
+- **NOTABLE** (yellow): Important differences — content changes, removed elements, placeholder values
+- **MINOR** (blue): Rendering differences — font antialiasing, sub-pixel spacing, minor color shifts
+- **GOOD** (green): Things that match correctly — always include at least one positive finding per pair
+
+Build a `callouts` list for each pair: `[{severity, title, details}]` (max 4 per image).
+
+### Phase 5: Generate Comparison Images
+
+Each comparison image has three columns plus qualitative callout boxes.
+
+**Layout:**
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Title: "Page 3 — Dashboard"                              [DIFF 18.2%] │
+├────────────────────────┬──────────────────────┬──────────────────────────┤
+│  REFERENCE             │  PIXEL DIFF HEATMAP  │  ACTUAL                  │
+│  (Expected)            │  (red = changes)     │  (Current)               │
+│  [green border]        │  [red border]        │  [blue border]           │
+│  [533x450]             │  [533x450]           │  [533x450]              │
+├────────────────────────┴──────────────────────┴──────────────────────────┤
+│  DIFFERENCES:                                                            │
+│  ┌─CRITICAL────────┐ ┌─NOTABLE─────────┐ ┌─MINOR──────────┐ ┌─GOOD───┐│
+│  │ Title           │ │ Title           │ │ Title          │ │ Title   ││
+│  │ Details...      │ │ Details...      │ │ Details...     │ │ Details ││
+│  └─────────────────┘ └─────────────────┘ └────────────────┘ └─────────┘│
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+**Python implementation** (Pillow + numpy):
+
+```python
+from PIL import Image, ImageDraw, ImageFont, ImageFilter
+import numpy as np
+
+# --- Constants ---
+COL_W, COL_H = 533, 450   # 3 equal columns
+CALLOUT_H = 170
+PAD = 20
+
+COLORS = {
+    "critical": ((200, 40, 40), (255, 80, 80)),
+    "notable":  ((180, 130, 0), (255, 200, 50)),
+    "minor":    ((60, 130, 180), (100, 180, 240)),
+    "good":     ((40, 150, 40), (80, 200, 80)),
+}
+
+try:
+    FONT_TITLE   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 28)
+    FONT_LABEL   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 18)
+    FONT_CALLOUT = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 14)
+    FONT_SMALL   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 12)
+except Exception:
+    FONT_TITLE = FONT_LABEL = FONT_CALLOUT = FONT_SMALL = ImageFont.load_default()
+
+
+def normalize_to_size(img, target_w, target_h, bg_color=(255, 255, 255)):
+    """
+    Scale image to fit within target_w x target_h preserving aspect ratio,
+    then center it on a background. No stretching, no black bars.
+    """
+    img_w, img_h = img.size
+    scale = min(target_w / img_w, target_h / img_h)
+    new_w = int(img_w * scale)
+    new_h = int(img_h * scale)
+    scaled = img.resize((new_w, new_h), Image.LANCZOS)
+
+    canvas = Image.new("RGB", (target_w, target_h), bg_color)
+    offset_x = (target_w - new_w) // 2
+    offset_y = (target_h - new_h) // 2
+    canvas.paste(scaled, (offset_x, offset_y))
+    return canvas
+
+
+def compute_diff_heatmap(ref, gen, threshold=25):
+    """
+    Compute a red pixel-diff heatmap overlaid on the actual image.
+    Returns (overlay_image, diff_percentage).
+    """
+    ref_arr = np.array(ref.convert("RGB"), dtype=np.float32)
+    gen_arr = np.array(gen.convert("RGB"), dtype=np.float32)
+    diff = np.abs(ref_arr - gen_arr).mean(axis=2)  # grayscale diff per pixel
+
+    diff_pct = (diff > threshold).sum() / diff.size * 100
+
+    # Normalize diff to 0-255 intensity
+    diff_norm = np.clip(diff * (255 / max(diff.max(), 1)), 0, 255).astype(np.uint8)
+
+    # Create red overlay: high-diff pixels get bright red, low-diff transparent
+    overlay_rgba = np.zeros((*diff_norm.shape, 4), dtype=np.uint8)
+    mask = diff_norm > threshold
+    overlay_rgba[mask, 0] = 255                          # R
+    overlay_rgba[mask, 1] = 0                            # G
+    overlay_rgba[mask, 2] = 0                            # B
+    overlay_rgba[mask, 3] = np.clip(diff_norm[mask], 60, 180)  # A (semi-transparent)
+
+    red_overlay = Image.fromarray(overlay_rgba, mode="RGBA")
+    heatmap = Image.alpha_composite(gen.convert("RGBA"), red_overlay).convert("RGB")
+
+    return heatmap, diff_pct
+
+
+def create_comparison(ref_path, gen_path, out_path, label, callouts):
+    """
+    Generate a full comparison image with 3 columns side by side:
+    REFERENCE | HEATMAP | ACTUAL — all same height, equal width.
+    Plus qualitative callout boxes below.
+    """
+    ref = normalize_to_size(Image.open(ref_path), COL_W, COL_H)
+    gen = normalize_to_size(Image.open(gen_path), COL_W, COL_H)
+
+    heatmap, diff_pct = compute_diff_heatmap(ref, gen)
+    heatmap_col = heatmap
+
+    content_w = COL_W * 3 + PAD * 4
+    total_h = PAD + 40 + 24 + COL_H + PAD + 24 + CALLOUT_H + PAD
+    canvas = Image.new("RGB", (content_w, total_h), (25, 25, 25))
+    draw = ImageDraw.Draw(canvas)
+
+    y = PAD
+
+    # --- Title bar + diff badge ---
+    draw.text((PAD, y), label, fill=(255, 255, 255), font=FONT_TITLE)
+    badge_text = f"DIFF {diff_pct:.1f}%"
+    if diff_pct < 5:
+        badge_color = (40, 150, 40)
+    elif diff_pct < 20:
+        badge_color = (180, 130, 0)
+    else:
+        badge_color = (200, 40, 40)
+    badge_x = content_w - PAD - 140
+    draw.rectangle([badge_x, y, badge_x + 130, y + 30], fill=badge_color)
+    draw.text((badge_x + 8, y + 6), badge_text, fill=(255, 255, 255), font=FONT_LABEL)
+    y += 44
+
+    # --- Column labels ---
+    col1_x = PAD
+    col2_x = PAD * 2 + COL_W
+    col3_x = PAD * 3 + COL_W * 2
+    draw.text((col1_x, y), "REFERENCE (Expected)", fill=(140, 200, 140), font=FONT_LABEL)
+    draw.text((col2_x, y), "PIXEL DIFF HEATMAP", fill=(200, 120, 120), font=FONT_LABEL)
+    draw.text((col3_x, y), "ACTUAL (Current)", fill=(140, 160, 240), font=FONT_LABEL)
+    y += 24
+
+    # --- 3 images side by side ---
+    canvas.paste(ref, (col1_x, y))
+    canvas.paste(heatmap_col, (col2_x, y))
+    canvas.paste(gen, (col3_x, y))
+    draw.rectangle([col1_x - 1, y - 1, col1_x + COL_W, y + COL_H], outline=(100, 200, 100), width=2)
+    draw.rectangle([col2_x - 1, y - 1, col2_x + COL_W, y + COL_H], outline=(200, 60, 60), width=2)
+    draw.rectangle([col3_x - 1, y - 1, col3_x + COL_W, y + COL_H], outline=(100, 120, 240), width=2)
+    y += COL_H + PAD
+
+    # --- Callout boxes ---
+    draw.text((PAD, y), "DIFFERENCES:", fill=(220, 220, 220), font=FONT_LABEL)
+    y += 24
+    num = min(len(callouts), 4)
+    if num > 0:
+        box_w = (content_w - PAD * (num + 1)) // num
+        box_h = CALLOUT_H - 30
+        for i, c in enumerate(callouts[:4]):
+            bx = PAD + i * (box_w + PAD)
+            bg, accent = COLORS.get(c["severity"], COLORS["minor"])
+            draw.rectangle([bx, y, bx + box_w, y + box_h], fill=(40, 40, 40), outline=accent, width=2)
+            draw.rectangle([bx + 2, y + 2, bx + 80, y + 20], fill=bg)
+            draw.text((bx + 6, y + 3), c["severity"].upper(), fill=(255, 255, 255), font=FONT_SMALL)
+            draw.text((bx + 8, y + 24), c["title"], fill=accent, font=FONT_CALLOUT)
+            # Wrap details text
+            words = c["details"].split()
+            lines, current = [], ""
+            for w in words:
+                test = f"{current} {w}".strip()
+                bbox = draw.textbbox((0, 0), test, font=FONT_SMALL)
+                if bbox[2] - bbox[0] > box_w - 16 and current:
+                    lines.append(current)
+                    current = w
+                else:
+                    current = test
+            if current:
+                lines.append(current)
+            for j, line in enumerate(lines[:4]):
+                draw.text((bx + 8, y + 42 + j * 16), line, fill=(200, 200, 200), font=FONT_SMALL)
+
+    canvas.save(out_path, quality=95)
+    return diff_pct
+```
+
+### Phase 6: Upload to Telemetry (structured findings)
+
+Each image comparison produces telemetry artifacts: a screenshot, structured finding events per callout, and an image-level summary event.
+
+#### 6a. Screenshots per image pair
+
+**The comparison image is always the primary output:**
+```
+mcp__telemetry__log_screenshot({
+  session_id,
+  phase: "verification",
+  description: "[COMPARISON] <label> <N> — <highest severity>: <key finding>",
+  file_path: "<absolute path to comparison PNG>"
+})
+```
+
+Also log as an artifact for download/browsing on the dashboard:
+```
+mcp__telemetry__log_artifact({
+  session_id,
+  file_path: "<absolute path to comparison PNG>",
+  artifact_type: "comparison",
+  description: "<label> image <N> comparison",
+  metadata: { label: "<label>", image_number: <N>, diff_pct: <X.X> }
+})
+```
+
+#### 6b. Structured finding event per callout
+
+For **each individual finding**, log a `comparison_finding` event with queryable metadata:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "verification",
+  event_type: "info",
+  message: "<severity>: <title> — <label> image <N>",
+  metadata: {
+    type: "comparison_finding",
+    label: "<label>",
+    image_number: <N>,
+    image_name: "<filename>",
+    severity: "<critical|notable|minor|good>",
+    finding_title: "<short title>",
+    finding_details: "<full description>",
+    diff_pct: <X.X>,
+    comparison_image: "<absolute path>",
+    ref_image: "<absolute path>",
+    actual_image: "<absolute path>"
+  }
+})
+```
+
+#### 6c. Image-level summary event
+
+After logging all findings for an image pair:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "verification",
+  event_type: "info",
+  message: "Compared <label> image <N> (<name>) — <highest severity>, diff <X.X>%",
+  metadata: {
+    type: "comparison_image_summary",
+    label: "<label>",
+    image_number: <N>,
+    image_name: "<filename>",
+    diff_pct: <X.X>,
+    highest_severity: "<critical|notable|minor|good>",
+    finding_count: { critical: <N>, notable: <N>, minor: <N>, good: <N> },
+    comparison_image: "<absolute path>"
+  }
+})
+```
+
+#### 6d. Final rollup event
+
+After all image pairs:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "deliverables",
+  event_type: "info",
+  message: "Image comparison complete — <N> images, <C> critical, <N> notable findings",
+  metadata: {
+    type: "comparison_rollup",
+    label: "<label>",
+    total_images: <N>,
+    total_findings: <N>,
+    by_severity: { critical: <N>, notable: <N>, minor: <N>, good: <N> },
+    avg_diff_pct: <X.X>
+  }
+})
+```
+
+#### Querying findings programmatically
+
+```sql
+-- All critical findings across sessions
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_finding'
+  AND metadata->>'severity' = 'critical';
+
+-- All findings for a specific comparison
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_finding'
+  AND metadata->>'label' = 'homepage-redesign';
+
+-- Image summaries sorted by diff percentage
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_image_summary'
+ORDER BY (metadata->>'diff_pct')::float DESC;
+```
+
+### Phase 7: Summary Output
+
+```markdown
+## Image Comparison Results
+
+| Image | Diff % | Severity | Key Finding |
+|-------|:------:|----------|-------------|
+| 01 — Homepage | 12.3% | NOTABLE | Header layout shifted, CTA button color changed |
+| 02 — Dashboard | 18.2% | CRITICAL | Chart data missing, sidebar collapsed |
+| ... | ... | ... | ... |
+
+**Critical:** <count> images
+**Notable:** <count> images
+**Good:** <count> images
+
+**Output:** <output-dir>/comparisons/
+**Telemetry:** Session <id>
+```
+
+---
+
+## Common Use Cases
+
+- **UI regression testing:** Compare screenshots before/after a code change
+- **Design fidelity:** Compare design mockup PNGs against implemented page screenshots
+- **Generated content:** Compare expected output against LLM/AI-generated output
+- **Email templates:** Compare HTML email reference renders against actual sends
+- **Chart/data viz:** Compare expected chart renders against actual output

package/skills/commands/coordinate.md

@@ -0,0 +1,283 @@
+---
+description: |
+  Central coordinator mode. Become the hub that manages all cmux workspaces — dispatch work, monitor progress, and persist state across conversations.
+  Use this to initialize or resume a coordinator session.
+allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, mcp__telemetry__*, mcp__linear__*
+---
+
+# Coordinate — Central Workspace Coordinator
+
+## Role
+
+You are the **central coordinator**. The user talks to you, and you manage all cmux workspaces. You do NOT write code directly — you dispatch, monitor, and integrate.
+
+## ⛔ CRITICAL RULES
+
+1. **You are the hub.** All communication to other workspaces goes through you via `cmux send` + `cmux send-key Enter`.
+2. **Be concise.** Don't dump raw screen output. Summarize what's happening in each workspace.
+3. **Protect context.** This is your biggest constraint. Minimize context usage by:
+   - Summarizing `cmux read-screen` output instead of showing it raw
+   - Using `mcp__telemetry__get_session_summary` instead of screen reads when possible
+   - Periodically compacting state (see Phase 3)
+4. **Persist state.** Save coordinator state to telemetry so you can resume across conversations.
+5. **Be proactive.** After dispatching work, monitor it without being asked. Alert the user when workspaces finish or hit errors.
+6. **Always target the Claude surface.** Run `/cmux-guide` if unsure about any cmux operation. Key rules: never omit `--surface`, use full `"workspace:N"` IDs for new workspaces, always discover surfaces before interacting. See "Surface Discovery" below.
+7. **⛔ LOG EVERYTHING TO THE LIVE FEED.** Every dispatch, every monitor check, every status change, every decision — call `mcp__telemetry__log_event` immediately. The dashboard live feed is useless without constant logging. If you did something and didn't log it, go back and log it now. Target 5+ events per user interaction. Use these event types:
+   - `action` — dispatched work, checked workspace, created workspace
+   - `decision` — chose which workspace, prioritized a task, skipped something
+   - `info` — status update, workspace completed, workspace idle
+   - `error` — workspace failed, send failed, workspace unreachable
+8. **⛔ SYNC STATE AFTER EVERY CHANGE.** Call `save_coordinator_state` after EVERY workspace status change, dispatch, or completion — not just "every 5-10 interactions". The dashboard reads state directly. Stale state = stale dashboard.
+
+---
+
+## Phase 1: Initialize
+
+### If resuming (default — check for prior state first):
+```
+state = mcp__telemetry__get_coordinator_state()
+```
+If state exists:
+- Load workspace statuses, pending tasks, decisions
+- Run `cmux list-workspaces` to verify what's actually running
+- Reconcile (workspaces may have changed since last session)
+- Present a brief status update to the user
+
+### If fresh start:
+```
+cmux list-workspaces
+```
+- Map all active workspaces
+- Create coordinator state:
+```
+mcp__telemetry__save_coordinator_state({
+  session_id: "<generated-id>",
+  state: {
+    workspaces: { ... },
+    pending_tasks: [],
+    decisions: [],
+    notes: ""
+  }
+})
+```
+- Present workspace map to user
+
+---
+
+## Surface Discovery
+
+Workspaces often have multiple surfaces (panes) — Claude terminals, web browsers, dev servers, idle shells. **You must always identify and target the Claude surface** for reads and sends.
+
+### How to discover surfaces
+```bash
+cmux list-pane-surfaces --workspace <id>
+```
+This returns all surfaces in a workspace. Identify the Claude surface by:
+- Label contains "Claude Code"
+- When read, shows the `❯` prompt with `bypass permissions` text
+- NOT a browser (URL in label), NOT a dev server (logs), NOT "idle"
+
+### Cache surface IDs
+Store the Claude surface ID per workspace in coordinator state:
+```json
+{
+  "workspace:1": { "name": "Telemetry MCP", "status": "idle", "claude_surface": "surface:2" },
+  "workspace:5": { "name": "CDD Slides", "status": "idle", "claude_surface": "surface:7" }
+}
+```
+
+### Always use `--surface`
+**Every** `read-screen`, `send`, and `send-key` command MUST include `--surface <surface_id>`:
+```bash
+cmux read-screen --workspace <id> --surface <surface_id> --lines 10
+cmux send --workspace <id> --surface <surface_id> "<text>"
+cmux send-key --workspace <id> --surface <surface_id> Enter
+```
+
+### When to re-discover
+- On initialization (Phase 1) — discover all surfaces for all workspaces
+- After creating a new workspace
+- If a `read-screen` or `send` returns an error or unexpected content (browser HTML, ASCII art, server logs)
+- If a surface ID returns "Surface is not a terminal" error
+
+### During Phase 1 initialization
+After `cmux list-workspaces`, run `cmux list-pane-surfaces --workspace <id>` for **every** workspace. Build the full surface map before presenting status.
+
+---
+
+## Phase 2: Active Coordination
+
+### Creating new workspaces
+When spinning up a new workspace:
+1. `cmux new-workspace --cwd <path> --command "claude"` — creates the workspace
+2. **Immediately rename it:** `cmux rename-workspace --workspace <id> "<descriptive-name>"`
+3. Discover surfaces: `cmux list-pane-surfaces --workspace <id>`
+4. Cache the Claude surface ID in coordinator state
+
+### Forwarding messages verbatim
+When the user sends a message via `/speak` that is clearly intended for a workspace (e.g., instructions, corrections, feedback), forward it **verbatim** — copy their exact text. Do NOT paraphrase, summarize, or reinterpret. The user chose their words deliberately.
+
+### Dispatching work
+When the user asks you to send work to a workspace:
+1. Get the Claude surface from state (or discover via `cmux list-pane-surfaces` if not cached)
+2. Check if workspace is idle: `cmux read-screen --workspace <id> --surface <claude_surface> --lines 5`
+3. If busy, add to `pending_tasks` in state and tell the user
+4. If idle, send via: `cmux send --workspace <id> --surface <claude_surface> "<message>"` then `cmux send-key --workspace <id> --surface <claude_surface> Enter`
+4. Log the dispatch to telemetry:
+```
+mcp__telemetry__log_event({
+  session_id: coordinator_session_id,
+  phase: "coordination",
+  event_type: "action",
+  message: "Dispatched to <workspace-name>: <summary>",
+  metadata: { workspace: "<id>", full_message: "<what was sent>" }
+})
+```
+5. Update workspace status in state
+
+### Monitoring
+When checking on workspaces:
+- **Prefer telemetry over screen reads** — `get_session_summary` is cheaper on context
+- **Screen reads for non-telemetry workspaces** — always use `--surface <claude_surface>`: `cmux read-screen --workspace <id> --surface <claude_surface> --lines 10` (not 40+)
+- **If read returns unexpected content** (HTML, ASCII art, server logs, "Surface is not a terminal") — you're on the wrong surface. Re-discover with `cmux list-pane-surfaces`
+- **Summarize aggressively** — "Telemetry MCP: building screenshot thumbnails, 3min in" not the full output
+- **⛔ Log EVERY monitor check:**
+```
+mcp__telemetry__log_event({
+  session_id: coordinator_session_id,
+  phase: "coordination",
+  event_type: "info",
+  message: "<workspace-name>: <what you observed>",
+  metadata: { workspace: "<id>", status: "<idle|working|done|failed>" }
+})
+```
+- After monitoring, update state AND call `save_coordinator_state` immediately
+
+### Session Linking (for live feed)
+The telemetry dashboard live feed shows events from all workspace sessions — but ONLY if the coordinator state has their `session_id` linked. **You must actively link sessions.**
+
+After dispatching `/start-work` to a workspace:
+1. Wait ~30 seconds for the session to be created
+2. Run `mcp__telemetry__list_sessions({ status: "in_progress", limit: 5 })`
+3. Match the new session to the workspace by worktree name
+4. Update coordinator state with the `session_id` on that workspace
+
+**Periodically re-link:** Every 5-10 interactions, run `list_sessions` and reconcile — new sessions may have been created, old ones may have completed.
+
+Without this linking, the coordinator live feed will be empty even though workspaces are logging events.
+
+### Responding to the user
+- Lead with the answer, not the process
+- Use tables for multi-workspace status
+- Don't repeat what the user said
+
+### Intent Routing (auto-detect workspace)
+
+The user will often just say what they want without naming a workspace. **You must infer the target workspace** from context. Do NOT ask "which workspace?" unless genuinely ambiguous.
+
+**Routing priority:**
+1. **Explicit name** — user says "telemetry" or "slides" → direct match
+2. **Topic match** — match keywords to workspace descriptions in state:
+   - Screenshots, dashboard, events, sessions, thumbnails → Telemetry MCP
+   - Slides, generation, template, PPTX, quality score → Slide Generation
+   - Database, JWT, auth, migration → DB Migration
+   - (Update these mappings as workspaces change)
+3. **Recency** — if user just saw output from a workspace and responds, it's about that workspace
+4. **Active work** — if only one workspace is actively working, comments about "it" or "that" refer to it
+5. **Ambiguous** — only ask if 2+ workspaces are equally likely. Present as numbered options:
+   ```
+   That could be about:
+   1. Telemetry MCP (working on thumbnails)
+   2. Slide Generation (idle, last worked on quality)
+   Which one?
+   ```
+
+**Build the keyword map from workspace state.** When saving state, include a `topics` array per workspace:
+```json
+{
+  "workspace:1": { "name": "Telemetry MCP", "topics": ["telemetry", "dashboard", "screenshots", "events", "sessions", "MCP"] },
+  "workspace:4": { "name": "Slide Generation", "topics": ["slides", "pptx", "generation", "template", "quality"] }
+}
+```
+
+**The user should feel like they're just talking, and messages magically go to the right place.**
+
+---
+
+## Phase 3: Context Management
+
+### Periodic state saves
+After EVERY workspace status change, save state immediately. At minimum every 2-3 interactions:
+```
+mcp__telemetry__save_coordinator_state({
+  session_id: coordinator_session_id,
+  state: { workspaces: {...}, pending_tasks: [...], decisions: [...], notes: "..." }
+})
+```
+
+### When context is getting heavy
+Signs: conversation is long, lots of screen reads accumulated, you're near context limits.
+
+1. Save everything important:
+```
+mcp__telemetry__compact_coordinator_context({
+  session_id: coordinator_session_id,
+  context: {
+    summary: "<what happened this conversation>",
+    decisions: ["<key decisions made>"],
+    workspace_states: { ... },
+    pending_work: ["<things still to do>"],
+    user_preferences_learned: ["<any new preferences>"]
+  }
+})
+```
+2. Tell the user: "Context is getting heavy. I've saved state — you can start a fresh `/coordinate` and I'll pick up where we left off."
+3. The user starts a new conversation and runs `/coordinate` — Phase 1 loads the saved state.
+
+---
+
+## Phase 4: Pending Task Management
+
+When a workspace finishes and has pending tasks:
+1. Check the workspace is actually idle
+2. Send the next pending task
+3. Remove from pending list
+4. Update state
+
+When the user queues something for a busy workspace:
+1. Add to `pending_tasks` with workspace ID and message
+2. Confirm: "Queued for <workspace-name> — will send when it's free"
+3. Check periodically if it's free
+
+---
+
+## Workspace Command Reference
+
+```bash
+cmux list-workspaces                                                    # see all workspaces
+cmux list-pane-surfaces --workspace <id>                                # list all surfaces in a workspace
+cmux read-screen --workspace <id> --surface <surface_id> --lines 10    # check output (ALWAYS use --surface)
+cmux send --workspace <id> --surface <surface_id> "<text>"             # send message (ALWAYS use --surface)
+cmux send-key --workspace <id> --surface <surface_id> Enter            # press Enter (ALWAYS use --surface)
+cmux new-workspace --cwd <path> --command "claude"                     # spawn new workspace
+cmux rename-workspace --workspace <id> "<name>"                        # rename a workspace
+cmux notify "<message>"                                                # macOS notification
+```
+
+**⚠️ Never omit `--surface`.** Bare commands without `--surface` will target whatever surface is "selected" — which may be a browser, dev server, or idle shell, not Claude.
+
+**⚠️ Always name new workspaces.** After `cmux new-workspace`, immediately run `cmux rename-workspace --workspace <id> "<descriptive-name>"`. Unnamed workspaces show as "Claude Code" which is useless.
+
+---
+
+## On Conversation Start
+
+Always begin with:
+1. Load prior coordinator state (or initialize fresh)
+2. `cmux list-workspaces` to get current workspace map
+3. `cmux list-pane-surfaces --workspace <id>` for **every** workspace — build the surface map
+4. Identify the Claude surface in each workspace (label contains "Claude Code", or read to verify)
+5. Cache `claude_surface` per workspace in coordinator state
+6. Quick status check on active workspaces (using `--surface` for all reads)
+7. Present status table to user (include surface IDs for reference)
+8. Ask: "What should we work on?" (or pick up pending tasks)

package/skills/commands/live-browser.md

@@ -0,0 +1,45 @@
+---
+description: |
+  Launch agent-browser in headed (visible) mode so you can watch it work in real time.
+  Use when you want to see what agent-browser is doing — demos, debugging, or verification.
+allowed-tools: Bash
+---
+
+# /live-browser — Watch Agent Browser Live
+
+Toggles agent-browser between headed (visible) and headless modes.
+
+## Usage
+
+- `/live-browser` or `/live-browser on` — Enable headed mode (browser window visible)
+- `/live-browser off` — Disable headed mode (back to headless)
+- `/live-browser status` — Check current mode
+
+## On Invoke
+
+Parse the argument (default: "on").
+
+### Enable (on)
+```bash
+# Set env for current session
+export AGENT_BROWSER_HEADED=1
+echo "AGENT_BROWSER_HEADED=1" >> ~/.claude/.env 2>/dev/null
+echo "✓ Agent browser is now in HEADED mode — you'll see the Chrome window"
+echo "  Note: The browser will take focus when agent-browser runs"
+```
+
+### Disable (off)
+```bash
+unset AGENT_BROWSER_HEADED
+sed -i '' '/AGENT_BROWSER_HEADED/d' ~/.claude/.env 2>/dev/null
+echo "✓ Agent browser is back to HEADLESS mode"
+```
+
+### Status
+```bash
+if [ "$AGENT_BROWSER_HEADED" = "1" ]; then
+  echo "Mode: HEADED (visible browser window)"
+else
+  echo "Mode: HEADLESS (no visible window)"
+fi
+```

package/skills/commands/marathon.md

@@ -0,0 +1,111 @@
+---
+description: |
+  Autonomous workspace monitoring. Checks inbox + workspace screens on a recurring interval and takes action when sessions complete — dispatches queued work, restarts stalled sessions, reports status.
+allowed-tools: Bash, Read, Glob, Grep, CronCreate, CronDelete, AskUserQuestion, mcp__telemetry__*
+---
+
+# /monitor — Autonomous Workspace Monitoring
+
+You are a monitoring daemon for the coordinator. You check workspace status periodically and take action when needed.
+
+## Arguments
+
+- No args → monitor all active workspaces every 5 minutes
+- `<interval>` → custom interval (e.g., `2m`, `10m`)
+- `stop` → cancel all monitoring crons
+
+## On Invoke
+
+### 1. Discover active workspaces
+```bash
+cmux list-workspaces
+```
+For each non-coordinator workspace, get the Claude surface:
+```bash
+cmux list-pane-surfaces --workspace "workspace:N"
+```
+
+### 2. Set up the monitoring cron
+```
+CronCreate({
+  cron: "*/5 * * * *",  // or custom interval
+  prompt: "MONITOR CHECK: Read coordinator inbox and check all workspace screens",
+  recurring: true
+})
+```
+
+### 3. On each cron fire
+
+#### Check inbox
+```bash
+cat ~/.claude/coordinator-inbox.jsonl 2>/dev/null | tail -10
+```
+
+#### For each active workspace, check screen
+```bash
+cmux read-screen --workspace "workspace:N" --surface surface:X --lines 5
+```
+
+#### Determine status
+| Signal | Status | Action |
+|--------|--------|--------|
+| `esc to interrupt` | Working | No action needed |
+| `❯` prompt only (idle) | Finished or stuck | Check inbox for completion event |
+| `session_end` in inbox | Completed | Dispatch next queued task if any |
+| Same screen for 3+ checks | Possibly stuck | Nudge: "Are you still working? If stuck, /clear and retry." |
+| Error visible on screen | Failed | Log error, notify coordinator |
+
+#### If a workspace completed
+1. Read the inbox for details
+2. Check git log for new commits
+3. **Check the task queue for pending tasks:**
+   ```bash
+   ~/.claude/scripts/task-queue.sh next
+   ```
+   If a pending task exists, dispatch it to the idle workspace:
+   ```bash
+   TASK_JSON=$(~/.claude/scripts/task-queue.sh claim "<workspace-name>")
+   TASK=$(echo "$TASK_JSON" | jq -r '.task')
+   CONTEXT=$(echo "$TASK_JSON" | jq -r '.context')
+   TASK_ID=$(echo "$TASK_JSON" | jq -r '.id')
+   ```
+   Then send the task to the workspace:
+   ```bash
+   cmux send --workspace "<workspace-id>" "/start-work --context=\"$CONTEXT\" $TASK"
+   ```
+4. **Track re-queue counts:** If a task has been re-queued 3+ times (check `requeue_count`), do NOT dispatch it again. Instead:
+   ```bash
+   ~/.claude/scripts/task-queue.sh fail "$TASK_ID" "Max re-queues reached, needs human review"
+   cmux notify "ESCALATE: Task $TASK_ID failed after 3 attempts"
+   ```
+5. Clear processed inbox messages
+6. Log status to telemetry
+
+#### If a workspace seems stuck
+1. Check if it's waiting on something (Inngest job, API call, build)
+2. If idle for 3+ checks with no progress, send a nudge
+3. If nudge doesn't help after 2 more checks, restart the session
+
+### 4. Status report
+Every 30 minutes (or 6 checks), output a summary including the task queue:
+```
+MONITOR STATUS:
+- ws:8 (CDD Marathon): Working, 3 commits since last report
+- ws:11 (Import Fix): Completed, dispatched next task
+- Inbox: 2 messages processed
+- Task queue: 3 pending, 1 in_progress, 2 completed, 0 failed
+```
+Check the queue:
+```bash
+~/.claude/scripts/task-queue.sh list
+```
+
+## Stopping
+To stop monitoring:
+```
+CronDelete <job-id>
+```
+Or invoke `/monitor stop` which deletes all monitoring crons.
+
+## Key principle
+**Don't just observe — act.** If a workspace finishes and there's queued work, dispatch it immediately. If a workspace is stuck, nudge it. The coordinator shouldn't have to manually check — that's your job.

package/skills/commands/revive.md

@@ -0,0 +1,144 @@
+---
+description: |
+  Spawn a watcher process that monitors the current workspace and auto-sends a resume command after /clear.
+  Keeps coordinator sessions alive across context clears by auto-restarting them.
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# Revive — Auto-Resume After /clear
+
+Spawn a background watcher that monitors this workspace and automatically sends a resume command when Claude becomes idle (after /clear or session restart).
+
+## Usage
+
+```
+/revive                          # Start watcher with defaults (/coordinate)
+/revive /start-work --resume     # Resume a start-work session instead
+/revive --stop                   # Stop the watcher
+/revive --status                 # Check if watcher is running
+```
+
+## Instructions
+
+Parse the user's arguments from `$ARGUMENTS`:
+- If empty or no special flags → start the watcher with default command `/coordinate`
+- If `--stop` → stop the running watcher
+- If `--status` → report watcher status
+- Otherwise → use the argument as the resume command
+
+### Starting the Watcher
+
+1. **Check if a watcher is already running:**
+   ```bash
+   if [ -f ~/.claude/revive-watcher.pid ]; then
+     PID=$(cat ~/.claude/revive-watcher.pid)
+     if kill -0 "$PID" 2>/dev/null; then
+       echo "Watcher already running (PID $PID). Stop it first with /revive --stop"
+       # Ask user if they want to restart
+     fi
+   fi
+   ```
+
+2. **Detect the current workspace and surface:**
+   The watcher needs to know which cmux workspace and surface to monitor. Use `cmux list-workspaces` and identify the current one.
+
+   ```bash
+   # List workspaces to find the right one
+   cmux list-workspaces
+   ```
+
+   Then identify the Claude surface within that workspace:
+   ```bash
+   # Try reading common surfaces to find the Claude prompt
+   for s in surface:5 surface:3 surface:1; do
+     SCREEN=$(cmux read-screen --workspace <workspace_id> --surface "$s" --lines 3 2>/dev/null)
+     if echo "$SCREEN" | grep -qE "claude|bypass|❯"; then
+       echo "Found Claude on $s"
+       break
+     fi
+   done
+   ```
+
+3. **Start the watcher in the background:**
+   ```bash
+   RESUME_CMD="${ARGUMENTS:-/coordinate}"
+   # Strip --stop/--status flags if present
+   if [[ "$RESUME_CMD" == "--stop" ]] || [[ "$RESUME_CMD" == "--status" ]]; then
+     # Handle these cases separately (see below)
+     :
+   else
+     nohup ~/.claude/scripts/revive-watcher.sh \
+       --workspace "$WORKSPACE" \
+       --surface "$SURFACE" \
+       --command "$RESUME_CMD" \
+       > ~/.claude/revive-watcher.log 2>&1 &
+
+     echo "Revive watcher started (PID $!)"
+     echo "  Monitoring: $WORKSPACE $SURFACE"
+     echo "  Resume command: $RESUME_CMD"
+     echo "  Log: ~/.claude/revive-watcher.log"
+     echo ""
+     echo "When you /clear, the watcher will detect the idle prompt and"
+     echo "automatically send '$RESUME_CMD' to restart the session."
+     echo ""
+     echo "To stop: /revive --stop"
+   fi
+   ```
+
+### Stopping the Watcher
+
+```bash
+if [ -f ~/.claude/revive-watcher.pid ]; then
+  PID=$(cat ~/.claude/revive-watcher.pid)
+  if kill -0 "$PID" 2>/dev/null; then
+    kill "$PID"
+    echo "Watcher stopped (PID $PID)."
+  else
+    echo "Watcher was not running (stale PID file)."
+    rm -f ~/.claude/revive-watcher.pid
+  fi
+else
+  echo "No watcher running."
+fi
+```
+
+### Checking Status
+
+```bash
+if [ -f ~/.claude/revive-watcher.pid ]; then
+  PID=$(cat ~/.claude/revive-watcher.pid)
+  if kill -0 "$PID" 2>/dev/null; then
+    echo "Watcher is running (PID $PID)"
+    echo "Last 5 log lines:"
+    tail -5 ~/.claude/revive-watcher.log 2>/dev/null || echo "(no log yet)"
+  else
+    echo "Watcher is NOT running (stale PID file)."
+    rm -f ~/.claude/revive-watcher.pid
+  fi
+else
+  echo "No watcher configured."
+fi
+```
+
+## How It Works
+
+The watcher polls the workspace screen every 10 seconds. It detects idle state by checking:
+- The prompt marker (`❯`) is visible
+- "esc to interrupt" is NOT visible (meaning Claude isn't actively working)
+- "bypass permissions" or "What can I help" text appears (indicating a fresh prompt)
+
+When idle is detected, it sends the resume command and enters a 60-second cooldown to avoid double-sending.
+
+## Configuration
+
+The watcher script (`~/.claude/scripts/revive-watcher.sh`) accepts these options:
+- `--workspace <id>` — Which cmux workspace to monitor
+- `--surface <id>` — Which surface within the workspace (default: auto-detect)
+- `--command <cmd>` — What to send on resume (default: `/coordinate`)
+- `--interval <secs>` — Poll frequency (default: 10)
+- `--once` — Send once and exit (for one-shot revival)
+- `--quiet` — Suppress log output
+
+## Implementation
+
+Execute the above steps based on the parsed arguments. Present the result to the user clearly.

package/skills/commands/speak.md

@@ -0,0 +1,49 @@
+---
+description: |
+  Send a message to the coordinator workspace from a separate terminal. Sets up a simple input loop that routes your messages to the active coordinator.
+allowed-tools: Bash
+---
+
+# /speak — Talk to the Coordinator
+
+Sets up a message relay from this terminal to the coordinator workspace. Your messages get sent directly to the coordinator's Claude session.
+
+## On Invoke
+
+1. Find the coordinator target (saved by /coordinate on startup):
+```bash
+cat ~/.claude/coordinator-target 2>/dev/null
+```
+
+2. If no target file exists, discover it:
+```bash
+# List workspaces and find the one named "Main Conversation" or the coordinator
+cmux list-workspaces
+# Ask the user which workspace is the coordinator
+```
+
+3. Start the relay loop:
+```bash
+echo "Connected to coordinator. Type messages below. Ctrl+C to exit."
+echo "---"
+while IFS= read -r -p "> " msg; do
+  if [ -z "$msg" ]; then continue; fi
+  target=$(cat ~/.claude/coordinator-target 2>/dev/null)
+  if [ -z "$target" ]; then
+    echo "No coordinator target found. Run /coordinate first."
+    continue
+  fi
+  tw=${target% *}
+  ts=${target#* }
+  cmux send --workspace $tw --surface $ts "$msg" 2>/dev/null
+  cmux send-key --workspace $tw --surface $ts Enter 2>/dev/null
+  echo "  → sent"
+done
+```
+
+## If coordinator-target doesn't exist
+
+Guide the user:
+1. The coordinator needs to run `/coordinate` first, which writes `~/.claude/coordinator-target`
+2. Or manually set it: `echo "workspace:1 surface:5" > ~/.claude/coordinator-target`
+3. Find the right values with: `cmux list-workspaces` then `cmux list-pane-surfaces --workspace <id>`

package/skills/scripts/revive-watcher.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Revive Watcher — monitors a cmux workspace and auto-sends a resume command after /clear
+#
+# Usage: revive-watcher.sh [options]
+#   --workspace <id>    Workspace to monitor (default: auto-detect current)
+#   --surface <id>      Surface to monitor (default: auto-detect Claude surface)
+#   --command <cmd>     Command to send on resume (default: /coordinate)
+#   --interval <secs>   Poll interval in seconds (default: 10)
+#   --once              Send the resume command once, then exit
+#   --quiet             Suppress output except errors
+#
+# The watcher detects when Claude Code is idle (fresh prompt after /clear) and
+# sends the configured resume command to restart the session.
+
+set -euo pipefail
+
+# Defaults
+WORKSPACE=""
+SURFACE=""
+RESUME_CMD="/coordinate"
+INTERVAL=10
+ONCE=false
+QUIET=false
+PID_FILE="${HOME}/.claude/revive-watcher.pid"
+
+log() {
+  if [ "$QUIET" = false ]; then
+    echo "$(date '+%H:%M:%S') [revive] $*"
+  fi
+}
+
+err() {
+  echo "$(date '+%H:%M:%S') [revive] ERROR: $*" >&2
+}
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --workspace) WORKSPACE="$2"; shift 2 ;;
+    --surface)   SURFACE="$2"; shift 2 ;;
+    --command)   RESUME_CMD="$2"; shift 2 ;;
+    --interval)  INTERVAL="$2"; shift 2 ;;
+    --once)      ONCE=true; shift ;;
+    --quiet)     QUIET=true; shift ;;
+    --help|-h)
+      head -14 "$0" | tail -12
+      exit 0
+      ;;
+    *) err "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Auto-detect workspace if not specified
+if [ -z "$WORKSPACE" ]; then
+  # Try to find the current workspace from cmux
+  CURRENT=$(cmux list-workspaces 2>/dev/null | grep -o 'workspace:[0-9]*' | head -1 || true)
+  if [ -z "$CURRENT" ]; then
+    err "Could not auto-detect workspace. Use --workspace <id>"
+    exit 1
+  fi
+  WORKSPACE="$CURRENT"
+  log "Auto-detected workspace: $WORKSPACE"
+fi
+
+# Auto-detect Claude surface if not specified
+if [ -z "$SURFACE" ]; then
+  # Read all surfaces and find the one running Claude
+  SURFACES=$(cmux list-workspaces 2>/dev/null || true)
+  # Try common Claude surface patterns
+  for s in "surface:5" "surface:3" "surface:1"; do
+    SCREEN=$(cmux read-screen --workspace "$WORKSPACE" --surface "$s" --lines 5 2>/dev/null || true)
+    if echo "$SCREEN" | grep -qi "claude\|bypass\|permission\|❯"; then
+      SURFACE="$s"
+      break
+    fi
+  done
+  if [ -z "$SURFACE" ]; then
+    # Default to surface:5 (most common for Claude in cmux)
+    SURFACE="surface:5"
+    log "Could not auto-detect surface, defaulting to $SURFACE"
+  else
+    log "Auto-detected Claude surface: $SURFACE"
+  fi
+fi
+
+# Write PID file for management
+echo $$ > "$PID_FILE"
+trap 'rm -f "$PID_FILE"; log "Watcher stopped."; exit 0' EXIT INT TERM
+
+log "Watcher started"
+log "  Workspace: $WORKSPACE"
+log "  Surface:   $SURFACE"
+log "  Command:   $RESUME_CMD"
+log "  Interval:  ${INTERVAL}s"
+log "  PID:       $$"
+
+# Track state to avoid spamming
+LAST_SEND_TIME=0
+COOLDOWN=60  # seconds between sends
+
+is_idle() {
+  local screen
+  screen=$(cmux read-screen --workspace "$WORKSPACE" --surface "$SURFACE" --lines 5 2>/dev/null || true)
+
+  if [ -z "$screen" ]; then
+    return 1  # Can't read screen — not idle
+  fi
+
+  # Idle = has the prompt marker but NO "esc to interrupt" (which means Claude is working)
+  if echo "$screen" | grep -q "esc to interrupt"; then
+    return 1  # Claude is actively working
+  fi
+
+  # Check for idle prompt indicators:
+  # - Empty prompt (❯ with nothing after)
+  # - "bypass permissions" text (settings line visible = idle)
+  # - Just the prompt line with no active output
+  if echo "$screen" | grep -qE "(^❯\s*$|bypass permissions|What can I help)"; then
+    return 0  # Idle
+  fi
+
+  return 1  # Not clearly idle
+}
+
+while true; do
+  sleep "$INTERVAL"
+
+  if is_idle; then
+    NOW=$(date +%s)
+    ELAPSED=$((NOW - LAST_SEND_TIME))
+
+    if [ "$ELAPSED" -ge "$COOLDOWN" ]; then
+      log "Workspace idle — sending resume command: $RESUME_CMD"
+      cmux send --workspace "$WORKSPACE" --surface "$SURFACE" "$RESUME_CMD" 2>/dev/null || {
+        err "Failed to send to $WORKSPACE $SURFACE"
+        continue
+      }
+      sleep 1
+      cmux send-key --workspace "$WORKSPACE" --surface "$SURFACE" Enter 2>/dev/null || true
+      LAST_SEND_TIME=$NOW
+      log "Resume command sent. Cooling down ${COOLDOWN}s."
+
+      if [ "$ONCE" = true ]; then
+        log "One-shot mode — exiting."
+        exit 0
+      fi
+    fi
+  fi
+done