claude-tempo 0.1.0

package/src/cli.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { start, status, init, server, up, down, help, version } from './cli/commands';
+import { runPreflight } from './cli/preflight';
+import * as out from './cli/output';
+
+interface ParsedArgs {
+  command: string;
+  positional: string[];
+  temporalAddress: string;
+  name?: string;
+  dir: string;
+  skipPreflight: boolean;
+  background: boolean;
+  keepMcp: boolean;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const result: ParsedArgs = {
+    command: 'help',
+    positional: [],
+    temporalAddress: process.env.TEMPORAL_ADDRESS || 'localhost:7233',
+    dir: process.cwd(),
+    skipPreflight: false,
+    background: false,
+    keepMcp: false,
+  };
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--temporal-address' && i + 1 < argv.length) {
+      result.temporalAddress = argv[++i];
+    } else if ((arg === '-n' || arg === '--name') && i + 1 < argv.length) {
+      result.name = argv[++i];
+    } else if (arg === '--dir' && i + 1 < argv.length) {
+      result.dir = argv[++i];
+    } else if (arg === '--skip-preflight') {
+      result.skipPreflight = true;
+    } else if (arg === '--background' || arg === '-d') {
+      result.background = true;
+    } else if (arg === '--keep-mcp') {
+      result.keepMcp = true;
+    } else if (arg === '--help' || arg === '-h') {
+      result.command = 'help';
+    } else if (arg === '--version' || arg === '-v') {
+      result.command = 'version';
+    } else if (!arg.startsWith('-')) {
+      result.positional.push(arg);
+    } else {
+      out.error(`Unknown option: ${arg}`);
+      out.log(`Run ${out.dim('claude-tempo help')} for usage.`);
+      process.exit(1);
+    }
+    i++;
+  }
+
+  if (result.positional.length > 0) {
+    result.command = result.positional[0];
+  }
+
+  return result;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const ensemble = args.positional[1] || process.env.CLAUDE_TEMPO_ENSEMBLE || 'default';
+
+  switch (args.command) {
+    case 'conduct':
+      await start({
+        ensemble,
+        conductor: true,
+        temporalAddress: args.temporalAddress,
+        name: args.name,
+        skipPreflight: args.skipPreflight,
+      });
+      break;
+
+    case 'start':
+      await start({
+        ensemble,
+        conductor: false,
+        temporalAddress: args.temporalAddress,
+        name: args.name,
+        skipPreflight: args.skipPreflight,
+      });
+      break;
+
+    case 'status':
+      await status({
+        ensemble: args.positional[1], // undefined = show all
+        temporalAddress: args.temporalAddress,
+      });
+      break;
+
+    case 'server':
+      await server({
+        temporalAddress: args.temporalAddress,
+        background: args.background,
+      });
+      break;
+
+    case 'down':
+      await down({
+        temporalAddress: args.temporalAddress,
+        removeMcp: !args.keepMcp,
+        dir: args.dir,
+      });
+      break;
+
+    case 'up':
+      await up({
+        ensemble,
+        temporalAddress: args.temporalAddress,
+        name: args.name,
+      });
+      break;
+
+    case 'init':
+      await init({ dir: args.dir });
+      break;
+
+    case 'preflight':
+      const result = await runPreflight({
+        temporalAddress: args.temporalAddress,
+        projectDir: args.dir,
+      });
+      for (const w of result.warnings) out.warn(w);
+      if (!result.ok) {
+        for (const e of result.errors) out.error(e);
+        process.exit(1);
+      }
+      out.success('All checks passed');
+      break;
+
+    case 'version':
+      version();
+      break;
+
+    case 'help':
+    default:
+      help();
+      break;
+  }
+}
+
+main().catch((err) => {
+  out.error(err.message || String(err));
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,25 @@
+export interface Config {
+  temporalAddress: string;
+  temporalNamespace: string;
+  taskQueue: string;
+  ensemble: string;
+}
+
+export function getConfig(): Config {
+  return {
+    temporalAddress: process.env.TEMPORAL_ADDRESS ?? 'localhost:7233',
+    temporalNamespace: process.env.TEMPORAL_NAMESPACE ?? 'default',
+    taskQueue: process.env.CLAUDE_TEMPO_TASK_QUEUE ?? 'claude-tempo',
+    ensemble: process.env.CLAUDE_TEMPO_ENSEMBLE ?? 'default',
+  };
+}
+
+/** Build a workflow ID for a player session: claude-session-{ensemble}-{playerId} */
+export function sessionWorkflowId(ensemble: string, playerId: string): string {
+  return `claude-session-${ensemble}-${playerId}`;
+}
+
+/** Build a workflow ID for a conductor: claude-session-{ensemble}-conductor */
+export function conductorWorkflowId(ensemble: string): string {
+  return `claude-session-${ensemble}-conductor`;
+}

package/src/server.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import * as crypto from 'crypto';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client, Connection, WorkflowIdConflictPolicy } from '@temporalio/client';
+import { getConfig, conductorWorkflowId } from './config';
+import { createWorker } from './worker';
+import { SessionInput } from './types';
+import { registerEnsembleTool } from './tools/ensemble';
+import { registerCueTool } from './tools/cue';
+import { registerSetPartTool } from './tools/set-part';
+import { registerListenTool } from './tools/listen';
+import { registerRecruitTool } from './tools/recruit';
+import { registerReportTool } from './tools/report';
+import { registerTerminateTool } from './tools/terminate';
+import { registerSetNameTool } from './tools/set-name';
+import { startMessagePoller } from './channel';
+
+const log = (...args: unknown[]) => console.error('[claude-tempo]', ...args);
+
+function getGitInfo(workDir: string): { gitRoot?: string; gitBranch?: string } {
+  try {
+    const gitRoot = execSync('git rev-parse --show-toplevel', {
+      cwd: workDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    let gitBranch: string | undefined;
+    try {
+      gitBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+        cwd: workDir,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      // not on a branch
+    }
+    return { gitRoot, gitBranch };
+  } catch {
+    return {};
+  }
+}
+
+async function main() {
+  // Only activate when explicitly opted in via CLAUDE_TEMPO_ENSEMBLE
+  if (!process.env.CLAUDE_TEMPO_ENSEMBLE) {
+    log('CLAUDE_TEMPO_ENSEMBLE not set — MCP server idle (no workflow started)');
+    // Keep the process alive so Claude Code doesn't see a crash, but do nothing
+    const transport = new StdioServerTransport();
+    const idleServer = new McpServer({ name: 'claude-tempo', version: '0.1.0' });
+    await idleServer.connect(transport);
+    return;
+  }
+
+  const config = getConfig();
+  const isConductor = process.env.CLAUDE_TEMPO_CONDUCTOR === 'true';
+  let playerId = isConductor ? 'conductor' : crypto.randomBytes(4).toString('hex');
+  const getPlayerId = () => playerId;
+  const setPlayerId = (id: string) => { playerId = id; };
+  const workDir = process.cwd();
+  const { gitRoot, gitBranch } = getGitInfo(workDir);
+
+  log(`Starting ${isConductor ? 'conductor' : `peer ${playerId}`} in ${workDir}`);
+
+  // Connect Temporal client
+  const connection = await Connection.connect({
+    address: config.temporalAddress,
+  });
+  const client = new Client({
+    connection,
+    namespace: config.temporalNamespace,
+  });
+
+  // Start the Temporal worker (runs in background)
+  const worker = await createWorker(config);
+  const workerRunPromise = worker.run();
+  workerRunPromise.catch((err) => {
+    log('Worker error:', err);
+    process.exit(1);
+  });
+
+  // Start the session workflow
+  const workflowId = isConductor
+    ? conductorWorkflowId(config.ensemble)
+    : `claude-session-${config.ensemble}-${playerId}`;
+
+  const sessionInput: SessionInput = {
+    metadata: {
+      playerId,
+      ensemble: config.ensemble,
+      hostname: os.hostname(),
+      workDir,
+      gitRoot,
+      gitBranch,
+      isConductor,
+    },
+    autoSummary: `Session in ${path.basename(workDir)}`,
+  };
+
+  const handle = await client.workflow.start('claudeSessionWorkflow', {
+    workflowId,
+    taskQueue: config.taskQueue,
+    args: [sessionInput],
+    workflowIdConflictPolicy: WorkflowIdConflictPolicy.USE_EXISTING,
+    workflowExecutionTimeout: '24 hours',
+    searchAttributes: {
+      ...(gitRoot ? { ClaudeTempoGitRoot: [gitRoot] } : {}),
+      ClaudeTempoHostname: [os.hostname()],
+      ClaudeTempoEnsemble: [config.ensemble],
+      ClaudeTempoPlayerId: [playerId],
+    },
+  });
+  log(`Workflow ${workflowId} started (or reconnected)`);
+
+  // If there's a conductor running, announce ourselves
+  if (!isConductor) {
+    try {
+      const conductorHandle = client.workflow.getHandle(conductorWorkflowId(config.ensemble));
+      await conductorHandle.signal('receiveMessage', {
+        from: playerId,
+        text: `Player ${playerId} joined from ${workDir}`,
+      });
+    } catch {
+      // No conductor running — that's fine
+    }
+  }
+
+  // Create MCP server
+  const serverInstructions = `You are part of the "${config.ensemble}" ensemble of Claude Code sessions coordinated via Temporal. ` +
+    `Your temporary player ID is "${playerId}". ` +
+    `IMPORTANT: If you receive a message instructing you to call \`set_name\`, do so immediately before anything else. ` +
+    `When you receive a message from another session, treat it like a coworker asking for help — respond promptly, then resume your work. ` +
+    `Use \`set_name\` to give yourself a human-readable name. ` +
+    `Use \`ensemble\` to see who else is active. ` +
+    `Use \`cue\` to reply directly to the player who messaged you, or to ask others for help. ` +
+    `Use \`recruit\` if you need a session in a directory where none exists. ` +
+    `Use \`report\` to notify the conductor of task completion, blockers, or questions — always report when you finish a recruited task.`;
+
+  const mcpServer = new McpServer({
+    name: 'claude-tempo',
+    version: '0.1.0',
+  }, {
+    capabilities: {
+      experimental: { 'claude/channel': {} },
+    },
+    instructions: serverInstructions,
+  });
+
+  // Register tools
+  registerEnsembleTool(mcpServer, client, config, getPlayerId, workflowId);
+  registerCueTool(mcpServer, client, config, getPlayerId);
+  registerSetPartTool(mcpServer, handle);
+  registerSetNameTool(mcpServer, client, config, handle, getPlayerId, setPlayerId);
+  registerListenTool(mcpServer, handle);
+  registerRecruitTool(mcpServer, client, config, getPlayerId);
+  registerReportTool(mcpServer, client, config, getPlayerId);
+  registerTerminateTool(mcpServer, client, config, getPlayerId);
+
+  // Start message poller — push messages into Claude Code via channel notifications
+  const stopPoller = startMessagePoller(handle, async (messages) => {
+    for (const msg of messages) {
+      log(`Message from ${msg.from}: ${msg.text}`);
+      try {
+        await mcpServer.server.notification({
+          method: 'notifications/claude/channel',
+          params: {
+            content: msg.text,
+            meta: {
+              from_player: msg.from,
+              sent_at: msg.timestamp,
+            },
+          },
+        });
+      } catch (err) {
+        log('Channel notification error:', err);
+      }
+    }
+  });
+
+  // Connect MCP transport
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+  log('MCP server connected');
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    log('Shutting down...');
+    stopPoller();
+    try {
+      await handle.signal('shutdown');
+    } catch {
+      try {
+        await handle.cancel();
+      } catch {
+        // workflow may already be gone
+      }
+    }
+    worker.shutdown();
+    await workerRunPromise.catch(() => {});
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/src/spawn.ts

@@ -0,0 +1,213 @@
+import { spawn, execFileSync } from 'child_process';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+const log = (...args: unknown[]) => console.error('[claude-tempo:spawn]', ...args);
+
+/** POSIX shell-safe single-quoting (works in bash, zsh, and fish) */
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/** Resolve the absolute path to the `claude` binary */
+export function resolveClaudePath(): string {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    return execFileSync(cmd, ['claude'], { encoding: 'utf8' }).trim().split('\n')[0];
+  } catch {
+    return 'claude';
+  }
+}
+
+/**
+ * Detect the macOS terminal the user is actually running in.
+ *
+ * Priority:
+ *  1. TERM_PROGRAM env var (most reliable when available — set by the terminal itself)
+ *  2. Check frontmost app via AppleScript (detects what the user is actively using)
+ *  3. Fall back to Terminal.app
+ */
+export function detectMacTerminal(): 'ghostty' | 'iterm2' | 'terminal' {
+  const termProgram = (process.env.TERM_PROGRAM || '').toLowerCase();
+  if (termProgram === 'ghostty') return 'ghostty';
+  if (termProgram === 'iterm.app' || termProgram === 'iterm2') return 'iterm2';
+  if (termProgram === 'apple_terminal') return 'terminal';
+
+  // MCP servers may not inherit TERM_PROGRAM — check which terminal app is running
+  // Prefer frontmost app detection over pgrep to avoid false positives
+  try {
+    const frontApp = execFileSync('osascript', ['-e',
+      'tell application "System Events" to get name of first application process whose frontmost is true',
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().toLowerCase();
+    if (frontApp === 'ghostty') return 'ghostty';
+    if (frontApp === 'iterm2') return 'iterm2';
+    if (frontApp === 'terminal') return 'terminal';
+  } catch { /* ignore */ }
+
+  // Last resort: check running processes
+  try {
+    execFileSync('pgrep', ['-x', 'ghostty'], { stdio: 'ignore' });
+    return 'ghostty';
+  } catch { /* not running */ }
+  try {
+    execFileSync('pgrep', ['-x', 'iTerm2'], { stdio: 'ignore' });
+    return 'iterm2';
+  } catch { /* not running */ }
+
+  return 'terminal';
+}
+
+/** Find the first available terminal emulator on Linux */
+export function findLinuxTerminal(): string | null {
+  const candidates = ['gnome-terminal', 'konsole', 'x-terminal-emulator', 'xfce4-terminal', 'xterm'];
+  for (const term of candidates) {
+    try {
+      execFileSync('which', [term], { stdio: 'ignore' });
+      return term;
+    } catch {
+      // not found, try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a shell command string that sets env vars and runs claude.
+ * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
+ */
+export function buildClaudeCommand(
+  claudeBin: string,
+  claudeArgs: string[],
+  envVars: Record<string, string>,
+): string {
+  const envInline = Object.entries(envVars)
+    .map(([k, v]) => `${k}=${shellQuote(v)}`)
+    .join(' ');
+  const args = claudeArgs.map(a => shellQuote(a)).join(' ');
+  return envInline ? `${envInline} ${claudeBin} ${args}` : `${claudeBin} ${args}`;
+}
+
+/**
+ * Spawn a Claude Code session in a visible terminal window.
+ *
+ * Strategy per terminal:
+ *  - Ghostty: `initial input` into a normal window (preserves full shell env)
+ *  - iTerm2: `write text` via AppleScript (same approach)
+ *  - Terminal.app: .command script with shell profile sourcing
+ *  - Windows: shell:true with env vars
+ *  - Linux: terminal emulator with -e flag
+ */
+export function spawnInTerminal(
+  claudeArgs: string[],
+  workDir: string,
+  envVars: Record<string, string>,
+): { pid: number | undefined } {
+  const claudeBin = resolveClaudePath();
+  const claudeInvocation = buildClaudeCommand(claudeBin, claudeArgs, envVars);
+
+  if (process.platform === 'darwin') {
+    const detected = detectMacTerminal();
+    log(`Terminal detection: TERM_PROGRAM=${JSON.stringify(process.env.TERM_PROGRAM)}, detected=${detected}`);
+
+    if (detected === 'ghostty') {
+      const osaScript = `
+        tell application "Ghostty"
+          set cfg to new surface configuration
+          set initial working directory of cfg to ${JSON.stringify(workDir)}
+          set initial input of cfg to ${JSON.stringify(claudeInvocation + '\n')}
+          set win to new window with configuration cfg
+        end tell`;
+      log('Using Ghostty initial-input path');
+      const child = spawn('osascript', ['-e', osaScript], {
+        detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      child.stderr?.on('data', (d: Buffer) => log('osascript stderr:', d.toString()));
+      child.stdout?.on('data', (d: Buffer) => log('osascript stdout:', d.toString()));
+      child.unref();
+      return { pid: child.pid };
+    }
+
+    if (detected === 'iterm2') {
+      const osaScript = `
+        tell application "iTerm2"
+          set newWindow to (create window with default profile)
+          tell current session of newWindow
+            write text "cd ${shellQuote(workDir)} && ${claudeInvocation}"
+          end tell
+        end tell`;
+      log('Using iTerm2 write-text path');
+      const child = spawn('osascript', ['-e', osaScript], {
+        detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      child.stderr?.on('data', (d: Buffer) => log('osascript stderr:', d.toString()));
+      child.unref();
+      return { pid: child.pid };
+    }
+
+    // Terminal.app: .command file with shell profile sourcing
+    const userShell = process.env.SHELL || '/bin/zsh';
+    const scriptPath = join(tmpdir(), `claude-tempo-recruit-${Date.now()}.command`);
+    let profileSource: string;
+    if (userShell.endsWith('/fish')) {
+      profileSource = `exec fish -c "cd ${shellQuote(workDir)} && ${claudeInvocation}"`;
+    } else {
+      profileSource = [
+        `[ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null`,
+        `[ -f "$HOME/.bashrc" ] && source "$HOME/.bashrc" 2>/dev/null`,
+        `[ -f "$HOME/.nvm/nvm.sh" ] && source "$HOME/.nvm/nvm.sh" 2>/dev/null`,
+        `command -v fnm >/dev/null && eval "$(fnm env)" 2>/dev/null`,
+      ].join('\n');
+    }
+    const envExports = Object.entries(envVars)
+      .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
+      .join('\n');
+    const lines = [
+      '#!/bin/bash',
+      profileSource,
+      envExports,
+      `cd ${shellQuote(workDir)}`,
+      `${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`,
+    ];
+    writeFileSync(scriptPath, lines.join('\n') + '\n', { mode: 0o755 });
+    log('Using Terminal.app .command path:', scriptPath);
+    const child = spawn('open', [scriptPath], { detached: true, stdio: 'ignore' });
+    child.unref();
+    return { pid: child.pid };
+  }
+
+  if (process.platform === 'win32') {
+    const child = spawn(claudeBin, claudeArgs, {
+      cwd: workDir,
+      detached: true,
+      stdio: 'ignore',
+      shell: true,
+      env: { ...process.env, ...envVars },
+    });
+    child.unref();
+    return { pid: child.pid };
+  }
+
+  // Linux
+  const envExports = Object.entries(envVars)
+    .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
+    .join('; ');
+  const fullCmd = `${envExports}; cd ${shellQuote(workDir)} && ${shellQuote(claudeBin)} ${claudeArgs.map(a => shellQuote(a)).join(' ')}`;
+
+  const terminal = findLinuxTerminal();
+  if (!terminal) {
+    log('No terminal emulator found on Linux, falling back to headless spawn');
+    const child = spawn('bash', ['-c', fullCmd], { detached: true, stdio: 'ignore' });
+    child.unref();
+    return { pid: child.pid };
+  }
+
+  let child;
+  if (terminal === 'gnome-terminal') {
+    child = spawn(terminal, ['--', 'bash', '-c', fullCmd], { detached: true, stdio: 'ignore' });
+  } else {
+    child = spawn(terminal, ['-e', 'bash', '-c', fullCmd], { detached: true, stdio: 'ignore' });
+  }
+  child.unref();
+  return { pid: child.pid };
+}

package/src/tools/cue.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config, sessionWorkflowId } from '../config';
+import { resolveSession } from './resolve';
+import { defineTool } from './helpers';
+
+const log = (...args: unknown[]) => console.error('[claude-tempo:cue]', ...args);
+
+export function registerCueTool(
+  server: McpServer,
+  client: Client,
+  config: Config,
+  getPlayerId: () => string,
+) {
+  defineTool(
+    server,
+    'cue',
+    'Send a message to another Claude Code session by player name. Delivered instantly via Temporal signal.',
+    {
+      playerId: z.string().describe('The player name of the target session'),
+      message: z.string().describe('The message to send'),
+    },
+    async (args) => {
+      const { playerId, message } = args as { playerId: string; message: string };
+      try {
+        const handle = await resolveSession(client, config.ensemble, playerId);
+        if (!handle) {
+          return {
+            content: [{ type: 'text' as const, text: `No active session found with name "${playerId}".` }],
+            isError: true,
+          };
+        }
+        await handle.signal('receiveMessage', {
+          from: getPlayerId(),
+          text: message,
+        });
+
+        // Record outbound message on sender's own workflow
+        try {
+          const senderHandle = client.workflow.getHandle(
+            sessionWorkflowId(config.ensemble, getPlayerId()),
+          );
+          await senderHandle.signal('recordSentMessage', { to: playerId, text: message });
+        } catch (err) {
+          log('Failed to record sent message:', err);
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: `Message sent to ${playerId}.` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to send message to ${playerId}: ${err}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}