ninja-terminals 2.3.9 → 2.4.1

package/CLAUDE.md

@@ -5,28 +5,8 @@ You are a Claude Code worker instance running inside Ninja Terminals, a multi-te
 ## When User Says "Use Ninja Terminal"
 
 If the user asks you to orchestrate via Ninja Terminals, you MUST:
-1. Run the startup check FIRST (see Startup Protocol below)
-2. Read `ORCHESTRATOR-PROMPT.md`
-3. Follow the rules there — visible PTY workflow is primary; use `ninja-dispatch`/API for reliable visible dispatch, browser paste as manual fallback, MCP/API/browser for monitoring
-
-## Startup Protocol
-
-Before any orchestration, run this command to ensure server is running and UIs are open:
-
-```bash
-node .claude/hooks/ninja-startup.js
-```
-
-This will:
-- Start the MCP server on port 3300 if not running
-- Health check the server
-- Open Main UI (`http://localhost:3300/`) in browser
-- Open Log Viewer (`http://localhost:3300/log-viewer.html`) in browser
-- Output JSON confirmation with URLs
-
-**Do not proceed with orchestration until startup outputs `"status": "ready"`.**
-
-If startup fails, report: `STATUS: ERROR — Ninja server failed to start. Check if port 3300 is in use.`
+1. Read `ORCHESTRATOR-PROMPT.md` FIRST
+2. Follow the rules there — visible PTY workflow is primary; use `ninja-dispatch`/API for reliable visible dispatch, browser paste as manual fallback, MCP/API/browser for monitoring
 
 ## Identity
 - You are ONE of 4 Claude Code terminals running simultaneously

package/README.md

@@ -8,8 +8,10 @@ Free & open. Donations welcome.
 
 ## Installation
 
+Run the one-time setup command:
+
 ```bash
-npm install -g ninja-terminals
+npx --yes ninja-terminals --setup
 ```
 
 ## Quick Start

package/cli.js

@@ -30,7 +30,7 @@ USAGE
   npx ninja-terminals [options]
 
 OPTIONS
-  --setup                  Configure MCP server + orchestrator prompt (run once)
+  --setup                  Run the one-time setup flow for Claude Code
   --port        <number>   Port to listen on          (default: 3300)
   --terminals   <number>   Number of terminals to spawn (default: 4)
   --cwd         <path>     Working directory for terminals (default: current dir)
@@ -38,6 +38,7 @@ OPTIONS
   --help,    -h            Show this help message
 
 EXAMPLES
+  npx --yes ninja-terminals --setup
   npx ninja-terminals
   npx ninja-terminals --port 3301 --terminals 2
   npx ninja-terminals --cwd /path/to/my-project
@@ -54,43 +55,24 @@ if (hasFlag('--version') || hasFlag('-v')) {
 
 // ── Setup command ───────────────────────────────────────────
 if (hasFlag('--setup')) {
-  runSetup().then(() => process.exit(0)).catch(e => { console.error(e); process.exit(1); });
-}
-
-async function runSetup() {
   const fs = require('fs');
   const path = require('path');
   const os = require('os');
 
   console.log('\n🥷 NINJA TERMINALS SETUP\n');
 
-  // 1. Find or create .claude/settings.json (Claude Code format)
-  const projectClaudeDir = path.join(process.cwd(), '.claude');
-  const globalClaudeDir = path.join(os.homedir(), '.claude');
-  const projectSettings = path.join(projectClaudeDir, 'settings.json');
-  const globalSettings = path.join(globalClaudeDir, 'settings.json');
-
-  // Prefer project-level if .claude dir exists, else use global
-  let settingsPath, claudeDir;
-  if (fs.existsSync(projectClaudeDir)) {
-    settingsPath = projectSettings;
-    claudeDir = projectClaudeDir;
-  } else {
-    settingsPath = globalSettings;
-    claudeDir = globalClaudeDir;
-    // Create global .claude dir if needed
-    if (!fs.existsSync(claudeDir)) {
-      fs.mkdirSync(claudeDir, { recursive: true });
-    }
-  }
+  // 1. Find or create .mcp.json
+  const projectMcp = path.join(process.cwd(), '.mcp.json');
+  const globalMcp = path.join(os.homedir(), '.mcp.json');
+  const mcpPath = fs.existsSync(projectMcp) ? projectMcp : globalMcp;
 
   let mcpConfig = { mcpServers: {} };
-  if (fs.existsSync(settingsPath)) {
+  if (fs.existsSync(mcpPath)) {
     try {
-      mcpConfig = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+      mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
       if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
     } catch (e) {
-      console.log(`⚠️  Could not parse ${settingsPath}, creating new config`);
+      console.log(`⚠️  Could not parse ${mcpPath}, creating new config`);
     }
   }
 
@@ -100,29 +82,19 @@ async function runSetup() {
     args: ['ninja-terminals-mcp'],
     env: {
       NINJA_TERMINAL_COUNT: '4',
-      NINJA_LOG_LEVEL: 'info',
-      HTTP_PORT: '3300'
+      NINJA_LOG_LEVEL: 'info'
     }
   };
 
-  // Get npm root for copying orchestrator prompt (works in dev and installed mode)
-  let npmRoot;
-  try {
-    npmRoot = path.dirname(require.resolve('ninja-terminals/package.json'));
-  } catch {
-    npmRoot = __dirname; // Dev mode fallback
-  }
+  // Get npm root for copying orchestrator prompt
+  const npmRoot = path.dirname(require.resolve('ninja-terminals/package.json'));
 
-  fs.writeFileSync(settingsPath, JSON.stringify(mcpConfig, null, 2) + '\n');
-  console.log(`✅ Added ninja-terminals to ${settingsPath}`);
+  fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  console.log(`✅ Added ninja-terminals to ${mcpPath}`);
 
   // 3. Copy orchestrator prompt to CLAUDE.md
   const claudeMd = path.join(process.cwd(), 'CLAUDE.md');
-  // Use the real orchestrator prompt, not the pointer file
-  let orchestratorPrompt = path.join(npmRoot, 'ORCHESTRATOR-PROMPT.md');
-  if (!fs.existsSync(orchestratorPrompt)) {
-    orchestratorPrompt = path.join(npmRoot, 'prompts', 'orchestrator.md');
-  }
+  const orchestratorPrompt = path.join(npmRoot, 'ORCHESTRATOR-PROMPT.md');
 
   if (fs.existsSync(orchestratorPrompt)) {
     const prompt = fs.readFileSync(orchestratorPrompt, 'utf-8');
@@ -168,7 +140,7 @@ async function runSetup() {
   }
 
   // Save updated config with all MCPs
-  fs.writeFileSync(settingsPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
 
   // 5. Check for Claude in Chrome (optional but recommended)
   const chromeExt = mcpConfig.mcpServers['claude-in-chrome'];
@@ -182,17 +154,28 @@ async function runSetup() {
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✨ Setup complete!
 
-Next: Restart Claude Code, then tell Claude:
-      "use ninja terminals"
+MCPs configured:
+  • ninja-terminals - orchestrates parallel Claude Code instances
+  • playwright - browser automation (screenshots, clicks, reading)
+  • fetch - API calls to /api/terminals
+
+Next steps:
+1. Restart Claude Code to load MCP servers
+2. Run: npx ninja-terminals
+3. Or use MCP tools directly in Claude Code
+
+MCP tools available after restart:
+  mcp__ninja-terminals__spawn_terminal
+  mcp__ninja-terminals__send_input
+  mcp__ninja-terminals__list_terminals
+  ... and 9 more
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `);
+  process.exit(0);
 }
 
-// If setup mode was requested, we're done (setup function calls process.exit)
-if (!hasFlag('--setup')) {
-
 const port      = parseInt(getArg('--port',      '3300'),  10);
-const terminals = parseInt(getArg('--terminals', '4'),     10);  // Full access
+const terminals = parseInt(getArg('--terminals', '2'),     10);  // Free tier default
 const cwd       = getArg('--cwd', process.cwd());
 const token     = getArg('--token', null);
 const offline   = hasFlag('--offline');
@@ -228,6 +211,7 @@ console.log(`
 // must be set here before the require call.
 
 process.env.PORT               = String(port);
+process.env.HTTP_PORT          = String(port);
 process.env.DEFAULT_TERMINALS  = String(terminals);
 process.env.DEFAULT_CWD        = cwd;
 
@@ -270,5 +254,3 @@ setTimeout(() => {
 // ── Start the server ─────────────────────────────────────────
 
 require('./server.js');
-
-} // end if (!hasFlag('--setup'))

package/lib/ninja-request.js

@@ -0,0 +1,247 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const NINJA_DIR = path.join(os.homedir(), '.ninja');
+const REQUEST_FILE = path.join(NINJA_DIR, 'ninja-request.json');
+const LEDGER_FILE = path.join(NINJA_DIR, 'dispatch-ledger.ndjson');
+const VERIFICATION_LEDGER_FILE = path.join(NINJA_DIR, 'verification-ledger.ndjson');
+const VISUAL_LEDGER_FILE = path.join(NINJA_DIR, 'visual-ledger.ndjson');
+
+const NINJA_PATTERNS = [
+  /(?:^|\b)(?:open|start|launch|spawn|bring up)\s+(?:the\s+)?ninja\s*terminals?\b/i,
+  /(?:^|\b)ninja\s*terminals?\s+(?:please|now)\b/i,
+];
+
+const MODE_PATTERNS = [
+  { mode: 'shell', pattern: /(?:terminals?|shell)\s+only/i, defaultCount: 4 },
+  { mode: 'claude', pattern: /claude\s+only/i, defaultCount: 4 },
+  { mode: 'codex', pattern: /codex\s+only/i, defaultCount: 4 },
+  { mode: 'opencode', pattern: /(?:open\s*code|opencode)\s+only/i, defaultCount: 4 },
+  { mode: 'mixed', pattern: /\bmixed\b/i, defaultCount: 4 },
+  { mode: 'duo', pattern: /\bduo\b/i, defaultCount: 2 },
+];
+
+const NUMBER_WORDS = new Map([
+  ['one', 1],
+  ['two', 2],
+  ['three', 3],
+  ['four', 4],
+  ['five', 5],
+  ['six', 6],
+  ['seven', 7],
+  ['eight', 8],
+]);
+
+function isNinjaRequest(prompt) {
+  if (!prompt) return false;
+  return NINJA_PATTERNS.some(pattern => pattern.test(prompt));
+}
+
+function inferNinjaLaunchConfig(prompt) {
+  const text = String(prompt || '');
+  const modeEntry = MODE_PATTERNS.find(entry => entry.pattern.test(text));
+  const mode = modeEntry ? modeEntry.mode : 'claude';
+  const defaultCount = modeEntry ? modeEntry.defaultCount : 4;
+
+  const numericCount = text.match(/\b(\d+)\s*(?:terminals?|instances?)\b/i);
+  const wordCount = text.match(/\b(one|two|three|four|five|six|seven|eight)\s*(?:terminals?|instances?)\b/i);
+  const requestedCount = numericCount
+    ? parseInt(numericCount[1], 10)
+    : wordCount
+      ? NUMBER_WORDS.get(wordCount[1].toLowerCase())
+      : null;
+
+  const terminalCount = Number.isInteger(requestedCount) && requestedCount > 0
+    ? requestedCount
+    : defaultCount;
+
+  return { mode, terminalCount };
+}
+
+function writeNinjaRequest(cwd, promptPreview) {
+  try {
+    fs.mkdirSync(NINJA_DIR, { recursive: true, mode: 0o700 });
+    const launchConfig = inferNinjaLaunchConfig(promptPreview);
+    const data = {
+      timestamp: new Date().toISOString(),
+      cwd: cwd || process.cwd(),
+      promptPreview: (promptPreview || '').slice(0, 200),
+      launchConfig,
+    };
+    fs.writeFileSync(REQUEST_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    return data;
+  } catch (err) {
+    console.error(`Warning: Could not write ninja request: ${err.message}`);
+    return null;
+  }
+}
+
+function readNinjaRequest() {
+  try {
+    const raw = fs.readFileSync(REQUEST_FILE, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function clearNinjaRequest() {
+  try {
+    fs.unlinkSync(REQUEST_FILE);
+  } catch {
+    // already absent
+  }
+}
+
+function readLedgerAfter(afterTimestamp) {
+  try {
+    const raw = fs.readFileSync(LEDGER_FILE, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp && entry.timestamp > afterTimestamp) {
+          entries.push(entry);
+        }
+      } catch {
+        // skip malformed
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+function hasSuccessfulDispatchAfter(afterTimestamp) {
+  const entries = readLedgerAfter(afterTimestamp);
+  return entries.some(e => e.success === true);
+}
+
+function readVerificationLedgerAfter(afterTimestamp) {
+  try {
+    const raw = fs.readFileSync(VERIFICATION_LEDGER_FILE, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp && entry.timestamp > afterTimestamp) {
+          entries.push(entry);
+        }
+      } catch {
+        // skip malformed
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+function hasVerificationAfter(afterTimestamp) {
+  const entries = readVerificationLedgerAfter(afterTimestamp);
+  return entries.length > 0;
+}
+
+function getLastSuccessfulDispatchTimestamp(afterTimestamp) {
+  const entries = readLedgerAfter(afterTimestamp);
+  const successful = entries.filter(e => e.success === true);
+  if (successful.length === 0) return null;
+  return successful[successful.length - 1].timestamp;
+}
+
+function getLastVerificationTimestamp(afterTimestamp) {
+  const entries = readVerificationLedgerAfter(afterTimestamp);
+  if (entries.length === 0) return null;
+  return entries[entries.length - 1].timestamp;
+}
+
+function readVisualLedgerAfter(afterTimestamp) {
+  try {
+    const raw = fs.readFileSync(VISUAL_LEDGER_FILE, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp && entry.timestamp > afterTimestamp) {
+          entries.push(entry);
+        }
+      } catch {
+        // skip malformed
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+function readVisualLedgerBetween(startTs, endTs) {
+  try {
+    const raw = fs.readFileSync(VISUAL_LEDGER_FILE, 'utf8');
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp && entry.timestamp > startTs && entry.timestamp < endTs) {
+          entries.push(entry);
+        }
+      } catch {
+        // skip malformed
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+function hasVisualBetween(startTs, endTs, options = {}) {
+  const entries = readVisualLedgerBetween(startTs, endTs);
+  return entries.some(e => {
+    if (options.stage && e.stage !== options.stage) return false;
+    if (options.stages && !options.stages.includes(e.stage)) return false;
+    if (options.source && e.source !== options.source) return false;
+    return true;
+  });
+}
+
+function hasVisualAfter(afterTimestamp, options = {}) {
+  const entries = readVisualLedgerAfter(afterTimestamp);
+  return entries.some(e => {
+    if (options.stage && e.stage !== options.stage) return false;
+    if (options.stages && !options.stages.includes(e.stage)) return false;
+    if (options.source && e.source !== options.source) return false;
+    return true;
+  });
+}
+
+module.exports = {
+  NINJA_DIR,
+  REQUEST_FILE,
+  LEDGER_FILE,
+  VERIFICATION_LEDGER_FILE,
+  VISUAL_LEDGER_FILE,
+  isNinjaRequest,
+  inferNinjaLaunchConfig,
+  writeNinjaRequest,
+  readNinjaRequest,
+  clearNinjaRequest,
+  readLedgerAfter,
+  hasSuccessfulDispatchAfter,
+  readVerificationLedgerAfter,
+  hasVerificationAfter,
+  getLastSuccessfulDispatchTimestamp,
+  getLastVerificationTimestamp,
+  readVisualLedgerAfter,
+  readVisualLedgerBetween,
+  hasVisualBetween,
+  hasVisualAfter,
+};

package/lib/settings-gen.js

@@ -192,22 +192,9 @@ function writeWorkerSettings(terminalId, projectDir, scope, options = {}) {
   const mergedAllow = [...new Set([...(existing.permissions?.allow || []), ...settings.permissions.allow])];
   const mergedDeny = [...new Set([...(existing.permissions?.deny || []), ...settings.permissions.deny])];
 
-  // Build hooks for self-improvement loop (matches Claude Code's nested format)
-  const ninjaDir = path.resolve(__dirname, '..');
-  const hooks = {
-    PostToolUse: [{
-      matcher: '',
-      hooks: [{
-        type: 'command',
-        command: path.join(ninjaDir, '.claude/hooks/track-tool.sh'),
-      }],
-    }],
-  };
-
   const merged = {
     ...existing,
     permissions: { allow: mergedAllow, deny: mergedDeny },
-    hooks,
     sandbox: settings.sandbox,
   };
 

package/mcp-server.js

@@ -40,9 +40,9 @@ const {
 } = require('./lib/runtime-session');
 
 // ── Config ──────────────────────────────────────────────────
-const PREFERRED_HTTP_PORT = parseInt(process.env.HTTP_PORT || '3300', 10);
+const PREFERRED_HTTP_PORT = parseInt(process.env.HTTP_PORT || process.env.PORT || '3300', 10);
 let HTTP_PORT = PREFERRED_HTTP_PORT;
-const CLAUDE_CMD = process.env.CLAUDE_CMD || 'claude --dangerously-skip-permissions';
+const CLAUDE_CMD = process.env.CLAUDE_CMD || process.env.CLAUDE_CHROME_CMD || 'claude --chrome --model claude-opus-4-5-20251101';
 const SHELL = process.env.SHELL || '/bin/zsh';
 const PROJECT_DIR = __dirname;
 const INJECT_GUIDANCE = process.env.INJECT_GUIDANCE !== 'false';
@@ -151,6 +151,9 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
     env: {
       ...cleanEnv,
       TERM: 'xterm-256color',
+      COLORTERM: 'truecolor',
+      FORCE_COLOR: '1',
+      CLICOLOR_FORCE: '1',
       HOME: os.homedir(),
       PATH: `${os.homedir()}/.local/bin:/opt/homebrew/bin:${process.env.PATH || ''}`,
       SHELL_SESSIONS_DISABLE: '1',
@@ -940,37 +943,8 @@ async function main() {
     console.error(`Ninja Terminals server already running on port ${HTTP_PORT}`);
     console.error('MCP server starting in proxy mode (will use existing server)');
   } else {
-    HTTP_PORT = await findAvailablePort(PREFERRED_HTTP_PORT);
-    if (HTTP_PORT !== PREFERRED_HTTP_PORT) {
-      console.error(`Ninja Terminals preferred HTTP port ${PREFERRED_HTTP_PORT} unavailable; using ${HTTP_PORT}`);
-    }
-
-    // Standalone mode: start our own HTTP server
-    httpServer.listen(HTTP_PORT, () => {
-      const url = `http://localhost:${HTTP_PORT}`;
-      writeRuntimeSession({
-        port: HTTP_PORT,
-        url,
-        cwd: PROJECT_DIR,
-        terminals: parseInt(process.env.NINJA_TERMINAL_COUNT || '2', 10),
-        command: 'ninja-terminals-mcp',
-      });
-      ownsRuntimeSession = true;
-      console.error(`Ninja Terminals HTTP server running on ${url}`);
-
-      // Auto-spawn terminals based on tier (NINJA_TERMINAL_COUNT env var)
-      // Free = 2, Paid = 4
-      const terminalCount = parseInt(process.env.NINJA_TERMINAL_COUNT || '2', 10);
-      const labels = ['T1', 'T2', 'T3', 'T4', 'T5', 'T6', 'T7', 'T8'];
-
-      console.error(`Auto-spawning ${terminalCount} terminals...`);
-      for (let i = 0; i < terminalCount; i++) {
-        const label = labels[i] || `T${i + 1}`;
-        spawnTerminal(label, [], process.cwd(), 'pro');
-        console.error(`  Spawned ${label}`);
-      }
-      console.error(`All ${terminalCount} terminals ready`);
-    });
+    console.error('No live Ninja runtime found. MCP is staying request-only until ninja-ensure starts the runtime.');
+    console.error('No HTTP server, no session file, no terminal spawn on Claude startup.');
   }
 
   // Start MCP server on stdio