@lioneltay/worker-manager 0.0.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "worker-manager",
+  "version": "0.0.1",
+  "description": "Spawn and manage worker agents in isolated worktrees",
+  "author": {
+    "name": "lioneltay"
+  },
+  "repository": "https://github.com/lioneltay/agent-forge/tree/main/packages/claude-plugins/worker-manager",
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "worker-manager": {
+      "command": "npx",
+      "args": ["-y", "@lioneltay/worker-manager"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,337 @@
+# @lioneltay/worker-manager
+
+A Claude Code plugin that spawns autonomous worker agents in isolated git worktrees. Workers run in tmux sessions with their own Claude Code instance and communicate back to the orchestrator via a file-based mail system.
+
+## Installation
+
+Install via the Claude Code plugin marketplace, or manually:
+
+```bash
+npm install -g @lioneltay/worker-manager
+```
+
+## Quick start
+
+Once the plugin is installed, the orchestrator tools are available in your Claude Code session:
+
+```
+> Spawn a worker to refactor the auth module into separate files
+
+# Claude calls start_worker({ title: "refactor-auth", task: "..." })
+# Worker is created in a new worktree on branch worker/refactor-auth-a3f1b2c0
+# Worker runs autonomously in tmux session worker-a3f1b2c0
+
+> [next prompt — hook fires automatically]
+# "Worker refactor-auth (a3f1b2c0) COMPLETED: Refactored auth module into..."
+```
+
+## How it works
+
+A single Node.js binary (`dist/index.js`) serves four different roles depending on how it's invoked:
+
+```mermaid
+flowchart TD
+    Entry["node dist/index.js"]
+    Entry --> CheckHook{"--hook flag?"}
+    CheckHook -->|Yes| Hook["UserPromptSubmit Hook
+    Read & display pending mail"]
+    CheckHook -->|No| CheckStop{"--stop-hook flag?"}
+    CheckStop -->|Yes| StopHook["Stop Hook
+    Block premature stops"]
+    CheckStop -->|No| CheckWorker{"WORKER_ID env var?"}
+    CheckWorker -->|Yes| Worker["Worker MCP Server
+    Tools: complete, ask"]
+    CheckWorker -->|No| Orchestrator["Orchestrator MCP Server
+    Tools: start_worker, list_workers,
+    nudge_worker, stop_worker, read_mail"]
+```
+
+The orchestrator runs as an MCP server in the lead agent's Claude Code session. When it spawns a worker, it launches a new Claude Code instance in a tmux session, configured with a worker MCP server that provides `complete` and `ask` tools. Workers communicate back via the filesystem — no HTTP servers, no daemons.
+
+## Tools
+
+### Orchestrator tools
+
+| Tool           | Input                                         | Description                                                                       |
+| -------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
+| `start_worker` | `title`, `task`, `useWorktree`, `baseBranch?` | Spawn a worker agent in an isolated worktree or the current directory.            |
+| `list_workers` | —                                             | List all workers with status. Cross-references tmux to detect crashed workers.    |
+| `nudge_worker` | `id`, `message`                               | Send a message to a worker's tmux session (answers questions, provides guidance). |
+| `stop_worker`  | `id`                                          | Stop a running worker by killing its tmux session. Worktrees are preserved.       |
+| `read_mail`    | —                                             | Read and clear all pending messages from this orchestrator's workers.             |
+
+### Worker tools
+
+| Tool       | Input      | Description                                                                         |
+| ---------- | ---------- | ----------------------------------------------------------------------------------- |
+| `complete` | `summary`  | Signal task completion. Writes a mail message and updates the registry.             |
+| `ask`      | `question` | Ask the orchestrator a question. Sets status to "asking" and writes a mail message. |
+
+## Worker lifecycle
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant O as Orchestrator
+    participant FS as State (filesystem)
+    participant T as tmux
+    participant W as Worker (Claude Code)
+    participant WT as Git Worktree
+
+    User->>O: "spawn a worker to do X"
+    O->>WT: Create worktree (new branch)
+    O->>FS: Register worker in state.json
+    O->>T: Create tmux session
+    O->>T: Launch: claude --dangerously-skip-permissions<br/>with worker MCP + task prompt
+    T->>W: Claude Code starts
+
+    Note over W: Works autonomously<br/>in isolated worktree
+
+    alt Task completed
+        W->>FS: complete(summary)<br/>Write mail + update status
+    else Needs clarification
+        W->>FS: ask(question)<br/>Write mail + update status
+    end
+
+    Note over User,O: On next prompt submission...
+    FS-->>O: UserPromptSubmit hook<br/>reads and prints mail
+
+    alt Worker asked a question
+        O->>T: nudge_worker(id, message)<br/>tmux send-keys
+        T->>W: Message appears as user input
+    end
+
+    Note over User,O: When orchestrator tries to stop...
+    FS-->>O: Stop hook checks for unread mail<br/>blocks if messages are pending
+```
+
+## State management
+
+All state is stored in a temp directory derived from the git root, keeping the repository clean:
+
+```
+$TMPDIR/worker-manager/<hash>/
+├── state.json                    # Worker registry
+├── orchestrators/
+│   └── <claude-code-pid>         # Maps PID → orchestrator ID
+└── mail/
+    ├── <orchestrator-id>/        # Per-orchestrator mailbox
+    │   ├── 2025-01-15T...-uuid.json
+    │   └── 2025-01-15T...-uuid.json
+    └── <orchestrator-id>/
+        └── ...
+```
+
+The `<hash>` is the first 12 characters of the SHA-256 of the git root path. This means different repositories get isolated state, and worktrees of the same repository share state with the main checkout.
+
+### Worker registry (`state.json`)
+
+Tracks all workers spawned from this git root:
+
+```json
+{
+  "workers": {
+    "a3f1b2c0": {
+      "id": "a3f1b2c0",
+      "name": "refactor-auth",
+      "task": "Refactor the auth module...",
+      "status": "running",
+      "branch": "worker/refactor-auth-a3f1b2c0",
+      "worktreePath": "/repo/.worktrees/worker--refactor-auth-a3f1b2c0",
+      "tmuxSession": "worker-a3f1b2c0",
+      "createdAt": "2025-01-15T10:30:00.000Z",
+      "useWorktree": true
+    }
+  }
+}
+```
+
+Registry writes are atomic — data is written to a temp file first, then renamed into place via `fs.renameSync`.
+
+### Worker statuses
+
+| Status      | Meaning                                                       |
+| ----------- | ------------------------------------------------------------- |
+| `running`   | Worker is actively processing its task                        |
+| `completed` | Worker called `complete` — task is done                       |
+| `asking`    | Worker called `ask` — waiting for orchestrator response       |
+| `failed`    | Detected by `list_workers` when tmux session no longer exists |
+| `stopped`   | Worker was explicitly stopped or cleaned up on shutdown       |
+
+### Mail messages
+
+Each message is a separate JSON file named `<timestamp>-<uuid>.json`:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "workerId": "a3f1b2c0",
+  "workerName": "refactor-auth",
+  "type": "completion",
+  "content": "Refactored auth module into login.ts, register.ts, and middleware.ts",
+  "timestamp": "2025-01-15T10:35:00.000Z"
+}
+```
+
+Message types: `completion`, `question`.
+
+Reading mail is destructive — files are deleted after being read. This ensures each message is delivered exactly once.
+
+### Multi-session isolation
+
+Multiple Claude Code sessions in the same directory each get their own mailbox:
+
+```mermaid
+flowchart TB
+    subgraph "Claude Code Session A (PID 1234)"
+        MCP_A["Orchestrator MCP<br/>id: abc12345"]
+        Hook_A["Hooks<br/>ppid: 1234"]
+    end
+
+    subgraph "Claude Code Session B (PID 5678)"
+        MCP_B["Orchestrator MCP<br/>id: def67890"]
+        Hook_B["Hooks<br/>ppid: 5678"]
+    end
+
+    subgraph "State Directory"
+        Mapping["orchestrators/<br/>1234 → abc12345<br/>5678 → def67890"]
+        Mail_A["mail/abc12345/<br/>messages..."]
+        Mail_B["mail/def67890/<br/>messages..."]
+    end
+
+    MCP_A -->|"writes mapping"| Mapping
+    MCP_B -->|"writes mapping"| Mapping
+    Hook_A -->|"reads ppid 1234<br/>→ abc12345"| Mapping
+    Hook_B -->|"reads ppid 5678<br/>→ def67890"| Mapping
+    Hook_A -->|"reads only"| Mail_A
+    Hook_B -->|"reads only"| Mail_B
+```
+
+**How it works:**
+
+1. When the orchestrator MCP server starts, it generates a unique ID and writes a mapping from its parent PID (the Claude Code process) to that ID.
+2. Workers receive the orchestrator ID via the `ORCHESTRATOR_ID` env var and write mail to `mail/<orchestratorId>/`.
+3. Hooks run as children of the same Claude Code process, so `process.ppid` matches the MCP server's `process.ppid`. They look up the mapping to find the right mailbox.
+
+This ensures each session only reads its own workers' mail, even when multiple sessions share the same git root.
+
+## Hooks
+
+The plugin registers two Claude Code hooks:
+
+### UserPromptSubmit hook
+
+Fires before every prompt. Reads pending mail from this orchestrator's mailbox and prints it to stdout, where Claude Code displays it as context for the next turn.
+
+```
+[Worker refactor-auth (a3f1b2c0)] COMPLETED: Refactored auth module into...
+```
+
+### Stop hook
+
+Fires when Claude Code is about to stop. Has two modes depending on context:
+
+**Orchestrator mode** (no `WORKER_ID` env var): Checks for unread mail. If mail is pending, blocks the stop with a JSON decision so the orchestrator processes worker results before going idle.
+
+**Worker mode** (`WORKER_ID` env var set): Checks whether the worker called `complete` or `ask`. If not, blocks the stop and reminds the worker to call one of those tools. This prevents workers from silently exiting without reporting results.
+
+```mermaid
+flowchart TD
+    StopHook["Stop Hook Fires"]
+    StopHook --> IsWorker{"WORKER_ID set?"}
+
+    IsWorker -->|No| OrchestratorPath["Orchestrator Mode"]
+    OrchestratorPath --> HasMapping{"Orchestrator ID<br/>mapping exists?"}
+    HasMapping -->|No| AllowStop0["Allow stop<br/>(no workers spawned)"]
+    HasMapping -->|Yes| HasMail{"Pending mail?"}
+    HasMail -->|No| AllowStop1["Allow stop"]
+    HasMail -->|Yes| BlockOrch["Block stop<br/>Show mail content"]
+
+    IsWorker -->|Yes| WorkerPath["Worker Mode"]
+    WorkerPath --> CheckStatus{"Worker status?"}
+    CheckStatus -->|"completed / asking"| AllowStop2["Allow stop"]
+    CheckStatus -->|running| CheckRetries{"Retries >= 2?"}
+    CheckRetries -->|Yes| AllowStop3["Allow stop<br/>(give up)"]
+    CheckRetries -->|No| BlockWorker["Block stop<br/>'Call complete or ask'"]
+```
+
+The worker stop hook has a retry limit of 2 to prevent infinite loops — if the worker ignores the reminder twice, it's allowed to exit.
+
+## Worker spawning
+
+When `start_worker` is called, the following happens:
+
+```mermaid
+sequenceDiagram
+    participant O as Orchestrator
+    participant WT as Worktree Manager
+    participant FS as Filesystem
+    participant T as tmux
+
+    O->>WT: create("worker/name-id", { newBranch: true })
+    WT-->>O: { path: "/repo/.worktrees/worker--name-id" }
+
+    O->>FS: Write worker to state.json
+    O->>FS: Write MCP config to $TMPDIR/mcp-config-{id}.json
+
+    Note over FS: MCP config points worker at same<br/>binary with env vars: WORKER_ID,<br/>WORKER_NAME, STATE_DIR, ORCHESTRATOR_ID
+
+    O->>T: tmux new-session -d -s worker-{id}
+    O->>T: tmux send-keys:<br/>export WORKER_ID=... STATE_DIR=...<br/>claude --dangerously-skip-permissions<br/>--mcp-config {path} --session-id {uuid}<br/>--append-system-prompt "..." "task"
+```
+
+Key details:
+
+- **Same binary, different mode**: The worker's MCP config points at the same `dist/index.js`. The `WORKER_ID` env var causes it to start as a worker MCP server instead of an orchestrator.
+- **Environment variables in tmux**: `WORKER_ID` and `STATE_DIR` are exported as shell variables in the tmux session before launching Claude. This allows the Stop hook (which inherits the shell environment) to detect that it's running in a worker context.
+- **`--dangerously-skip-permissions`**: Workers run without permission prompts since they're autonomous.
+- **System prompt injection**: Workers are told to call `complete` when done or `ask` if blocked.
+
+## Cleanup
+
+### Explicit stop
+
+Use `stop_worker` to kill a specific worker's tmux session. The worker's status is updated to `"stopped"` and its worktree is preserved on disk for merging.
+
+### Shutdown cleanup
+
+When the orchestrator MCP server exits (Claude Code session ends, SIGTERM, or SIGINT), all running workers are automatically cleaned up:
+
+1. All workers with `status: "running"` have their tmux sessions killed
+2. Their status is updated to `"stopped"` in the registry
+3. The orchestrator's PID mapping file is removed
+
+Worktrees are intentionally preserved in both cases — they contain code changes the user may want to merge.
+
+### Worktree vs shared directory
+
+`useWorktree: true` creates an isolated git worktree via `@lioneltay/worktree-manager`. `useWorktree: false` runs the worker in the current directory on the current branch — useful for parallel tasks that don't need branch isolation (e.g., research, testing).
+
+## Source files
+
+```
+src/
+├── index.ts          # Entry point — mode detection + hook implementations
+├── orchestrator.ts   # Orchestrator MCP server (start_worker, list_workers, etc.)
+├── worker.ts         # Worker MCP server (complete, ask)
+├── spawn.ts          # Worker spawning logic (tmux + Claude CLI)
+├── state.ts          # File-based state (registry, mail, orchestrator mapping)
+└── types.ts          # Shared type definitions
+```
+
+## Plugin structure
+
+```
+.claude-plugin/
+  plugin.json         # Plugin manifest
+.mcp.json             # MCP server configuration
+hooks/
+  hooks.json          # Hook definitions (UserPromptSubmit + Stop)
+```
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` — MCP server implementation
+- `@lioneltay/worktree-manager` — Git worktree creation
+- `zod` — Input validation for MCP tool schemas
+- `tmux` — Required system dependency for worker session management

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { getStateDir, getGitRoot, readAndFlushMail, readRegistry, readOrchestratorId, } from "./state.js";
+import { startOrchestratorServer } from "./orchestrator.js";
+import { startWorkerServer } from "./worker.js";
+function runHook() {
+    try {
+        const gitRoot = getGitRoot();
+        const stateDir = getStateDir(gitRoot);
+        const orchestratorId = readOrchestratorId(stateDir, process.ppid);
+        if (!orchestratorId)
+            return;
+        const messages = readAndFlushMail(stateDir, orchestratorId);
+        if (messages.length === 0) {
+            return;
+        }
+        for (const msg of messages) {
+            const prefix = msg.type === "completion" ? "COMPLETED" : "QUESTION";
+            process.stdout.write(`[Worker ${msg.workerName} (${msg.workerId})] ${prefix}: ${msg.content}\n`);
+        }
+    }
+    catch {
+        // Silently ignore errors in hook mode
+    }
+}
+function runStopHook() {
+    const workerId = process.env.WORKER_ID;
+    const stateDir = process.env.STATE_DIR;
+    // Orchestrator mode: check for pending mail
+    if (!workerId || !stateDir) {
+        try {
+            const gitRoot = getGitRoot();
+            const orchestratorStateDir = getStateDir(gitRoot);
+            const orchestratorId = readOrchestratorId(orchestratorStateDir, process.ppid);
+            if (!orchestratorId)
+                return;
+            const messages = readAndFlushMail(orchestratorStateDir, orchestratorId);
+            if (messages.length === 0) {
+                return;
+            }
+            const formatted = messages
+                .map((m) => {
+                const prefix = m.type === "completion" ? "COMPLETED" : "QUESTION";
+                return `[Worker ${m.workerName} (${m.workerId})] ${prefix}: ${m.content}`;
+            })
+                .join("\n");
+            const response = {
+                decision: "block",
+                reason: formatted,
+            };
+            process.stdout.write(JSON.stringify(response) + "\n");
+        }
+        catch {
+            // Silently ignore errors
+        }
+        return;
+    }
+    try {
+        const registry = readRegistry(stateDir);
+        const worker = registry.workers[workerId];
+        if (!worker)
+            return;
+        // Already completed or asked — let it stop
+        if (worker.status === "completed" || worker.status === "asking") {
+            return;
+        }
+        // Check retry count to avoid infinite loops (max 2 attempts)
+        const retryFile = path.join(os.tmpdir(), "worker-manager", `stop-retries-${workerId}`);
+        let retries = 0;
+        try {
+            retries = parseInt(fs.readFileSync(retryFile, "utf-8"), 10);
+        }
+        catch {
+            // File doesn't exist yet
+        }
+        if (retries >= 2) {
+            // Give up — clean up retry file
+            try {
+                fs.unlinkSync(retryFile);
+            }
+            catch { }
+            return;
+        }
+        // Increment retry count
+        const tmpDir = path.join(os.tmpdir(), "worker-manager");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        fs.writeFileSync(retryFile, String(retries + 1));
+        // Block Claude from stopping via JSON decision
+        const response = {
+            decision: "block",
+            reason: "You haven't called the `complete` or `ask` tool yet. " +
+                "Please call `complete` with a summary of what you accomplished, " +
+                "or `ask` if you need clarification from the orchestrator.",
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+    }
+    catch {
+        // Silently ignore errors
+    }
+}
+if (process.argv.includes("--hook")) {
+    runHook();
+}
+else if (process.argv.includes("--stop-hook")) {
+    runStopHook();
+}
+else if (process.env.WORKER_ID) {
+    startWorkerServer().catch((error) => {
+        console.error("Worker server fatal error:", error);
+        process.exit(1);
+    });
+}
+else {
+    startOrchestratorServer().catch((error) => {
+        console.error("Orchestrator server fatal error:", error);
+        process.exit(1);
+    });
+}

package/dist/orchestrator.d.ts

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

package/dist/orchestrator.js

@@ -0,0 +1,368 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { create } from "@lioneltay/worktree-manager";
+import { getGitRoot, getStateDir, readRegistry, writeRegistry, readAndFlushMail, writeOrchestratorMapping, removeOrchestratorMapping, } from "./state.js";
+import { spawnWorker } from "./spawn.js";
+function generateShortId() {
+    return randomUUID().slice(0, 8);
+}
+function titleToName(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 30);
+}
+function tmuxSessionExists(session) {
+    try {
+        execFileSync("tmux", ["has-session", "-t", session], {
+            stdio: "pipe",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function killTmuxSession(session) {
+    try {
+        execFileSync("tmux", ["kill-session", "-t", session], {
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Session may already be dead
+    }
+}
+function cleanupWorkers(stateDir) {
+    const registry = readRegistry(stateDir);
+    let changed = false;
+    for (const worker of Object.values(registry.workers)) {
+        if (worker.status === "running") {
+            killTmuxSession(worker.tmuxSession);
+            worker.status = "stopped";
+            changed = true;
+        }
+    }
+    if (changed) {
+        writeRegistry(stateDir, registry);
+    }
+    removeOrchestratorMapping(stateDir, process.ppid);
+}
+function getCurrentBranch() {
+    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        encoding: "utf-8",
+    }).trim();
+}
+export async function startOrchestratorServer() {
+    // Generate a unique ID for this orchestrator session so mail is scoped.
+    const orchestratorId = generateShortId();
+    const gitRoot = getGitRoot();
+    const stateDir = getStateDir(gitRoot);
+    // Write mapping so hooks (which share the same parent PID) can find our mailbox.
+    writeOrchestratorMapping(stateDir, process.ppid, orchestratorId);
+    const server = new McpServer({
+        name: "worker-manager",
+        version: "0.0.1",
+    });
+    server.registerTool("start_worker", {
+        description: [
+            "Spawn an autonomous worker agent to complete a task independently.",
+            "",
+            "Use useWorktree=true when the worker's changes should land on a separate branch (e.g., a feature that needs its own PR, changes that might conflict with other workers).",
+            "Use useWorktree=false to run in the current directory on the current branch (e.g., research, tests, or parallel edits to non-overlapping files).",
+            "",
+            "Workers send mail when they finish or have questions. Messages are delivered automatically via the prompt hook, or use `read_mail` to check manually.",
+        ].join("\n"),
+        inputSchema: {
+            title: z.string().describe("Short title for the worker task"),
+            task: z
+                .string()
+                .describe("Detailed task description for the worker. Be specific about what to do and what files to modify."),
+            baseBranch: z
+                .string()
+                .optional()
+                .describe("Base branch to create the worktree from (defaults to current branch). Only used when useWorktree is true."),
+            useWorktree: z
+                .boolean()
+                .describe("true = isolated git worktree on a new branch. false = current directory, current branch."),
+        },
+    }, async ({ title, task, baseBranch, useWorktree }) => {
+        try {
+            const id = generateShortId();
+            const name = titleToName(title);
+            const tmuxSession = `worker-${id}`;
+            let workingDir;
+            let branchName;
+            if (useWorktree) {
+                branchName = `worker/${name}-${id}`;
+                const worktree = await create(branchName, {
+                    newBranch: true,
+                    from: baseBranch,
+                });
+                workingDir = worktree.path;
+            }
+            else {
+                branchName = getCurrentBranch();
+                workingDir = gitRoot;
+            }
+            const entry = {
+                id,
+                name,
+                task,
+                status: "running",
+                branch: branchName,
+                worktreePath: workingDir,
+                tmuxSession,
+                createdAt: new Date().toISOString(),
+                useWorktree,
+            };
+            const registry = readRegistry(stateDir);
+            registry.workers[id] = entry;
+            writeRegistry(stateDir, registry);
+            spawnWorker({
+                id,
+                name,
+                task,
+                workingDir,
+                stateDir,
+                tmuxSession,
+                orchestratorId,
+            });
+            const info = [
+                `Worker started successfully.`,
+                `  ID: ${id}`,
+                `  Name: ${name}`,
+                `  Branch: ${branchName}`,
+                `  Directory: ${workingDir}`,
+                `  Tmux: ${tmuxSession}`,
+            ];
+            if (!useWorktree) {
+                info.push(`  Mode: shared directory (no worktree)`);
+            }
+            info.push(``, `The worker will notify you when it completes or has questions.`);
+            return {
+                content: [{ type: "text", text: info.join("\n") }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to start worker: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_workers", {
+        description: "List all workers with their current status. Detects crashed workers automatically.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const registry = readRegistry(stateDir);
+            const workers = Object.values(registry.workers);
+            if (workers.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No workers found." }],
+                };
+            }
+            const enriched = workers.map((w) => {
+                const tmuxAlive = w.status === "running" ? tmuxSessionExists(w.tmuxSession) : null;
+                const effectiveStatus = w.status === "running" && !tmuxAlive ? "failed" : w.status;
+                return { ...w, effectiveStatus };
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(enriched, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list workers: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("nudge_worker", {
+        description: "Send a message to a running worker. Use this to answer questions or provide guidance.",
+        inputSchema: {
+            id: z.string().describe("Worker ID"),
+            message: z
+                .string()
+                .describe("Message to send to the worker's terminal"),
+        },
+    }, async ({ id, message }) => {
+        try {
+            const registry = readRegistry(stateDir);
+            const worker = registry.workers[id];
+            if (!worker) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Worker '${id}' not found.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (!tmuxSessionExists(worker.tmuxSession)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Worker '${id}' tmux session is not running.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            execFileSync("tmux", [
+                "send-keys",
+                "-t",
+                worker.tmuxSession,
+                "-l",
+                message,
+            ]);
+            execFileSync("tmux", ["send-keys", "-t", worker.tmuxSession, "Enter"]);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Message sent to worker '${id}' (${worker.name}).`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to nudge worker: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("stop_worker", {
+        description: "Stop a running worker. The worker's code changes and worktree are preserved.",
+        inputSchema: {
+            id: z.string().describe("Worker ID"),
+        },
+    }, async ({ id }) => {
+        try {
+            const registry = readRegistry(stateDir);
+            const worker = registry.workers[id];
+            if (!worker) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Worker '${id}' not found.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (worker.status === "stopped") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Worker '${id}' (${worker.name}) is already stopped.`,
+                        },
+                    ],
+                };
+            }
+            if (tmuxSessionExists(worker.tmuxSession)) {
+                killTmuxSession(worker.tmuxSession);
+            }
+            registry.workers[id] = { ...worker, status: "stopped" };
+            writeRegistry(stateDir, registry);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Worker '${id}' (${worker.name}) has been stopped. Worktree preserved at: ${worker.worktreePath}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to stop worker: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("read_mail", {
+        description: "Read and clear all pending messages from workers. Messages are either task completions or questions. Reading is destructive — messages are removed after being read.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const messages = readAndFlushMail(stateDir, orchestratorId);
+            if (messages.length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: "No new messages from workers." },
+                    ],
+                };
+            }
+            const formatted = messages
+                .map((m) => {
+                const prefix = m.type === "completion" ? "COMPLETED" : "QUESTION";
+                return `[${prefix}] Worker ${m.workerName} (${m.workerId}):\n${m.content}`;
+            })
+                .join("\n\n---\n\n");
+            return {
+                content: [{ type: "text", text: formatted }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to read mail: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    transport.onclose = () => {
+        cleanupWorkers(stateDir);
+    };
+    process.on("SIGTERM", () => {
+        cleanupWorkers(stateDir);
+        process.exit(0);
+    });
+    process.on("SIGINT", () => {
+        cleanupWorkers(stateDir);
+        process.exit(0);
+    });
+}

package/dist/spawn.d.ts

@@ -0,0 +1,9 @@
+export declare function spawnWorker(options: {
+    id: string;
+    name: string;
+    task: string;
+    workingDir: string;
+    stateDir: string;
+    tmuxSession: string;
+    orchestratorId: string;
+}): void;

package/dist/spawn.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+function getBinaryPath() {
+    return path.resolve(path.dirname(__filename), "index.js");
+}
+function escapeShellArg(arg) {
+    return arg.replace(/'/g, "'\\''");
+}
+export function spawnWorker(options) {
+    const { id, name, task, workingDir, stateDir, tmuxSession, orchestratorId } = options;
+    const sessionId = randomUUID();
+    // Write MCP config pointing worker at same binary with env vars
+    const binaryPath = getBinaryPath();
+    const mcpConfig = {
+        mcpServers: {
+            worker: {
+                command: "node",
+                args: [binaryPath],
+                env: {
+                    WORKER_ID: id,
+                    WORKER_NAME: name,
+                    STATE_DIR: stateDir,
+                    ORCHESTRATOR_ID: orchestratorId,
+                },
+            },
+        },
+    };
+    const tmpDir = path.join(os.tmpdir(), "worker-manager");
+    fs.mkdirSync(tmpDir, { recursive: true });
+    const mcpConfigPath = path.join(tmpDir, `mcp-config-${id}.json`);
+    fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig));
+    // Create tmux session
+    execFileSync("tmux", [
+        "new-session",
+        "-d",
+        "-s",
+        tmuxSession,
+        "-c",
+        workingDir,
+    ]);
+    // Build Claude command
+    const systemPrompt = "You are a worker agent. Complete the assigned task thoroughly. " +
+        "When done, call the `complete` tool with a summary of what you did. " +
+        "If you need clarification from the orchestrator, call the `ask` tool with your question.";
+    // Export env vars so the Stop hook can identify this as a worker session
+    const envExport = `export WORKER_ID=${escapeShellArg(id)} STATE_DIR=${escapeShellArg(stateDir)}`;
+    const claudeCmd = [
+        "claude",
+        "--session-id",
+        sessionId,
+        "--mcp-config",
+        mcpConfigPath,
+        "--dangerously-skip-permissions",
+        "--append-system-prompt",
+        `'${escapeShellArg(systemPrompt)}'`,
+        `'${escapeShellArg(task)}'`,
+    ].join(" ");
+    const fullCommand = `${envExport} ; ${claudeCmd}`;
+    // Send command to tmux session
+    execFileSync("tmux", ["send-keys", "-t", tmuxSession, "-l", fullCommand]);
+    execFileSync("tmux", ["send-keys", "-t", tmuxSession, "Enter"]);
+}

package/dist/state.d.ts

@@ -0,0 +1,18 @@
+import type { WorkerEntry, WorkerRegistry, MailMessage } from "./types.js";
+export declare function getGitRoot(): string;
+export declare function getStateDir(gitRoot?: string): string;
+export declare function writeOrchestratorMapping(stateDir: string, ppid: number, orchestratorId: string): void;
+export declare function readOrchestratorId(stateDir: string, ppid: number): string | null;
+export declare function removeOrchestratorMapping(stateDir: string, ppid: number): void;
+export declare function readRegistry(stateDir: string): WorkerRegistry;
+export declare function writeRegistry(stateDir: string, registry: WorkerRegistry): void;
+export declare function updateWorker(stateDir: string, id: string, update: Partial<WorkerEntry>): void;
+/**
+ * Write a mail message to the orchestrator's scoped mailbox at
+ * `mail/<orchestratorId>/`.
+ */
+export declare function writeMail(stateDir: string, message: MailMessage, orchestratorId: string): void;
+/**
+ * Read and flush all mail from a specific orchestrator's mailbox.
+ */
+export declare function readAndFlushMail(stateDir: string, orchestratorId: string): MailMessage[];

package/dist/state.js

@@ -0,0 +1,109 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+export function getGitRoot() {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    }).trim();
+}
+export function getStateDir(gitRoot) {
+    const root = gitRoot ?? getGitRoot();
+    const hash = crypto
+        .createHash("sha256")
+        .update(root)
+        .digest("hex")
+        .slice(0, 12);
+    return path.join(os.tmpdir(), "worker-manager", hash);
+}
+function ensureStateDir(stateDir) {
+    fs.mkdirSync(stateDir, { recursive: true });
+}
+// --- Orchestrator identity mapping ---
+// Maps Claude Code PID → orchestrator ID so hooks can find the right mailbox.
+function orchestratorMappingDir(stateDir) {
+    return path.join(stateDir, "orchestrators");
+}
+export function writeOrchestratorMapping(stateDir, ppid, orchestratorId) {
+    const dir = orchestratorMappingDir(stateDir);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, String(ppid)), orchestratorId);
+}
+export function readOrchestratorId(stateDir, ppid) {
+    try {
+        return fs
+            .readFileSync(path.join(orchestratorMappingDir(stateDir), String(ppid)), "utf-8")
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function removeOrchestratorMapping(stateDir, ppid) {
+    try {
+        fs.unlinkSync(path.join(orchestratorMappingDir(stateDir), String(ppid)));
+    }
+    catch { }
+}
+function registryPath(stateDir) {
+    return path.join(stateDir, "state.json");
+}
+export function readRegistry(stateDir) {
+    const file = registryPath(stateDir);
+    if (!fs.existsSync(file)) {
+        return { workers: {} };
+    }
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+export function writeRegistry(stateDir, registry) {
+    ensureStateDir(stateDir);
+    const file = registryPath(stateDir);
+    const tmpFile = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmpFile, JSON.stringify(registry, null, 2));
+    fs.renameSync(tmpFile, file);
+}
+export function updateWorker(stateDir, id, update) {
+    const registry = readRegistry(stateDir);
+    const worker = registry.workers[id];
+    if (!worker) {
+        throw new Error(`Worker '${id}' not found in registry`);
+    }
+    registry.workers[id] = { ...worker, ...update };
+    writeRegistry(stateDir, registry);
+}
+/**
+ * Write a mail message to the orchestrator's scoped mailbox at
+ * `mail/<orchestratorId>/`.
+ */
+export function writeMail(stateDir, message, orchestratorId) {
+    const mailDir = path.join(stateDir, "mail", orchestratorId);
+    fs.mkdirSync(mailDir, { recursive: true });
+    const filename = `${message.timestamp}-${message.id}.json`;
+    fs.writeFileSync(path.join(mailDir, filename), JSON.stringify(message, null, 2));
+}
+/**
+ * Read and flush all mail from a specific orchestrator's mailbox.
+ */
+export function readAndFlushMail(stateDir, orchestratorId) {
+    const mailDir = path.join(stateDir, "mail", orchestratorId);
+    if (!fs.existsSync(mailDir)) {
+        return [];
+    }
+    const files = fs.readdirSync(mailDir).filter((f) => f.endsWith(".json"));
+    files.sort();
+    const messages = [];
+    for (const file of files) {
+        const filePath = path.join(mailDir, file);
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            messages.push(JSON.parse(content));
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // Skip corrupted files
+        }
+    }
+    return messages;
+}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export type WorkerStatus = "running" | "completed" | "failed" | "asking" | "stopped";
+export type WorkerEntry = {
+    id: string;
+    name: string;
+    task: string;
+    status: WorkerStatus;
+    branch: string;
+    worktreePath: string;
+    tmuxSession: string;
+    createdAt: string;
+    completedAt?: string;
+    summary?: string;
+    useWorktree: boolean;
+};
+export type WorkerRegistry = {
+    workers: Record<string, WorkerEntry>;
+};
+export type MailMessage = {
+    id: string;
+    workerId: string;
+    workerName: string;
+    type: "completion" | "question";
+    content: string;
+    timestamp: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker.d.ts

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

package/dist/worker.js

@@ -0,0 +1,99 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { updateWorker, writeMail } from "./state.js";
+export async function startWorkerServer() {
+    const workerId = process.env.WORKER_ID;
+    const workerName = process.env.WORKER_NAME ?? workerId;
+    const stateDir = process.env.STATE_DIR;
+    const orchestratorId = process.env.ORCHESTRATOR_ID;
+    const server = new McpServer({
+        name: `worker-${workerId}`,
+        version: "0.0.1",
+    });
+    server.registerTool("complete", {
+        description: "Signal that you have completed your assigned task. Provide a summary of what you did.",
+        inputSchema: {
+            summary: z
+                .string()
+                .describe("Summary of what was accomplished and any notable changes"),
+        },
+    }, async ({ summary }) => {
+        try {
+            updateWorker(stateDir, workerId, {
+                status: "completed",
+                completedAt: new Date().toISOString(),
+                summary,
+            });
+            writeMail(stateDir, {
+                id: randomUUID(),
+                workerId,
+                workerName,
+                type: "completion",
+                content: summary,
+                timestamp: new Date().toISOString(),
+            }, orchestratorId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Completion recorded. The orchestrator has been notified.",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to record completion: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("ask", {
+        description: "Ask the orchestrator a question when you need clarification or are blocked.",
+        inputSchema: {
+            question: z.string().describe("Your question for the orchestrator"),
+        },
+    }, async ({ question }) => {
+        try {
+            updateWorker(stateDir, workerId, {
+                status: "asking",
+            });
+            writeMail(stateDir, {
+                id: randomUUID(),
+                workerId,
+                workerName,
+                type: "question",
+                content: question,
+                timestamp: new Date().toISOString(),
+            }, orchestratorId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Question sent to orchestrator. Wait for a response via your terminal input.",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to send question: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @lioneltay/worker-manager --hook",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @lioneltay/worker-manager --stop-hook",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lioneltay/worker-manager",
+  "version": "0.0.2",
+  "description": "Claude Code plugin for spawning and managing worker agents in isolated worktrees",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lioneltay/agent-forge",
+    "directory": "packages/claude-plugins/worker-manager"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "worker-manager": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    ".mcp.json",
+    "hooks",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@lioneltay/worktree-manager": "^0.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "typescript": "^5.7.3"
+  }
+}