tanuki-telemetry 1.1.7 → 1.2.0

package/README.md

@@ -0,0 +1,116 @@
+# tanuki-telemetry
+
+Telemetry MCP server + 11 autonomous workflow skills for Claude Code. Track sessions, coordinate workspaces, run visual walkthroughs, and debug systematically.
+
+## Quick Start
+
+```bash
+npx tanuki-telemetry setup
+```
+
+This interactive wizard will:
+1. **Configure Telemetry MCP server** — local Docker with dashboard at `localhost:3333`
+2. **Install 11 skills** — autonomous workflows, debugging, visual QA, coordination
+3. **Set up hooks** — workspace completion notifications, coordinator inbox
+4. **Create output directories** — for screenshots, artifacts, reports
+
+## Skills
+
+### Core Workflows
+| Skill | Description |
+|-------|-------------|
+| `/start-work` | Fully autonomous development — scope, implement, test, PR |
+| `/debug` | Systematic bug investigation — replicate 3x, analyze, fix |
+| `/review-code` | Thorough PR code review against project standards |
+
+### Visual QA
+| Skill | Description |
+|-------|-------------|
+| `/walkthrough` | Execute walkthrough scenarios with screenshots |
+| `/create-path` | Generate walkthrough scenarios from codebase routes |
+| `/edit-path` | Add/update scenarios for specific features |
+| `/compare-image` | Visual diff with qualitative annotations |
+
+### Coordination
+| Skill | Description |
+|-------|-------------|
+| `/coordinate` | Central hub for managing multiple cmux workspaces |
+| `/cmux-guide` | Reference for workspace navigation (surfaces, sending, reading) |
+
+### Telemetry
+| Skill | Description |
+|-------|-------------|
+| `/sessions` | Browse past session history, stats, screenshots |
+
+## Dashboard
+
+The telemetry dashboard runs at `http://localhost:3333` with:
+
+- **Sessions** — live event timeline, screenshots, artifacts, plan progress
+- **Coordinator** — workspace status, live feed from all workspaces
+- **Walkthroughs** — QA run history with screenshots and action timeline
+- **Knowledge** — accumulated insights from past sessions
+
+### Inline Artifact Viewer
+- Markdown rendered as HTML
+- JSON with collapsible syntax highlighting
+- Images with click-to-enlarge lightbox
+- Text files with line limiting
+
+### Live Updates
+- Stats update via WebSocket (no reload needed)
+- Coordinator live feed aggregates events from all workspace sessions
+
+## Hooks
+
+The installer configures PostToolUse hooks for workspace communication:
+
+- **Session end** → writes to `~/.claude/coordinator-inbox.jsonl` + macOS notification
+- **Session start** → logs to coordinator inbox (async)
+- **Telemetry events** → streams event messages to inbox (async)
+
+The coordinator checks the inbox instead of polling workspace screens.
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
+│ Claude Code  │────▶│  Telemetry MCP   │────▶│  Dashboard   │
+│ (workspaces) │     │  (SQLite + API)  │     │  (React SPA) │
+└─────────────┘     └──────────────────┘     └──────────────┘
+       │                     │
+       ▼                     ▼
+ ~/.claude/           localhost:3333
+ coordinator-         Sessions, Coordinator,
+ inbox.jsonl          Walkthroughs, Knowledge
+```
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|------------|---------|
+| Docker image | Telemetry MCP container | `telemetry-mcp:latest` |
+| Data volume | Session data + screenshots | `~/telemetry-data` |
+| Repo directory | Your project root | `cwd` |
+| Worktrees directory | Git worktrees location | `../worktrees` |
+| Outputs directory | Screenshots, artifacts | `../outputs` |
+| Base branch | Branch for worktrees | `main` |
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- Docker (for telemetry server + dashboard)
+- Git
+- [cmux](https://cmux.dev) (for multi-workspace coordination)
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/cli.js setup
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { setup } from "./setup.js";
+import { start, stop, status } from "./commands.js";
+const command = process.argv[2];
+const commands = {
+    setup: () => setup(),
+    start: () => start(),
+    stop: () => stop(),
+    status: () => status(),
+};
+const handler = commands[command];
+if (handler) {
+    handler().catch((err) => {
+        console.error(`\nFailed: ${err.message}`);
+        process.exit(1);
+    });
+}
+else {
+    console.log(`
+@junior/telemetry-mcp — Local Telemetry MCP for Claude Code
+
+Usage:
+  npx @junior/telemetry-mcp setup     Interactive setup wizard (local Docker)
+  npx @junior/telemetry-mcp start     Start the telemetry dashboard
+  npx @junior/telemetry-mcp stop      Stop the telemetry dashboard
+  npx @junior/telemetry-mcp status    Check container health
+  `);
+    if (command && command !== "--help" && command !== "-h") {
+        console.error(`Unknown command: ${command}`);
+        process.exit(1);
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,3 @@
+export declare function start(): Promise<void>;
+export declare function stop(): Promise<void>;
+export declare function status(): Promise<void>;

package/dist/commands.js

@@ -0,0 +1,69 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COMPOSE_FILE = join(__dirname, "..", "docker", "docker-compose.yml");
+function getEnvArgs() {
+    const parts = [];
+    if (process.env.TELEMETRY_DATA_DIR) {
+        parts.push(`TELEMETRY_DATA_DIR=${process.env.TELEMETRY_DATA_DIR}`);
+    }
+    if (process.env.TELEMETRY_IMAGE) {
+        parts.push(`TELEMETRY_IMAGE=${process.env.TELEMETRY_IMAGE}`);
+    }
+    return parts.join(" ");
+}
+function composeCmd(args) {
+    if (!existsSync(COMPOSE_FILE)) {
+        throw new Error(`docker-compose.yml not found at ${COMPOSE_FILE}`);
+    }
+    return `${getEnvArgs()} docker compose -f ${COMPOSE_FILE} ${args}`;
+}
+export async function start() {
+    console.log("Starting telemetry dashboard...");
+    try {
+        execSync(composeCmd("up -d dashboard"), { stdio: "inherit" });
+        console.log("\nDashboard running at http://localhost:3333");
+    }
+    catch {
+        console.error("Failed to start dashboard");
+        process.exit(1);
+    }
+}
+export async function stop() {
+    console.log("Stopping telemetry services...");
+    try {
+        execSync(composeCmd("down"), { stdio: "inherit" });
+        console.log("Stopped.");
+    }
+    catch {
+        console.error("Failed to stop services");
+        process.exit(1);
+    }
+}
+export async function status() {
+    console.log("Telemetry service status:\n");
+    // Check containers
+    try {
+        execSync(composeCmd("ps"), { stdio: "inherit" });
+    }
+    catch {
+        console.log("  No compose services found (may not be running)");
+    }
+    // Health check
+    console.log("");
+    try {
+        const response = await fetch("http://localhost:3333/health");
+        if (response.ok) {
+            const data = await response.json();
+            console.log(`Dashboard health: OK (${JSON.stringify(data)})`);
+        }
+        else {
+            console.log(`Dashboard health: HTTP ${response.status}`);
+        }
+    }
+    catch {
+        console.log("Dashboard health: not reachable");
+    }
+}

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export declare function setup(): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,303 @@
+import prompts from "prompts";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLAUDE_DIR = join(homedir(), ".claude");
+const CLAUDE_JSON = join(homedir(), ".claude.json");
+const COMMANDS_DIR = join(CLAUDE_DIR, "commands");
+const SETTINGS_JSON = join(CLAUDE_DIR, "settings.json");
+export async function setup() {
+    console.log("\n@junior/telemetry-mcp — Setup\n");
+    console.log("This will configure your local environment with:");
+    console.log("  1. Telemetry MCP server (Docker, stdio)");
+    console.log("  2. Dashboard at http://localhost:3333");
+    console.log("  3. /start-work autonomous workflow command");
+    console.log("  4. /compare-image visual diff command\n");
+    // Check Docker is available
+    try {
+        execSync("docker version", { stdio: "pipe" });
+    }
+    catch {
+        console.error("Docker is required but not found. Please install Docker first.");
+        process.exit(1);
+    }
+    const options = await promptOptions();
+    // 1. Build/pull Docker image
+    await ensureDockerImage(options.dockerImage);
+    // 2. Configure ~/.claude.json (stdio docker)
+    await writeMcpConfig(options);
+    // 3. Start dashboard via docker compose
+    await startDashboard(options);
+    // 4. Create directories
+    if (!existsSync(options.outputsDir)) {
+        await mkdir(options.outputsDir, { recursive: true });
+        console.log(`  Created outputs directory: ${options.outputsDir}`);
+    }
+    // 5. Add health-check hook
+    await writeHealthCheckHook(options);
+    // 6. Install commands
+    await installStartWorkCommand(options);
+    await installCompareImageCommand();
+    await installAllTemplateCommands();
+    // 7. Health check
+    await healthCheck();
+    console.log("\nSetup complete!\n");
+    console.log("Next steps:");
+    console.log("  1. Restart Claude Code (or start a new session)");
+    console.log("  2. Run /start-work <task-name> to begin an autonomous workflow");
+    console.log("  3. Dashboard: http://localhost:3333");
+    console.log("  4. Run /coordinate to manage workspaces");
+    console.log("  5. Run /walkthrough <url> to test pages visually");
+    console.log("  6. Run /create-path <app> to generate walkthrough scenarios");
+    console.log("");
+}
+async function promptOptions() {
+    const answers = await prompts([
+        {
+            type: "text",
+            name: "dockerImage",
+            message: "Docker image name:",
+            initial: "telemetry-mcp:latest",
+        },
+        {
+            type: "text",
+            name: "dataVolume",
+            message: "Host path for data volume:",
+            initial: join(homedir(), "telemetry-data"),
+            hint: "Where session data / screenshots / artifacts are stored",
+        },
+        {
+            type: "text",
+            name: "repoDir",
+            message: "Default repo directory:",
+            initial: process.cwd(),
+        },
+        {
+            type: "text",
+            name: "worktreesDir",
+            message: "Worktrees directory:",
+            initial: join(process.cwd(), "../worktrees"),
+        },
+        {
+            type: "text",
+            name: "outputsDir",
+            message: "Outputs directory:",
+            initial: join(process.cwd(), "../outputs"),
+        },
+        {
+            type: "text",
+            name: "baseBranch",
+            message: "Base branch name:",
+            initial: "main",
+        },
+        {
+            type: "confirm",
+            name: "enableLinear",
+            message: "Enable Linear integration?",
+            initial: false,
+        },
+        {
+            type: "confirm",
+            name: "enablePlaywright",
+            message: "Enable Playwright screenshots?",
+            initial: false,
+        },
+    ]);
+    return {
+        dockerImage: answers.dockerImage || "telemetry-mcp:latest",
+        dataVolume: answers.dataVolume || join(homedir(), "telemetry-data"),
+        repoDir: answers.repoDir || process.cwd(),
+        worktreesDir: answers.worktreesDir || join(process.cwd(), "../worktrees"),
+        outputsDir: answers.outputsDir || join(process.cwd(), "../outputs"),
+        baseBranch: answers.baseBranch || "main",
+        enableLinear: answers.enableLinear ?? false,
+        enablePlaywright: answers.enablePlaywright ?? false,
+    };
+}
+async function ensureDockerImage(image) {
+    try {
+        execSync(`docker image inspect ${image}`, { stdio: "pipe" });
+        console.log(`  Docker image ${image} found`);
+    }
+    catch {
+        console.log(`  Docker image ${image} not found locally`);
+        console.log(`  Build it with: docker build -t ${image} .`);
+        console.log(`  (from the telemetry MCP server source directory)`);
+    }
+}
+async function writeMcpConfig(options) {
+    let claudeConfig = {};
+    if (existsSync(CLAUDE_JSON)) {
+        const raw = await readFile(CLAUDE_JSON, "utf-8");
+        claudeConfig = JSON.parse(raw);
+    }
+    if (!claudeConfig.mcpServers) {
+        claudeConfig.mcpServers = {};
+    }
+    claudeConfig.mcpServers["telemetry"] = {
+        type: "stdio",
+        command: "docker",
+        args: [
+            "run",
+            "--rm",
+            "-i",
+            "-v",
+            `${options.dataVolume}:/data`,
+            options.dockerImage,
+        ],
+    };
+    await writeFile(CLAUDE_JSON, JSON.stringify(claudeConfig, null, 2) + "\n");
+    console.log("  Telemetry MCP server added to ~/.claude.json");
+}
+async function startDashboard(options) {
+    const composePath = join(__dirname, "..", "docker", "docker-compose.yml");
+    if (!existsSync(composePath)) {
+        console.log("  docker-compose.yml not found — skipping dashboard auto-start");
+        return;
+    }
+    try {
+        execSync(`TELEMETRY_DATA_DIR=${options.dataVolume} TELEMETRY_IMAGE=${options.dockerImage} docker compose -f ${composePath} up -d dashboard`, { stdio: "pipe" });
+        console.log("  Dashboard started at http://localhost:3333");
+    }
+    catch (err) {
+        console.log("  Could not auto-start dashboard. Run: npx @junior/telemetry-mcp start");
+    }
+}
+async function writeHealthCheckHook(options) {
+    let settings = {};
+    if (existsSync(SETTINGS_JSON)) {
+        const raw = await readFile(SETTINGS_JSON, "utf-8");
+        settings = JSON.parse(raw);
+    }
+    if (!settings.hooks)
+        settings.hooks = {};
+    if (!settings.hooks.SessionStart)
+        settings.hooks.SessionStart = [];
+    const hasHook = settings.hooks.SessionStart.some((entry) => entry.hooks?.some((h) => h.command?.includes("telemetry")));
+    if (!hasHook) {
+        const startCmd = `docker start telemetry-mcp 2>/dev/null || docker run --rm -d --name telemetry-mcp -i -v ${options.dataVolume}:/data ${options.dockerImage} 2>/dev/null; echo 'OK'`;
+        settings.hooks.SessionStart.push({
+            matcher: "",
+            hooks: [{ type: "command", command: startCmd }],
+        });
+        await writeFile(SETTINGS_JSON, JSON.stringify(settings, null, 2) + "\n");
+        console.log("  Health-check hook added to ~/.claude/settings.json");
+    }
+    else {
+        console.log("  Telemetry hook already exists in settings.json");
+    }
+}
+async function installStartWorkCommand(options) {
+    await mkdir(COMMANDS_DIR, { recursive: true });
+    const templatePath = join(__dirname, "..", "templates", "start-work.md");
+    let template;
+    if (existsSync(templatePath)) {
+        template = await readFile(templatePath, "utf-8");
+    }
+    else {
+        template = "<!-- See templates/start-work.md -->";
+    }
+    template = template
+        .replaceAll("{{REPO_DIR}}", options.repoDir)
+        .replaceAll("{{WORKTREES_DIR}}", options.worktreesDir)
+        .replaceAll("{{OUTPUTS_DIR}}", options.outputsDir)
+        .replaceAll("{{BASE_BRANCH}}", options.baseBranch);
+    if (!options.enableLinear) {
+        template = removeSection(template, "LINEAR_START", "LINEAR_END");
+    }
+    else {
+        template = template
+            .replaceAll("<!-- LINEAR_START -->", "")
+            .replaceAll("<!-- LINEAR_END -->", "");
+    }
+    if (!options.enablePlaywright) {
+        template = removeSection(template, "PLAYWRIGHT_START", "PLAYWRIGHT_END");
+    }
+    else {
+        template = template
+            .replaceAll("<!-- PLAYWRIGHT_START -->", "")
+            .replaceAll("<!-- PLAYWRIGHT_END -->", "");
+    }
+    const tools = [
+        "Bash", "Read", "Glob", "Grep", "Edit", "Write", "Agent", "AskUserQuestion",
+        "mcp__telemetry__*",
+    ];
+    if (options.enableLinear)
+        tools.push("mcp__linear__*");
+    if (options.enablePlaywright)
+        tools.push("mcp__playwright__*");
+    template = template.replaceAll("{{ALLOWED_TOOLS}}", tools.join(", "));
+    const destPath = join(COMMANDS_DIR, "start-work.md");
+    if (existsSync(destPath)) {
+        const backupPath = join(COMMANDS_DIR, `start-work.backup.${Date.now()}.md`);
+        const existing = await readFile(destPath, "utf-8");
+        await writeFile(backupPath, existing);
+        console.log(`  Backed up existing /start-work`);
+    }
+    await writeFile(destPath, template);
+    console.log("  /start-work command installed");
+}
+async function installCompareImageCommand() {
+    await mkdir(COMMANDS_DIR, { recursive: true });
+    const templatePath = join(__dirname, "..", "templates", "compare-image.md");
+    if (!existsSync(templatePath)) {
+        console.log("  compare-image.md template not found — skipping");
+        return;
+    }
+    const template = await readFile(templatePath, "utf-8");
+    const destPath = join(COMMANDS_DIR, "compare-image.md");
+    if (existsSync(destPath)) {
+        const backupPath = join(COMMANDS_DIR, `compare-image.backup.${Date.now()}.md`);
+        const existing = await readFile(destPath, "utf-8");
+        await writeFile(backupPath, existing);
+        console.log(`  Backed up existing /compare-image`);
+    }
+    await writeFile(destPath, template);
+    console.log("  /compare-image command installed");
+}
+async function installAllTemplateCommands() {
+    await mkdir(COMMANDS_DIR, { recursive: true });
+    const templatesDir = join(__dirname, "..", "templates");
+    // Commands already handled by dedicated installers
+    const skip = new Set(["start-work.md", "compare-image.md"]);
+    const { readdirSync } = await import("node:fs");
+    const files = readdirSync(templatesDir).filter((f) => f.endsWith(".md") && !skip.has(f));
+    for (const file of files) {
+        const srcPath = join(templatesDir, file);
+        const destPath = join(COMMANDS_DIR, file);
+        const template = await readFile(srcPath, "utf-8");
+        if (existsSync(destPath)) {
+            const existing = await readFile(destPath, "utf-8");
+            if (existing === template) {
+                continue;
+            } // Already up to date
+            const name = file.replace(".md", "");
+            const backupPath = join(COMMANDS_DIR, `${name}.backup.${Date.now()}.md`);
+            await writeFile(backupPath, existing);
+        }
+        await writeFile(destPath, template);
+        console.log(`  /${file.replace(".md", "")} command installed`);
+    }
+}
+async function healthCheck() {
+    try {
+        const response = await fetch("http://localhost:3333/health");
+        if (response.ok) {
+            console.log("  Dashboard health check: OK");
+        }
+        else {
+            console.log("  Dashboard health check: responded but not OK");
+        }
+    }
+    catch {
+        console.log("  Dashboard health check: not reachable (may still be starting)");
+    }
+}
+function removeSection(text, startMarker, endMarker) {
+    const regex = new RegExp(`<!-- ${startMarker} -->[\\s\\S]*?<!-- ${endMarker} -->`, "g");
+    return text.replace(regex, "");
+}

package/docker/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  telemetry-mcp:
+    image: ${TELEMETRY_IMAGE:-telemetry-mcp:latest}
+    volumes:
+      - ${TELEMETRY_DATA_DIR:-~/telemetry-data}:/data
+    stdin_open: true
+
+  dashboard:
+    image: ${TELEMETRY_IMAGE:-telemetry-mcp:latest}
+    entrypoint: ["node", "dist/dashboard-server.js"]
+    volumes:
+      - ${TELEMETRY_DATA_DIR:-~/telemetry-data}:/data
+    ports:
+      - "3333:3333"
+    restart: unless-stopped

package/package.json

@@ -1,72 +1,40 @@
 {
   "name": "tanuki-telemetry",
-  "version": "1.1.7",
-  "description": "Workflow monitor and telemetry dashboard for Claude Code autonomous agents",
+  "version": "1.2.0",
+  "description": "Local installer for Telemetry MCP server — setup, start, stop, and status for Claude Code autonomous workflows",
   "type": "module",
   "bin": {
-    "tanuki": "./bin/tanuki.mjs",
-    "tanuki-telemetry": "./bin/tanuki.mjs"
+    "telemetry-mcp": "./dist/cli.js"
   },
-  "files": [
-    "bin/",
-    "skills/",
-    "src/",
-    "frontend/src/",
-    "frontend/index.html",
-    "frontend/package.json",
-    "frontend/tsconfig.json",
-    "frontend/tsconfig.app.json",
-    "frontend/eslint.config.js",
-    "frontend/vite.config.ts",
-    "tsconfig.json",
-    "Dockerfile",
-    "install.sh"
-  ],
   "scripts": {
     "build": "tsc",
-    "build:frontend": "cd frontend && npx vite build",
-    "build:all": "tsc && cd frontend && npx vite build",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
   },
+  "files": [
+    "dist",
+    "templates",
+    "docker"
+  ],
   "keywords": [
     "claude",
-    "mcp",
+    "claude-code",
     "telemetry",
-    "dashboard",
+    "mcp",
     "autonomous",
-    "agents",
-    "workflow"
+    "ai-agent"
   ],
-  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ykim-24/tanuki-telemetry.git"
+    "url": "https://github.com/ykim-24/tanuki-telemetry"
   },
+  "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "better-sqlite3": "^11.8.1",
-    "better-sqlite3-session-store": "^0.1.0",
-    "express": "^4.21.0",
-    "express-session": "^1.19.0",
-    "multer": "^2.1.1",
-    "passport": "^0.7.0",
-    "passport-google-oauth20": "^2.0.0",
-    "sharp": "^0.34.5",
-    "uuid": "^11.1.0",
-    "ws": "^8.19.0"
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.12",
-    "@types/express": "^5.0.0",
-    "@types/express-session": "^1.18.2",
-    "@types/multer": "^2.1.0",
-    "@types/node": "^22.13.10",
-    "@types/passport": "^1.0.17",
-    "@types/passport-google-oauth20": "^2.0.17",
-    "@types/sharp": "^0.31.1",
-    "@types/uuid": "^10.0.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.7.3"
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.7.0"
   }
 }

package/{skills → templates}/cmux-guide.md

@@ -110,10 +110,10 @@ cmux list-pane-surfaces --workspace "workspace:N"
 
 ### Choose the right --cwd
 The `--cwd` path determines where Claude starts. **Pick the most relevant directory for the task:**
-- Working on the main app? → `--cwd ~/project` (NOT the repo root)
-- Working on a worktree? → `--cwd ~/worktrees/<worktree-name>`
-- Working on a package? → `--cwd ~/project/packages/<package-name>`
-- General/cross-cutting? → `--cwd ~/project`
+- Working on the main app? → `--cwd ~/junior-main/junior` (NOT the repo root)
+- Working on a worktree? → `--cwd ~/junior-main/junior-worktrees/<worktree-name>`
+- Working on a package? → `--cwd ~/junior-main/junior/packages/<package-name>`
+- General/cross-cutting? → `--cwd ~/junior-main`
 
 **Wrong cwd = confused Claude.** If Claude is in the repo root, it may not find the right files or understand the project structure. Match the cwd to where the relevant code lives.
 
@@ -133,7 +133,16 @@ Keep names short but descriptive (e.g., "Benchmark Deck", "PPTX Import", "Auth M
 
 ## Monitoring Workspaces
 
-### Quick status check (low context cost):
+### Inbox-first (preferred — no screen reads needed):
+Workspaces using `/start-work` automatically notify the coordinator via a PostToolUse hook when their session ends. Messages go to `~/.claude/coordinator-inbox.jsonl`.
+```bash
+# Check for completion notifications
+cat ~/.claude/coordinator-inbox.jsonl 2>/dev/null | tail -5
+# Clear after processing
+> ~/.claude/coordinator-inbox.jsonl
+```
+
+### Quick status check (fallback — when no inbox message):
 ```bash
 cmux read-screen --workspace <id> --surface <surface_id> --lines 5
 ```