claude-multi-session 1.0.0

package/bin/mcp.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * claude-multi-session MCP Server entry point.
+ *
+ * This starts the MCP (Model Context Protocol) server that exposes
+ * multi-session tools to Claude Code as native tools.
+ *
+ * Claude Code connects to this server via stdio. Once connected,
+ * tools like spawn_session, send_message, delegate_task appear
+ * in Claude's tool list — just like Read, Edit, Grep, etc.
+ *
+ * Usage (in Claude Code MCP config):
+ *   {
+ *     "mcpServers": {
+ *       "multi-session": {
+ *         "command": "cms-mcp"
+ *       }
+ *     }
+ *   }
+ *
+ * Or run directly:
+ *   node bin/mcp.js
+ */
+
+const { startServer } = require('../src/mcp-server');
+startServer();

package/bin/setup.js

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║  claude-multi-session — Setup Wizard                         ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * Automatically registers the multi-session MCP server with Claude Code.
+ *
+ * Usage:
+ *   cms setup                  Interactive setup wizard
+ *   cms setup --global         Skip prompt, install globally
+ *   cms setup --local          Skip prompt, install locally
+ *   cms setup --uninstall      Remove MCP entry + CLAUDE.md section
+ *   cms setup --postinstall    (Internal) Print hint after npm install
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+// The name of the MCP server entry in settings.json
+const MCP_SERVER_NAME = 'multi-session';
+
+// Marker used to identify the strategy section in CLAUDE.md
+// (so we can detect duplicates and remove on uninstall)
+const CLAUDE_MD_START_MARKER = '<!-- claude-multi-session:start -->';
+const CLAUDE_MD_END_MARKER = '<!-- claude-multi-session:end -->';
+
+// ============================================================================
+// Strategy Guide Content (concise version of STRATEGY.md)
+// ============================================================================
+
+// This gets appended to CLAUDE.md when the user opts in.
+// It's a condensed version — just the decision framework and key rules.
+const STRATEGY_CONTENT = `
+${CLAUDE_MD_START_MARKER}
+
+## Multi-Session Strategy (claude-multi-session)
+
+### When to Delegate
+- **3+ independent parts** — run in parallel (e.g., login + signup + reset)
+- **Task too large for one context** — full features with tests
+- **Different models needed** — haiku for lookups, opus for architecture
+- **Risky operations** — delegate with safety limits
+
+### When NOT to Delegate
+- Simple tasks (< 5 min, < 3 files) — do it yourself
+- Tightly coupled changes — must happen atomically
+- Just reading/exploring — use Read, Grep, Glob directly
+
+### Decision Flow
+1. Simple task? → Do it yourself
+2. Can split into independent parts? → Delegate each in parallel
+3. Needs safety limits? → Use \`delegate_task\` with \`max_cost\` / \`max_turns\`
+4. Otherwise → \`spawn_session\` + \`send_message\` for direct control
+
+### Model Selection
+| Task | Model |
+|------|-------|
+| Simple lookups, counting | haiku |
+| Standard edits, bug fixes, tests | sonnet |
+| Architecture, complex refactoring | opus |
+
+### The Correction Loop
+1. \`delegate_task\` → read result
+2. Status = completed? → evaluate quality
+3. Good? → \`finish_task\` | Bad? → \`continue_task\` with specific fixes
+4. Hopeless? → \`abort_task\`, try differently
+
+### Anti-Patterns
+- Don't delegate trivial tasks (spawning overhead isn't worth it)
+- Don't use \`full\` preset by default (use \`edit\`, escalate if needed)
+- Don't send vague corrections ("fix it") — be specific
+- Don't coordinate parallel sessions editing the SAME file (conflicts)
+- Don't forget to \`finish_task\` — stopped sessions consume stored data
+
+${CLAUDE_MD_END_MARKER}
+`;
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Ask the user a question and return their answer.
+ * Uses Node's readline module — zero dependencies.
+ */
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Print a styled log line.
+ * @param {string} msg - The message to print
+ * @param {'info'|'success'|'warn'|'error'} [level] - Optional level
+ */
+function log(msg, level) {
+  const prefix = {
+    info: '  ',
+    success: '  ✓ ',
+    warn: '  ⚠ ',
+    error: '  ✗ ',
+  }[level || 'info'];
+  console.log(prefix + msg);
+}
+
+/**
+ * Figure out whether this package was installed globally or locally,
+ * and return the right MCP server command config.
+ *
+ * Global install: the `cms-mcp` binary is on PATH, so we can just call it.
+ * Local install: we need an absolute path to bin/mcp.js.
+ */
+function detectMcpCommand() {
+  // __dirname is the "bin/" folder where this script lives
+  // One level up is the package root
+  const packageRoot = path.resolve(__dirname, '..');
+  const mcpBin = path.join(packageRoot, 'bin', 'mcp.js');
+
+  // Check if cms-mcp is likely on PATH (global install)
+  // We do this by checking if the package is inside a global node_modules
+  const isGlobal = packageRoot.includes(path.join('node_modules', 'claude-multi-session'))
+    && (
+      packageRoot.includes(path.join('lib', 'node_modules')) // npm global on Linux/Mac
+      || packageRoot.includes(path.join('AppData', 'Roaming', 'npm')) // npm global on Windows
+      || packageRoot.includes('nvm') // nvm managed
+      || packageRoot.includes('.volta') // volta managed
+    );
+
+  if (isGlobal) {
+    // Global install — cms-mcp should be on PATH
+    return { command: 'cms-mcp' };
+  } else {
+    // Local or dev install — use absolute path to bin/mcp.js
+    return { command: 'node', args: [mcpBin] };
+  }
+}
+
+/**
+ * Read a JSON file safely. Returns empty object if file doesn't exist
+ * or has invalid JSON.
+ */
+function readJsonSafe(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write JSON to a file with nice formatting.
+ */
+function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+// ============================================================================
+// Core Setup Logic
+// ============================================================================
+
+/**
+ * Add the multi-session MCP server to a Claude Code settings.json file.
+ *
+ * @param {string} settingsPath - Absolute path to settings.json
+ * @returns {{ created: boolean, existed: boolean, overwritten: boolean }}
+ */
+async function addMcpServer(settingsPath) {
+  const result = { created: false, existed: false, overwritten: false };
+
+  // 1. Make sure the directory exists
+  const dir = path.dirname(settingsPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    log(`Created ${dir}`, 'info');
+  }
+
+  // 2. Read existing settings (or start with empty object)
+  const settings = readJsonSafe(settingsPath);
+  const fileExists = fs.existsSync(settingsPath);
+
+  if (!fileExists) {
+    log(`Creating ${settingsPath} ...`, 'info');
+    result.created = true;
+  } else {
+    log(`Reading ${settingsPath} ...`, 'info');
+  }
+
+  // 3. Ensure mcpServers key exists
+  if (!settings.mcpServers) {
+    settings.mcpServers = {};
+  }
+
+  // 4. Check if multi-session already exists
+  if (settings.mcpServers[MCP_SERVER_NAME]) {
+    result.existed = true;
+    const answer = await ask(
+      `  MCP server "${MCP_SERVER_NAME}" already exists. Overwrite? (y/n) > `
+    );
+    if (answer.toLowerCase() !== 'y') {
+      log('Skipped — keeping existing MCP config.', 'warn');
+      return result;
+    }
+    result.overwritten = true;
+  }
+
+  // 5. Build the MCP config entry
+  const mcpConfig = detectMcpCommand();
+  settings.mcpServers[MCP_SERVER_NAME] = mcpConfig;
+
+  log('Adding multi-session MCP server ...', 'info');
+
+  // 6. Write back
+  writeJson(settingsPath, settings);
+  log(`Wrote ${settingsPath}`, 'success');
+
+  return result;
+}
+
+/**
+ * Append the strategy guide to a CLAUDE.md file.
+ *
+ * @param {string} claudeMdPath - Absolute path to CLAUDE.md
+ * @returns {{ created: boolean, skipped: boolean }}
+ */
+function addStrategyGuide(claudeMdPath, skipPrompt) {
+  const result = { created: false, skipped: false };
+
+  // Check if file exists
+  let existing = '';
+  if (fs.existsSync(claudeMdPath)) {
+    existing = fs.readFileSync(claudeMdPath, 'utf-8');
+  }
+
+  // Check if strategy section already exists (avoid duplicates)
+  if (existing.includes(CLAUDE_MD_START_MARKER)) {
+    log('Strategy guide already in CLAUDE.md — skipping.', 'warn');
+    result.skipped = true;
+    return result;
+  }
+
+  // Create directory if needed
+  const dir = path.dirname(claudeMdPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Append the strategy content
+  if (existing) {
+    // Append to existing file
+    fs.appendFileSync(claudeMdPath, '\n' + STRATEGY_CONTENT, 'utf-8');
+    log(`Appended strategy guide to ${claudeMdPath}`, 'success');
+  } else {
+    // Create new file with strategy content
+    fs.writeFileSync(claudeMdPath, STRATEGY_CONTENT.trim() + '\n', 'utf-8');
+    log(`Created ${claudeMdPath} with strategy guide`, 'success');
+    result.created = true;
+  }
+
+  return result;
+}
+
+/**
+ * Remove multi-session from settings.json and CLAUDE.md.
+ *
+ * @param {string} settingsPath - Path to settings.json
+ * @param {string} claudeMdPath - Path to CLAUDE.md
+ */
+function uninstall(settingsPath, claudeMdPath) {
+  console.log('\n  Uninstalling multi-session...\n');
+
+  // 1. Remove from settings.json
+  if (fs.existsSync(settingsPath)) {
+    const settings = readJsonSafe(settingsPath);
+    if (settings.mcpServers && settings.mcpServers[MCP_SERVER_NAME]) {
+      delete settings.mcpServers[MCP_SERVER_NAME];
+
+      // Clean up empty mcpServers object
+      if (Object.keys(settings.mcpServers).length === 0) {
+        delete settings.mcpServers;
+      }
+
+      writeJson(settingsPath, settings);
+      log(`Removed "${MCP_SERVER_NAME}" from ${settingsPath}`, 'success');
+    } else {
+      log(`"${MCP_SERVER_NAME}" not found in ${settingsPath}`, 'warn');
+    }
+  } else {
+    log(`${settingsPath} not found — nothing to remove`, 'warn');
+  }
+
+  // 2. Remove strategy section from CLAUDE.md
+  if (fs.existsSync(claudeMdPath)) {
+    let content = fs.readFileSync(claudeMdPath, 'utf-8');
+    if (content.includes(CLAUDE_MD_START_MARKER)) {
+      // Remove everything between (and including) the markers
+      const startIdx = content.indexOf(CLAUDE_MD_START_MARKER);
+      const endIdx = content.indexOf(CLAUDE_MD_END_MARKER);
+      if (startIdx !== -1 && endIdx !== -1) {
+        const before = content.slice(0, startIdx).trimEnd();
+        const after = content.slice(endIdx + CLAUDE_MD_END_MARKER.length).trimStart();
+        content = before + (after ? '\n\n' + after : '') + '\n';
+        fs.writeFileSync(claudeMdPath, content, 'utf-8');
+        log(`Removed strategy guide from ${claudeMdPath}`, 'success');
+      }
+    } else {
+      log('No strategy guide found in CLAUDE.md — nothing to remove', 'warn');
+    }
+  }
+
+  console.log('\n  ✓ Uninstall complete. Restart Claude Code to apply.\n');
+}
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
+/**
+ * Run the setup wizard.
+ *
+ * @param {object} flags - CLI flags passed from cli.js or direct invocation
+ */
+async function run(flags = {}) {
+  // --postinstall mode: just print a hint and exit
+  if (flags.postinstall) {
+    console.log('');
+    console.log('  ╔═══════════════════════════════════════════════════════╗');
+    console.log('  ║  claude-multi-session installed successfully!         ║');
+    console.log('  ║                                                       ║');
+    console.log('  ║  Run setup to integrate with Claude Code:             ║');
+    console.log('  ║                                                       ║');
+    console.log('  ║    cms setup                                          ║');
+    console.log('  ║                                                       ║');
+    console.log('  ║  This registers the MCP server so Claude Code         ║');
+    console.log('  ║  can use multi-session tools natively.                 ║');
+    console.log('  ╚═══════════════════════════════════════════════════════╝');
+    console.log('');
+    return;
+  }
+
+  // Determine paths based on scope (global vs local)
+  const homeDir = os.homedir();
+  const globalSettingsPath = path.join(homeDir, '.claude', 'settings.json');
+  const globalClaudeMdPath = path.join(homeDir, '.claude', 'CLAUDE.md');
+  const localSettingsPath = path.join(process.cwd(), '.claude', 'settings.json');
+  const localClaudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+
+  // --uninstall mode
+  if (flags.uninstall) {
+    // Ask which scope to uninstall from (or use --global/--local flags)
+    let scope = flags.global ? 'global' : flags.local ? 'local' : null;
+    if (!scope) {
+      const answer = await ask(
+        '  Uninstall from? (1 = Global, 2 = Local project) > '
+      );
+      scope = answer === '2' ? 'local' : 'global';
+    }
+
+    const settingsPath = scope === 'global' ? globalSettingsPath : localSettingsPath;
+    const claudeMdPath = scope === 'global' ? globalClaudeMdPath : localClaudeMdPath;
+    uninstall(settingsPath, claudeMdPath);
+    return;
+  }
+
+  // Print header
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════════════════════╗');
+  console.log('  ║  claude-multi-session — Setup Wizard                  ║');
+  console.log('  ╚═══════════════════════════════════════════════════════╝');
+  console.log('');
+
+  // Step 1: Determine scope
+  let scope;
+  if (flags.global) {
+    scope = 'global';
+    log('Scope: Global (all projects)', 'info');
+  } else if (flags.local) {
+    scope = 'local';
+    log('Scope: Local (this project only)', 'info');
+  } else {
+    console.log('  Where should the MCP server be registered?\n');
+    console.log('    1) Global  — available in ALL projects');
+    console.log('       Writes to: ~/.claude/settings.json\n');
+    console.log('    2) Local   — only THIS project');
+    console.log('       Writes to: .claude/settings.json\n');
+    const answer = await ask('  Choose (1 or 2) > ');
+    scope = answer === '2' ? 'local' : 'global';
+    console.log('');
+  }
+
+  // Step 2: Set paths based on scope
+  const settingsPath = scope === 'global' ? globalSettingsPath : localSettingsPath;
+  const claudeMdPath = scope === 'global' ? globalClaudeMdPath : localClaudeMdPath;
+
+  // Step 3: Add MCP server to settings.json
+  const mcpResult = await addMcpServer(settingsPath);
+
+  // Step 4: Ask about strategy guide
+  console.log('');
+  let addGuide;
+  if (flags['no-guide']) {
+    addGuide = false;
+  } else if (flags.guide) {
+    addGuide = true;
+  } else {
+    const answer = await ask(
+      '  Add multi-session strategy guide to CLAUDE.md? (y/n) > '
+    );
+    addGuide = answer.toLowerCase() === 'y';
+  }
+
+  if (addGuide) {
+    addStrategyGuide(claudeMdPath);
+  }
+
+  // Step 5: Print summary
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════════════════════╗');
+  console.log('  ║  ✓ Setup complete!                                    ║');
+  console.log('  ╚═══════════════════════════════════════════════════════╝');
+  console.log('');
+  log('Restart Claude Code to load the multi-session tools.', 'info');
+  log('You\'ll see 17 new tools: spawn_session, delegate_task, etc.', 'info');
+  console.log('');
+  log('Test it: Ask Claude to "list all multi-session sessions"', 'info');
+  log('Learn more: cms help', 'info');
+  console.log('');
+}
+
+// ============================================================================
+// Direct invocation support (node bin/setup.js)
+// ============================================================================
+
+// If this script is run directly (not required by cli.js),
+// parse flags and run the wizard
+if (require.main === module) {
+  // Parse simple flags from process.argv
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      flags[key] = true;
+    }
+  }
+  run(flags).catch((err) => {
+    console.error(`\n  ✗ Setup failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "claude-multi-session",
+  "version": "1.0.0",
+  "description": "Multi-session orchestrator for Claude Code CLI — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically",
+  "main": "src/index.js",
+  "bin": {
+    "cms": "bin/cli.js",
+    "claude-multi-session": "bin/cli.js",
+    "cms-mcp": "bin/mcp.js",
+    "cms-setup": "bin/setup.js"
+  },
+  "scripts": {
+    "test": "node test-stream.js",
+    "postinstall": "node bin/setup.js --postinstall"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "session-manager",
+    "multi-session",
+    "orchestrator",
+    "ai",
+    "automation",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "STRATEGY.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}