tanuki-telemetry 1.4.0 → 1.4.2

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/record.md

@@ -0,0 +1,55 @@
+---
+description: |
+  Record an agent-browser session as MP4 video. Start recording, perform actions, stop to encode.
+  Videos can be uploaded to telemetry as artifacts.
+allowed-tools: Bash, mcp__telemetry__log_artifact
+---
+
+# /record — Record Agent Browser Session
+
+Records agent-browser screenshots at regular intervals and encodes them into an MP4 video.
+
+## Usage
+
+- `/record` or `/record start` — Start recording (1 frame/sec)
+- `/record start 500` — Start recording at 2 fps (500ms interval)
+- `/record stop` — Stop and encode to MP4
+- `/record stop --upload` — Stop, encode, and upload to telemetry
+- `/record status` — Check recording status
+
+## On Invoke
+
+Parse the argument. Default action is "start".
+
+### Start
+```bash
+~/.claude/scripts/record-browser.sh start "/tmp/browser-recording-$(date +%Y%m%d-%H%M%S).mp4" ${INTERVAL:-1000}
+```
+Then tell the user: "Recording started. Perform your actions, then run `/record stop` when done."
+
+### Stop
+```bash
+~/.claude/scripts/record-browser.sh stop
+```
+The script outputs the path to the MP4 file.
+
+If `--upload` flag is present and a telemetry session is active, upload as artifact:
+```
+mcp__telemetry__log_artifact({
+  session_id: current_session_id,
+  file_path: "/tmp/browser-recording-*.mp4",
+  artifact_type: "recording",
+  description: "Agent browser session recording"
+})
+```
+
+### Status
+```bash
+~/.claude/scripts/record-browser.sh status
+```
+
+## Tips
+- Start recording BEFORE navigating to the page you want to capture
+- Higher fps (lower interval) = smoother video but larger file
+- Default 1fps is good for demos, use 500ms for smoother action
+- Videos are saved to /tmp/ by default — upload to telemetry for persistence

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>`