knoxis-collab 1.0.0

package/knoxis-collab.js

@@ -0,0 +1,796 @@
+#!/usr/bin/env node
+
+/**
+ * Knoxis Collab — Three-way collaborative programming
+ *
+ * A persistent terminal session where:
+ *   User  <-->  Knoxis (Groq)  <-->  Claude Code
+ *
+ * Unlike the fire-and-forget pair programming scripts, this keeps the human
+ * in the loop. You talk to Knoxis, he dispatches to Claude when needed,
+ * reviews the output, and reports back. You approve, reject, or redirect.
+ * The session runs indefinitely with no timeouts or rigid phases.
+ *
+ * Usage:
+ *   node knoxis-collab.js                          # interactive, current dir
+ *   node knoxis-collab.js --workspace /path/to/project
+ *   node knoxis-collab.js --task "build a REST API"
+ *   KNOXIS_TASK_FILE=/tmp/task.txt node knoxis-collab.js
+ *
+ * Env:
+ *   GROQ_API_KEY             - Required (or set in ~/.knoxis/config.json)
+ *   KNOXIS_WORKSPACE         - Workspace directory (default: cwd)
+ *   KNOXIS_TASK_FILE         - Path to file containing initial task
+ *   KNOXIS_GROQ_MODEL        - Groq model (default: llama-3.3-70b-versatile)
+ *
+ * Commands:
+ *   /status    - Session info
+ *   /verbose   - Toggle Claude output streaming
+ *   /diff      - Show git changes in workspace
+ *   /log       - Show session log path
+ *   /exit      - End session
+ *
+ * ZERO EXTERNAL DEPENDENCIES — Node.js built-ins only.
+ */
+
+const { spawn, spawnSync } = require('child_process');
+const crypto = require('crypto');
+const https = require('https');
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ═══════════════════════════════════════════════════════════════
+//  CONFIG
+// ═══════════════════════════════════════════════════════════════
+
+const CONFIG_PATH = path.join(os.homedir(), '.knoxis', 'config.json');
+const SESSION_ID = crypto.randomUUID();
+const GROQ_MODEL = process.env.KNOXIS_GROQ_MODEL || 'llama-3.3-70b-versatile';
+
+// Parse CLI args
+function parseArgs() {
+  const args = { workspace: null, task: null, verbose: false };
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    if ((argv[i] === '--workspace' || argv[i] === '-w') && argv[i + 1]) {
+      args.workspace = argv[++i];
+    } else if ((argv[i] === '--task' || argv[i] === '-t') && argv[i + 1]) {
+      args.task = argv[++i];
+    } else if (argv[i] === '--verbose' || argv[i] === '-v') {
+      args.verbose = true;
+    }
+  }
+  return args;
+}
+
+const cliArgs = parseArgs();
+const WORKSPACE = cliArgs.workspace || process.env.KNOXIS_WORKSPACE || process.cwd();
+
+// Load config
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    }
+  } catch (e) {}
+  return {};
+}
+
+const config = loadConfig();
+const GROQ_API_KEY = process.env.GROQ_API_KEY || config.groqApiKey || '';
+
+// ═══════════════════════════════════════════════════════════════
+//  STATE
+// ═══════════════════════════════════════════════════════════════
+
+let claudeSessionId = null;
+let claudeDispatches = 0;
+let verbose = cliArgs.verbose;
+let isClaudeRunning = false;
+let activeClaudeProc = null;
+const conversationHistory = [];    // Groq message history
+const dispatchSummaries = [];      // Short summaries of what Claude did each dispatch
+
+// ═══════════════════════════════════════════════════════════════
+//  SESSION LOG
+// ═══════════════════════════════════════════════════════════════
+
+const sessionDir = path.join(WORKSPACE, '.knoxis', 'sessions');
+try { fs.mkdirSync(sessionDir, { recursive: true }); } catch (e) {}
+
+const logFile = path.join(
+  sessionDir,
+  `${new Date().toISOString().replace(/[:.]/g, '-')}-collab-${SESSION_ID.slice(0, 8)}.log`
+);
+
+function log(entry) {
+  const line = `[${new Date().toISOString()}] ${entry}\n`;
+  try { fs.appendFileSync(logFile, line); } catch (e) {}
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  TERMINAL UI
+// ═══════════════════════════════════════════════════════════════
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  white: '\x1b[37m',
+};
+
+function printHeader() {
+  console.log('');
+  console.log(`${C.cyan}╔══════════════════════════════════════════════════════════════╗${C.reset}`);
+  console.log(`${C.cyan}║${C.bold}${C.white}        KNOXIS COLLABORATIVE SESSION                         ${C.reset}${C.cyan}║${C.reset}`);
+  console.log(`${C.cyan}╚══════════════════════════════════════════════════════════════╝${C.reset}`);
+  console.log('');
+  console.log(`  ${C.dim}Session:${C.reset}  ${SESSION_ID.slice(0, 8)}`);
+  console.log(`  ${C.dim}Dir:${C.reset}      ${WORKSPACE}`);
+  console.log(`  ${C.dim}Knoxis:${C.reset}   Groq (${GROQ_MODEL})`);
+  console.log(`  ${C.dim}Claude:${C.reset}   Claude Code (session-persistent)`);
+  console.log(`  ${C.dim}Log:${C.reset}      ${path.basename(logFile)}`);
+  console.log('');
+  console.log(`  ${C.dim}Talk to Knoxis naturally. He dispatches to Claude when needed.${C.reset}`);
+  console.log(`  ${C.dim}Commands: /status  /verbose  /diff  /log  /exit${C.reset}`);
+  console.log('');
+}
+
+function printKnoxis(message) {
+  // Word-wrap at ~76 chars with Knoxis prefix
+  const lines = message.split('\n');
+  console.log('');
+  for (const line of lines) {
+    console.log(`  ${C.magenta}${C.bold}Knoxis:${C.reset} ${line}`);
+  }
+  console.log('');
+}
+
+function printClaudeLine(text) {
+  if (verbose) {
+    const lines = text.split('\n');
+    for (const line of lines) {
+      if (line.trim()) {
+        console.log(`  ${C.dim}  │ ${line}${C.reset}`);
+      }
+    }
+  }
+}
+
+function printClaudeStatus(status) {
+  if (!verbose) {
+    process.stdout.write(`\r  ${C.blue}  ⟳ Claude: ${status}${C.reset}${''.padEnd(20)}`);
+  }
+}
+
+function clearClaudeStatus() {
+  if (!verbose) {
+    process.stdout.write('\r' + ' '.repeat(80) + '\r');
+  }
+}
+
+function printDivider(label, color) {
+  const c = color || C.blue;
+  console.log(`\n  ${c}━━━ ${label} ━━━${C.reset}\n`);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  LOAD INITIAL TASK
+// ═══════════════════════════════════════════════════════════════
+
+function loadInitialTask() {
+  // CLI arg
+  if (cliArgs.task) return cliArgs.task;
+
+  // Task file
+  const taskFile = process.env.KNOXIS_TASK_FILE;
+  if (taskFile && fs.existsSync(taskFile)) {
+    return fs.readFileSync(taskFile, 'utf8').trim();
+  }
+
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  DETECT PROJECT CONTEXT (lightweight)
+// ═══════════════════════════════════════════════════════════════
+
+function detectProject() {
+  const info = [];
+
+  try {
+    const pkgPath = path.join(WORKSPACE, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      info.push(`Node.js project: ${pkg.name || 'unknown'}`);
+      if (pkg.description) info.push(pkg.description);
+    }
+  } catch (e) {}
+
+  try {
+    const pomPath = path.join(WORKSPACE, 'pom.xml');
+    if (fs.existsSync(pomPath)) info.push('Java/Maven project (pom.xml)');
+  } catch (e) {}
+
+  try {
+    const gradlePath = path.join(WORKSPACE, 'build.gradle');
+    if (fs.existsSync(gradlePath)) info.push('Java/Gradle project');
+  } catch (e) {}
+
+  try {
+    const nextPath = path.join(WORKSPACE, 'next.config.js');
+    const nextPath2 = path.join(WORKSPACE, 'next.config.mjs');
+    if (fs.existsSync(nextPath) || fs.existsSync(nextPath2)) info.push('Next.js app');
+  } catch (e) {}
+
+  // Git branch
+  try {
+    const result = spawnSync('git', ['branch', '--show-current'], { cwd: WORKSPACE, stdio: 'pipe' });
+    if (result.status === 0) {
+      const branch = result.stdout.toString().trim();
+      if (branch) info.push(`Git branch: ${branch}`);
+    }
+  } catch (e) {}
+
+  return info.join(' · ');
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  GROQ API (Knoxis)
+// ═══════════════════════════════════════════════════════════════
+
+function buildSystemPrompt(projectContext) {
+  return `You are Knoxis, a senior developer and technical lead in a live collaborative programming session. Three participants: the user (developer), you (Knoxis), and Claude Code (AI coding assistant that can read/write files, run commands, etc).
+
+Your role:
+- Talk to the user conversationally about what they want to build, fix, or change.
+- When a task is clear, dispatch it to Claude Code with a well-structured prompt.
+- Review Claude's output when it comes back. Give the user an honest, concise summary.
+- Ask clarifying questions when the user's intent is vague. Don't guess — ask.
+- Suggest breaking large tasks into steps. Execute one at a time.
+- Push back if something seems off. You're a peer, not a yes-man.
+- Keep things moving. Bias toward action over discussion.
+
+WORKSPACE: ${WORKSPACE}
+PROJECT: ${projectContext || 'unknown'}
+${dispatchSummaries.length > 0 ? '\nWORK DONE SO FAR:\n' + dispatchSummaries.map((s, i) => `  ${i + 1}. ${s}`).join('\n') : ''}
+
+RESPONSE FORMAT: You MUST respond with valid JSON only. No markdown wrapping, no code fences. Structure:
+{
+  "action": "respond" | "dispatch",
+  "message": "what to say to the user (concise, markdown OK for formatting)",
+  "claudePrompt": "structured prompt for Claude (ONLY when action is dispatch)"
+}
+
+ACTIONS:
+- "respond": Talk directly to the user. Use for greetings, clarifications, questions, status, simple answers. No Claude involved.
+- "dispatch": Send work to Claude Code. "message" tells the user what you're doing. "claudePrompt" is the structured prompt for Claude. Be specific: file paths, what to change, patterns to follow, what to report back.
+
+DISPATCH GUIDELINES:
+- Write claudePrompt like a senior dev writing a well-scoped ticket. Include: goal, files to touch, constraints, what to report when done.
+- Always include "Workspace: ${WORKSPACE}" in the prompt so Claude knows where to work.
+- If the task builds on previous work, reference what was already done.
+- Tell Claude: "When done, summarize what you changed (files, functions, lines)."
+- If the user's request is vague, respond with a clarifying question instead of dispatching.
+- For large tasks, suggest a plan and get approval before dispatching.
+
+REVIEW GUIDELINES (when you receive Claude's output):
+- Summarize what was actually changed — files, functions, key decisions.
+- Flag anything that looks wrong, incomplete, or that deviated from the ask.
+- Suggest logical next steps.
+- Be brief. 3-5 sentences for typical changes, more for complex work.
+
+PERSONALITY: Direct, technical, efficient. You're a developer talking to a developer. No fluff.`;
+}
+
+function callGroq(messages, projectContext) {
+  return new Promise((resolve, reject) => {
+    if (!GROQ_API_KEY) {
+      reject(new Error('GROQ_API_KEY not set'));
+      return;
+    }
+
+    const payload = JSON.stringify({
+      model: GROQ_MODEL,
+      messages: [
+        { role: 'system', content: buildSystemPrompt(projectContext) },
+        ...messages
+      ],
+      temperature: 0.3,
+      max_tokens: 2048,
+      response_format: { type: 'json_object' }
+    });
+
+    const options = {
+      hostname: 'api.groq.com',
+      path: '/openai/v1/chat/completions',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${GROQ_API_KEY}`,
+        'Content-Length': Buffer.byteLength(payload)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (json.error) {
+            reject(new Error(`Groq API: ${json.error.message || JSON.stringify(json.error)}`));
+            return;
+          }
+          if (!json.choices || !json.choices[0]) {
+            reject(new Error('Groq returned empty response'));
+            return;
+          }
+
+          const content = json.choices[0].message.content;
+          // Try parsing JSON, handle potential code fences
+          let cleaned = content.trim();
+          if (cleaned.startsWith('```')) {
+            cleaned = cleaned.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
+          }
+
+          const parsed = JSON.parse(cleaned);
+          resolve(parsed);
+        } catch (e) {
+          // If JSON parse fails, wrap raw text as a respond action
+          try {
+            const json = JSON.parse(data);
+            const raw = json.choices?.[0]?.message?.content || '';
+            resolve({ action: 'respond', message: raw || 'Sorry, I had trouble forming a response. Could you rephrase?' });
+          } catch (e2) {
+            reject(new Error(`Failed to parse Groq response: ${e.message}`));
+          }
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.setTimeout(30000, () => {
+      req.destroy();
+      reject(new Error('Groq request timed out (30s)'));
+    });
+
+    req.write(payload);
+    req.end();
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CLAUDE CODE DISPATCH
+// ═══════════════════════════════════════════════════════════════
+
+function checkClaudeInstalled() {
+  const result = spawnSync('which', ['claude'], { stdio: 'pipe' });
+  return result.status === 0;
+}
+
+function dispatchToClaude(prompt) {
+  return new Promise((resolve, reject) => {
+    claudeDispatches++;
+    isClaudeRunning = true;
+
+    const args = ['-p', '--dangerously-skip-permissions'];
+    if (claudeSessionId) {
+      args.push('--resume', claudeSessionId);
+    } else {
+      claudeSessionId = SESSION_ID;
+      args.push('--session-id', claudeSessionId);
+    }
+
+    log(`DISPATCH #${claudeDispatches}:\n${prompt}`);
+
+    const proc = spawn('claude', args, {
+      cwd: WORKSPACE,
+      env: { ...process.env },
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    activeClaudeProc = proc;
+    let stdout = '';
+    let stderr = '';
+    let outputLines = 0;
+    const startTime = Date.now();
+
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      outputLines += text.split('\n').filter(l => l.trim()).length;
+      printClaudeLine(text);
+      if (!verbose) {
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        printClaudeStatus(`working... ${outputLines} lines, ${elapsed}s`);
+      }
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      if (!text.includes('Debug:') && !text.includes('trace')) {
+        stderr += text;
+      }
+    });
+
+    proc.on('close', (code) => {
+      isClaudeRunning = false;
+      activeClaudeProc = null;
+      clearClaudeStatus();
+
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      log(`CLAUDE DONE (exit ${code}, ${elapsed}s, ${outputLines} lines):\n${stdout.slice(0, 2000)}`);
+
+      if (code === 0 || stdout.length > 0) {
+        resolve({ output: stdout.trim(), exitCode: code || 0, elapsed, lines: outputLines });
+      } else {
+        reject(new Error(`Claude exited with code ${code}${stderr ? ': ' + stderr.slice(0, 500) : ''}`));
+      }
+    });
+
+    proc.on('error', (err) => {
+      isClaudeRunning = false;
+      activeClaudeProc = null;
+      clearClaudeStatus();
+      reject(err);
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CONVERSATION MANAGEMENT
+// ═══════════════════════════════════════════════════════════════
+
+// Keep conversation history bounded. Always keep first 2 messages (greeting context)
+// and last 18 messages. Truncate long assistant messages.
+function trimHistory() {
+  const MAX_MESSAGES = 24;
+  if (conversationHistory.length <= MAX_MESSAGES) return;
+
+  const keep = 2; // greeting exchange
+  const tail = MAX_MESSAGES - keep;
+  const trimmed = [
+    ...conversationHistory.slice(0, keep),
+    { role: 'user', content: '[Earlier conversation trimmed for context. See dispatch summaries in system prompt for work done.]' },
+    ...conversationHistory.slice(-tail)
+  ];
+  conversationHistory.length = 0;
+  conversationHistory.push(...trimmed);
+}
+
+// Truncate Claude output for Groq review (Groq doesn't need the full thing)
+function truncateForReview(output, maxChars) {
+  const limit = maxChars || 6000;
+  if (output.length <= limit) return output;
+
+  const head = output.slice(0, limit * 0.7);
+  const tail = output.slice(-limit * 0.3);
+  return head + '\n\n[... output truncated for review ...]\n\n' + tail;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  COMMAND HANDLERS
+// ═══════════════════════════════════════════════════════════════
+
+function handleCommand(input) {
+  const cmd = input.toLowerCase().trim();
+
+  if (cmd === '/exit' || cmd === '/quit' || cmd === '/q') {
+    log('SESSION END (user exit)');
+    console.log(`\n  ${C.dim}Session ended. ${claudeDispatches} dispatches to Claude.${C.reset}`);
+    console.log(`  ${C.dim}Log: ${logFile}${C.reset}\n`);
+    process.exit(0);
+  }
+
+  if (cmd === '/status') {
+    console.log(`\n  ${C.dim}Session:${C.reset}     ${SESSION_ID.slice(0, 8)}`);
+    console.log(`  ${C.dim}Workspace:${C.reset}   ${WORKSPACE}`);
+    console.log(`  ${C.dim}Dispatches:${C.reset}  ${claudeDispatches}`);
+    console.log(`  ${C.dim}Claude:${C.reset}      ${claudeSessionId ? 'active (session ' + claudeSessionId.slice(0, 8) + ')' : 'not yet started'}`);
+    console.log(`  ${C.dim}Messages:${C.reset}    ${conversationHistory.length}`);
+    console.log(`  ${C.dim}Verbose:${C.reset}     ${verbose ? 'on' : 'off'}`);
+    console.log(`  ${C.dim}Log:${C.reset}         ${logFile}`);
+    if (dispatchSummaries.length > 0) {
+      console.log(`\n  ${C.dim}Work done:${C.reset}`);
+      dispatchSummaries.forEach((s, i) => console.log(`    ${i + 1}. ${s}`));
+    }
+    console.log('');
+    return true;
+  }
+
+  if (cmd === '/verbose') {
+    verbose = !verbose;
+    console.log(`\n  ${C.dim}Claude output streaming: ${verbose ? 'ON' : 'OFF'}${C.reset}\n`);
+    return true;
+  }
+
+  if (cmd === '/diff') {
+    try {
+      const result = spawnSync('git', ['diff', '--stat'], { cwd: WORKSPACE, stdio: 'pipe' });
+      const output = result.stdout.toString().trim();
+      if (output) {
+        console.log(`\n  ${C.dim}Git changes in workspace:${C.reset}`);
+        output.split('\n').forEach(line => console.log(`  ${C.dim}  ${line}${C.reset}`));
+      } else {
+        console.log(`\n  ${C.dim}No uncommitted changes.${C.reset}`);
+      }
+    } catch (e) {
+      console.log(`\n  ${C.dim}Not a git repository or git not available.${C.reset}`);
+    }
+    console.log('');
+    return true;
+  }
+
+  if (cmd === '/log') {
+    console.log(`\n  ${C.dim}Log: ${logFile}${C.reset}\n`);
+    return true;
+  }
+
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  MAIN INPUT HANDLER
+// ═══════════════════════════════════════════════════════════════
+
+let projectContext = '';
+
+async function handleUserInput(input, rl) {
+  const trimmed = input.trim();
+  if (!trimmed) return;
+
+  // Handle slash commands
+  if (trimmed.startsWith('/')) {
+    if (handleCommand(trimmed)) return;
+    // Unknown command — pass through to Knoxis
+  }
+
+  // Block input while Claude is running
+  if (isClaudeRunning) {
+    console.log(`\n  ${C.yellow}Claude is still working. Wait for it to finish or press Ctrl+C to cancel.${C.reset}\n`);
+    return;
+  }
+
+  // Add to conversation
+  conversationHistory.push({ role: 'user', content: trimmed });
+  log(`USER: ${trimmed}`);
+
+  try {
+    // Send to Knoxis (Groq)
+    trimHistory();
+    const response = await callGroq(conversationHistory, projectContext);
+
+    if (response.action === 'dispatch' && response.claudePrompt) {
+      // ─── DISPATCH TO CLAUDE ───
+      printKnoxis(response.message);
+      log(`KNOXIS (dispatch): ${response.message}`);
+
+      // Record the assistant dispatch decision
+      conversationHistory.push({
+        role: 'assistant',
+        content: JSON.stringify({ action: 'dispatch', message: response.message })
+      });
+
+      printDivider('Dispatching to Claude Code', C.blue);
+      if (!verbose) printClaudeStatus('starting...');
+
+      try {
+        const result = await dispatchToClaude(response.claudePrompt);
+
+        printDivider(`Claude finished (${result.elapsed}s, ${result.lines} lines)`, C.green);
+
+        // Send output to Knoxis for review
+        const reviewMessages = [
+          ...conversationHistory,
+          {
+            role: 'user',
+            content: `[SYSTEM: Claude Code finished (exit ${result.exitCode}, ${result.elapsed}s). Review the output and summarize for the user. Use action "respond".]\n\nClaude output:\n${truncateForReview(result.output)}`
+          }
+        ];
+
+        const review = await callGroq(reviewMessages, projectContext);
+        printKnoxis(review.message);
+        log(`KNOXIS (review): ${review.message}`);
+
+        // Track dispatch summary (short version for system prompt context)
+        const shortSummary = review.message.split('\n')[0].slice(0, 150);
+        dispatchSummaries.push(shortSummary);
+
+        // Add review to history
+        conversationHistory.push({
+          role: 'assistant',
+          content: JSON.stringify({ action: 'respond', message: review.message })
+        });
+
+      } catch (claudeErr) {
+        printDivider('Claude error', C.red);
+        const errMsg = `Claude hit an issue: ${claudeErr.message}. Want me to retry or take a different approach?`;
+        printKnoxis(errMsg);
+        log(`CLAUDE ERROR: ${claudeErr.message}`);
+        conversationHistory.push({
+          role: 'assistant',
+          content: JSON.stringify({ action: 'respond', message: errMsg })
+        });
+      }
+
+    } else {
+      // ─── DIRECT RESPONSE ───
+      printKnoxis(response.message);
+      log(`KNOXIS: ${response.message}`);
+      conversationHistory.push({
+        role: 'assistant',
+        content: JSON.stringify({ action: 'respond', message: response.message })
+      });
+    }
+
+  } catch (err) {
+    console.log(`\n  ${C.red}Error: ${err.message}${C.reset}\n`);
+    log(`ERROR: ${err.message}`);
+    // Remove the user message that caused the error so they can retry
+    if (conversationHistory.length > 0 && conversationHistory[conversationHistory.length - 1].role === 'user') {
+      conversationHistory.pop();
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  ENTRY POINT
+// ═══════════════════════════════════════════════════════════════
+
+async function main() {
+  // Preflight checks
+  if (!GROQ_API_KEY) {
+    console.error(`\n  ${C.red}Error: GROQ_API_KEY not found.${C.reset}`);
+    console.error(`  Set it via environment variable or in ~/.knoxis/config.json\n`);
+    process.exit(1);
+  }
+
+  if (!checkClaudeInstalled()) {
+    console.error(`\n  ${C.red}Error: 'claude' CLI not found in PATH.${C.reset}`);
+    console.error(`  Install Claude Code: npm install -g @anthropic-ai/claude-code\n`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(WORKSPACE)) {
+    console.error(`\n  ${C.red}Error: Workspace not found: ${WORKSPACE}${C.reset}\n`);
+    process.exit(1);
+  }
+
+  // Detect project
+  projectContext = detectProject();
+
+  // Print header
+  printHeader();
+  if (projectContext) {
+    console.log(`  ${C.dim}${projectContext}${C.reset}\n`);
+  }
+
+  log(`SESSION START: ${SESSION_ID}`);
+  log(`WORKSPACE: ${WORKSPACE}`);
+  log(`PROJECT: ${projectContext}`);
+
+  // Set up readline
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `  ${C.green}You:${C.reset} `,
+  });
+
+  // Handle Ctrl+C — kill Claude if running, otherwise exit
+  process.on('SIGINT', () => {
+    if (isClaudeRunning && activeClaudeProc) {
+      console.log(`\n\n  ${C.yellow}Cancelling Claude...${C.reset}\n`);
+      try { activeClaudeProc.kill('SIGTERM'); } catch (e) {}
+      setTimeout(() => {
+        try { if (activeClaudeProc) activeClaudeProc.kill('SIGKILL'); } catch (e) {}
+      }, 3000);
+    } else {
+      log('SESSION END (Ctrl+C)');
+      console.log(`\n\n  ${C.dim}Session ended. ${claudeDispatches} dispatches to Claude.${C.reset}`);
+      console.log(`  ${C.dim}Log: ${logFile}${C.reset}\n`);
+      process.exit(0);
+    }
+  });
+
+  // Greeting — either with initial task or open-ended
+  const initialTask = loadInitialTask();
+
+  try {
+    if (initialTask) {
+      // Start with a task already loaded
+      const greetingContent = `[SYSTEM: Session started. Workspace: ${WORKSPACE}. Project: ${projectContext || 'unknown'}. The user has provided an initial task. Acknowledge it and either ask a clarifying question or dispatch to Claude if it's clear enough.]\n\nTask: ${initialTask}`;
+      conversationHistory.push({ role: 'user', content: greetingContent });
+      log(`INITIAL TASK: ${initialTask}`);
+
+      const greeting = await callGroq(conversationHistory, projectContext);
+
+      if (greeting.action === 'dispatch' && greeting.claudePrompt) {
+        printKnoxis(greeting.message);
+        conversationHistory.push({
+          role: 'assistant',
+          content: JSON.stringify({ action: 'dispatch', message: greeting.message })
+        });
+
+        printDivider('Dispatching to Claude Code', C.blue);
+        if (!verbose) printClaudeStatus('starting...');
+
+        const result = await dispatchToClaude(greeting.claudePrompt);
+        printDivider(`Claude finished (${result.elapsed}s, ${result.lines} lines)`, C.green);
+
+        const reviewMessages = [
+          ...conversationHistory,
+          {
+            role: 'user',
+            content: `[SYSTEM: Claude Code finished (exit ${result.exitCode}, ${result.elapsed}s). Review and summarize.]\n\nClaude output:\n${truncateForReview(result.output)}`
+          }
+        ];
+
+        const review = await callGroq(reviewMessages, projectContext);
+        printKnoxis(review.message);
+        dispatchSummaries.push(review.message.split('\n')[0].slice(0, 150));
+        conversationHistory.push({
+          role: 'assistant',
+          content: JSON.stringify({ action: 'respond', message: review.message })
+        });
+      } else {
+        printKnoxis(greeting.message);
+        conversationHistory.push({
+          role: 'assistant',
+          content: JSON.stringify(greeting)
+        });
+      }
+
+    } else {
+      // Open-ended greeting
+      conversationHistory.push({
+        role: 'user',
+        content: `[SYSTEM: Collaborative session started. Workspace: ${WORKSPACE}. Project: ${projectContext || 'unknown'}. Greet the user briefly (1-2 sentences) and ask what they want to work on.]`
+      });
+
+      const greeting = await callGroq(conversationHistory, projectContext);
+      printKnoxis(greeting.message);
+      conversationHistory.push({
+        role: 'assistant',
+        content: JSON.stringify(greeting)
+      });
+    }
+  } catch (e) {
+    printKnoxis("Hey, I'm ready. What are we working on?");
+    conversationHistory.push({
+      role: 'assistant',
+      content: JSON.stringify({ action: 'respond', message: "Hey, I'm ready. What are we working on?" })
+    });
+  }
+
+  // Main loop
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    await handleUserInput(line, rl);
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    log('SESSION END (stdin closed)');
+    console.log(`\n  ${C.dim}Session ended. Log: ${logFile}${C.reset}\n`);
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  console.error(`\n  ${C.red}Fatal: ${err.message}${C.reset}\n`);
+  log(`FATAL: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "knoxis-collab",
+  "version": "1.0.0",
+  "description": "Three-way collaborative programming — User + Knoxis + Claude Code in a persistent session",
+  "main": "knoxis-collab.js",
+  "bin": {
+    "knoxis-collab": "./knoxis-collab.js"
+  },
+  "keywords": [
+    "knoxis",
+    "pair-programming",
+    "collaboration",
+    "claude",
+    "qig"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "knoxis-collab.js"
+  ]
+}