@atercates/claude-deck 0.2.1

package/lib/worktrees.ts

@@ -0,0 +1,262 @@
+/**
+ * Git Worktree management for isolated feature development
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import * as path from "path";
+import * as fs from "fs";
+import * as os from "os";
+import {
+  isGitRepo,
+  branchExists,
+  getRepoName,
+  slugify,
+  generateBranchName,
+} from "./git";
+
+const execAsync = promisify(exec);
+
+// Base directory for all worktrees
+const WORKTREES_DIR = path.join(os.homedir(), ".claude-deck", "worktrees");
+
+export interface WorktreeInfo {
+  worktreePath: string;
+  branchName: string;
+  baseBranch: string;
+  projectPath: string;
+  projectName: string;
+}
+
+export interface CreateWorktreeOptions {
+  projectPath: string;
+  featureName: string;
+  baseBranch?: string;
+}
+
+/**
+ * Ensure the worktrees directory exists
+ */
+async function ensureWorktreesDir(): Promise<void> {
+  await fs.promises.mkdir(WORKTREES_DIR, { recursive: true });
+}
+
+/**
+ * Resolve a path, expanding ~ to home directory
+ */
+function resolvePath(p: string): string {
+  return p.replace(/^~/, os.homedir());
+}
+
+/**
+ * Generate a unique worktree directory name
+ */
+function generateWorktreeDirName(
+  projectName: string,
+  featureName: string
+): string {
+  const featureSlug = slugify(featureName);
+  return `${projectName}-${featureSlug}`;
+}
+
+/**
+ * Create a new worktree for a feature branch
+ */
+export async function createWorktree(
+  options: CreateWorktreeOptions
+): Promise<WorktreeInfo> {
+  const { projectPath, featureName, baseBranch = "main" } = options;
+
+  const resolvedProjectPath = resolvePath(projectPath);
+
+  // Validate project is a git repo
+  if (!(await isGitRepo(resolvedProjectPath))) {
+    throw new Error(`Not a git repository: ${projectPath}`);
+  }
+
+  // Generate branch name
+  const branchName = generateBranchName(featureName);
+
+  // Check if branch already exists
+  if (await branchExists(resolvedProjectPath, branchName)) {
+    throw new Error(`Branch already exists: ${branchName}`);
+  }
+
+  // Generate worktree path
+  const projectName = getRepoName(resolvedProjectPath);
+  const worktreeDirName = generateWorktreeDirName(projectName, featureName);
+  const worktreePath = path.join(WORKTREES_DIR, worktreeDirName);
+
+  // Check if worktree path already exists
+  if (fs.existsSync(worktreePath)) {
+    throw new Error(`Worktree path already exists: ${worktreePath}`);
+  }
+
+  // Ensure worktrees directory exists
+  await ensureWorktreesDir();
+
+  // Create the worktree with a new branch
+  // Try multiple ref formats to avoid "ambiguous refname" errors
+  const refFormats = [
+    `origin/${baseBranch}`, // Try remote first (most explicit)
+    `refs/heads/${baseBranch}`, // Then local branch
+    baseBranch, // Finally, bare name as fallback
+  ];
+
+  let lastError: Error | null = null;
+  for (const ref of refFormats) {
+    try {
+      await execAsync(
+        `git -C "${resolvedProjectPath}" worktree add -b "${branchName}" "${worktreePath}" "${ref}"`,
+        { timeout: 30000 }
+      );
+      lastError = null;
+      break; // Success!
+    } catch (error: unknown) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      // Continue to next ref format
+    }
+  }
+
+  if (lastError) {
+    throw new Error(`Failed to create worktree: ${lastError.message}`);
+  }
+
+  return {
+    worktreePath,
+    branchName,
+    baseBranch,
+    projectPath: resolvedProjectPath,
+    projectName,
+  };
+}
+
+/**
+ * Delete a worktree and optionally its branch
+ */
+export async function deleteWorktree(
+  worktreePath: string,
+  projectPath: string,
+  deleteBranch = false
+): Promise<void> {
+  const resolvedProjectPath = resolvePath(projectPath);
+  const resolvedWorktreePath = resolvePath(worktreePath);
+
+  // Get the branch name before removing (for optional deletion)
+  let branchName: string | null = null;
+  if (deleteBranch) {
+    try {
+      const { stdout } = await execAsync(
+        `git -C "${resolvedWorktreePath}" rev-parse --abbrev-ref HEAD`,
+        { timeout: 5000 }
+      );
+      branchName = stdout.trim();
+    } catch {
+      // Ignore - worktree might already be gone
+    }
+  }
+
+  // Remove the worktree
+  try {
+    await execAsync(
+      `git -C "${resolvedProjectPath}" worktree remove "${resolvedWorktreePath}" --force`,
+      { timeout: 30000 }
+    );
+  } catch {
+    // If git worktree remove fails, try manual cleanup
+    if (fs.existsSync(resolvedWorktreePath)) {
+      await fs.promises.rm(resolvedWorktreePath, {
+        recursive: true,
+        force: true,
+      });
+    }
+    // Prune worktree references
+    try {
+      await execAsync(`git -C "${resolvedProjectPath}" worktree prune`, {
+        timeout: 10000,
+      });
+    } catch {
+      // Ignore prune errors
+    }
+  }
+
+  // Optionally delete the branch
+  if (
+    deleteBranch &&
+    branchName &&
+    branchName !== "main" &&
+    branchName !== "master"
+  ) {
+    try {
+      await execAsync(
+        `git -C "${resolvedProjectPath}" branch -D "${branchName}"`,
+        { timeout: 10000 }
+      );
+    } catch {
+      // Ignore branch deletion errors (might be merged or checked out elsewhere)
+    }
+  }
+}
+
+/**
+ * List all worktrees for a project
+ */
+export async function listWorktrees(projectPath: string): Promise<
+  Array<{
+    path: string;
+    branch: string;
+    head: string;
+  }>
+> {
+  const resolvedProjectPath = resolvePath(projectPath);
+
+  try {
+    const { stdout } = await execAsync(
+      `git -C "${resolvedProjectPath}" worktree list --porcelain`,
+      { timeout: 10000 }
+    );
+
+    const worktrees: Array<{ path: string; branch: string; head: string }> = [];
+    const entries = stdout.split("\n\n").filter(Boolean);
+
+    for (const entry of entries) {
+      const lines = entry.split("\n");
+      let worktreePath = "";
+      let branch = "";
+      let head = "";
+
+      for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+          worktreePath = line.slice(9);
+        } else if (line.startsWith("branch ")) {
+          branch = line.slice(7).replace("refs/heads/", "");
+        } else if (line.startsWith("HEAD ")) {
+          head = line.slice(5);
+        }
+      }
+
+      if (worktreePath) {
+        worktrees.push({ path: worktreePath, branch, head });
+      }
+    }
+
+    return worktrees;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a path is inside an ClaudeDeck worktree
+ */
+export function isClaudeDeckWorktree(worktreePath: string): boolean {
+  const resolvedPath = resolvePath(worktreePath);
+  return resolvedPath.startsWith(WORKTREES_DIR);
+}
+
+/**
+ * Get the worktrees base directory
+ */
+export function getWorktreesDir(): string {
+  return WORKTREES_DIR;
+}

package/mcp/orchestration-server.ts

@@ -0,0 +1,438 @@
+#!/usr/bin/env npx ts-node
+/**
+ * MCP Server for Session Orchestration
+ *
+ * Exposes tools for any Claude session to become a "conductor" that spawns
+ * and manages worker sessions. Each worker gets its own git worktree.
+ *
+ * Setup (one-time, in ~/.claude/settings.json or project .mcp.json):
+ *   {
+ *     "mcpServers": {
+ *       "claude-deck": {
+ *         "command": "npx",
+ *         "args": ["tsx", "/path/to/claude-deck/mcp/orchestration-server.ts"],
+ *         "env": {
+ *           "AGENTOS_URL": "http://localhost:3011"
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Usage: Any session can spawn workers by calling spawn_worker with its own
+ * session ID as conductorId. The UI will show the conductor/worker hierarchy.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const AGENTOS_URL = process.env.AGENTOS_URL || "http://localhost:3011";
+
+// Optional: Get conductor session ID from environment (can also be passed per-call)
+const DEFAULT_CONDUCTOR_ID = process.env.CONDUCTOR_SESSION_ID || "";
+
+async function apiCall(path: string, options?: RequestInit) {
+  const url = `${AGENTOS_URL}${path}`;
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+  return response.json();
+}
+
+const server = new Server(
+  {
+    name: "claude-deck-orchestration",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "spawn_worker",
+        description:
+          "Spawn a new worker session to handle a task. Creates an isolated git worktree for the worker.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            conductorId: {
+              type: "string",
+              description:
+                "Your session ID (the conductor). Required unless CONDUCTOR_SESSION_ID env var is set.",
+            },
+            task: {
+              type: "string",
+              description: "The task/prompt to send to the worker",
+            },
+            workingDirectory: {
+              type: "string",
+              description:
+                "The git repository path for the worker to operate in",
+            },
+            branchName: {
+              type: "string",
+              description:
+                "Optional branch name for the worktree (auto-generated if not provided)",
+            },
+            useWorktree: {
+              type: "boolean",
+              description:
+                "Whether to create an isolated worktree (default: true)",
+              default: true,
+            },
+            model: {
+              type: "string",
+              description: "Model to use (sonnet, opus, haiku)",
+              default: "sonnet",
+            },
+          },
+          required: ["task", "workingDirectory"],
+        },
+      },
+      {
+        name: "list_workers",
+        description: "List all worker sessions spawned by a conductor",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            conductorId: {
+              type: "string",
+              description:
+                "The conductor session ID. Required unless CONDUCTOR_SESSION_ID env var is set.",
+            },
+          },
+        },
+      },
+      {
+        name: "get_worker_output",
+        description: "Get recent terminal output from a worker",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            workerId: {
+              type: "string",
+              description: "The worker session ID",
+            },
+            lines: {
+              type: "number",
+              description: "Number of lines to retrieve (default: 50)",
+              default: 50,
+            },
+          },
+          required: ["workerId"],
+        },
+      },
+      {
+        name: "send_to_worker",
+        description: "Send a message or command to a worker",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            workerId: {
+              type: "string",
+              description: "The worker session ID",
+            },
+            message: {
+              type: "string",
+              description: "The message to send",
+            },
+          },
+          required: ["workerId", "message"],
+        },
+      },
+      {
+        name: "complete_worker",
+        description: "Mark a worker as completed (task finished successfully)",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            workerId: {
+              type: "string",
+              description: "The worker session ID",
+            },
+          },
+          required: ["workerId"],
+        },
+      },
+      {
+        name: "kill_worker",
+        description:
+          "Kill a worker session and optionally clean up its worktree",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            workerId: {
+              type: "string",
+              description: "The worker session ID",
+            },
+            cleanupWorktree: {
+              type: "boolean",
+              description: "Whether to delete the worktree (default: false)",
+              default: false,
+            },
+          },
+          required: ["workerId"],
+        },
+      },
+      {
+        name: "get_workers_summary",
+        description: "Get a summary count of workers by status",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            conductorId: {
+              type: "string",
+              description:
+                "The conductor session ID. Required unless CONDUCTOR_SESSION_ID env var is set.",
+            },
+          },
+        },
+      },
+    ],
+  };
+});
+
+// Helper to get conductor ID from args or env
+function getConductorId(
+  args: Record<string, unknown> | undefined
+): string | null {
+  return (args?.conductorId as string) || DEFAULT_CONDUCTOR_ID || null;
+}
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "spawn_worker": {
+        const conductorId = getConductorId(args);
+        if (!conductorId) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Error: conductorId is required. Pass it as a parameter or set CONDUCTOR_SESSION_ID env var.",
+              },
+            ],
+          };
+        }
+        const result = await apiCall("/api/orchestrate/spawn", {
+          method: "POST",
+          body: JSON.stringify({
+            conductorSessionId: conductorId,
+            task: args?.task,
+            workingDirectory: args?.workingDirectory,
+            branchName: args?.branchName,
+            useWorktree: args?.useWorktree ?? true,
+            model: args?.model || "sonnet",
+          }),
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result.error
+                ? `Error: ${result.error}`
+                : `Worker spawned successfully!\nID: ${result.session.id}\nName: ${result.session.name}\nWorktree: ${result.session.worktree_path || "none"}`,
+            },
+          ],
+        };
+      }
+
+      case "list_workers": {
+        const conductorId = getConductorId(args);
+        if (!conductorId) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Error: conductorId is required. Pass it as a parameter or set CONDUCTOR_SESSION_ID env var.",
+              },
+            ],
+          };
+        }
+        const result = await apiCall(
+          `/api/orchestrate/workers?conductorId=${conductorId}`
+        );
+        if (result.error) {
+          return {
+            content: [
+              { type: "text" as const, text: `Error: ${result.error}` },
+            ],
+          };
+        }
+        const workers = result.workers || [];
+        if (workers.length === 0) {
+          return {
+            content: [
+              { type: "text" as const, text: "No workers spawned yet." },
+            ],
+          };
+        }
+        const list = workers
+          .map(
+            (w: {
+              id: string;
+              name: string;
+              status: string;
+              task: string;
+              branchName: string | null;
+            }) =>
+              `- [${w.status.toUpperCase()}] ${w.name} (${w.id.slice(0, 8)})\n  Task: ${w.task}\n  Branch: ${w.branchName || "none"}`
+          )
+          .join("\n\n");
+        return {
+          content: [{ type: "text" as const, text: `Workers:\n\n${list}` }],
+        };
+      }
+
+      case "get_worker_output": {
+        const result = await apiCall(
+          `/api/orchestrate/workers/${args?.workerId}?lines=${args?.lines || 50}`
+        );
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result.error
+                ? `Error: ${result.error}`
+                : result.output || "(no output)",
+            },
+          ],
+        };
+      }
+
+      case "send_to_worker": {
+        const result = await apiCall(
+          `/api/orchestrate/workers/${args?.workerId}`,
+          {
+            method: "POST",
+            body: JSON.stringify({
+              action: "send",
+              message: args?.message,
+            }),
+          }
+        );
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result.error
+                ? `Error: ${result.error}`
+                : "Message sent successfully.",
+            },
+          ],
+        };
+      }
+
+      case "complete_worker": {
+        const result = await apiCall(
+          `/api/orchestrate/workers/${args?.workerId}`,
+          {
+            method: "POST",
+            body: JSON.stringify({ action: "complete" }),
+          }
+        );
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result.error
+                ? `Error: ${result.error}`
+                : "Worker marked as completed.",
+            },
+          ],
+        };
+      }
+
+      case "kill_worker": {
+        const cleanup = args?.cleanupWorktree ? "?cleanup=true" : "";
+        const result = await apiCall(
+          `/api/orchestrate/workers/${args?.workerId}${cleanup}`,
+          { method: "DELETE" }
+        );
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: result.error
+                ? `Error: ${result.error}`
+                : "Worker killed successfully.",
+            },
+          ],
+        };
+      }
+
+      case "get_workers_summary": {
+        const conductorId = getConductorId(args);
+        if (!conductorId) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Error: conductorId is required. Pass it as a parameter or set CONDUCTOR_SESSION_ID env var.",
+              },
+            ],
+          };
+        }
+        const result = await apiCall(
+          `/api/orchestrate/workers?conductorId=${conductorId}&summary=true`
+        );
+        if (result.error) {
+          return {
+            content: [
+              { type: "text" as const, text: `Error: ${result.error}` },
+            ],
+          };
+        }
+        const s = result.summary;
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Workers Summary:\n- Total: ${s.total}\n- Pending: ${s.pending}\n- Running: ${s.running}\n- Waiting: ${s.waiting}\n- Completed: ${s.completed}\n- Failed: ${s.failed}`,
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],
+        };
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`,
+        },
+      ],
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("ClaudeDeck Orchestration MCP Server started");
+}
+
+main().catch(console.error);