knoxis-helper 1.3.4 → 1.4.1

package/bin/knoxis-helper.js

@@ -84,6 +84,7 @@ function ask(rl, question) {
 function installAgentLocally(force) {
   const sourceAgent = path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js');
   const sourcePairProgram = path.join(__dirname, '..', 'lib', 'knoxis-pair-program.js');
+  const sourceInteractivePair = path.join(__dirname, '..', 'lib', 'knoxis-interactive-pair.js');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
 
   if (!fs.existsSync(sourceAgent)) {
@@ -119,6 +120,11 @@ function installAgentLocally(force) {
     console.log('  Installed: knoxis-pair-program.js');
   }
 
+  if (fs.existsSync(sourceInteractivePair)) {
+    fs.copyFileSync(sourceInteractivePair, path.join(AGENT_DIR, 'knoxis-interactive-pair.js'));
+    console.log('  Installed: knoxis-interactive-pair.js');
+  }
+
   if (fs.existsSync(sourcePackage)) {
     fs.copyFileSync(sourcePackage, path.join(AGENT_DIR, 'package.json'));
   }

package/lib/knoxis-interactive-pair.js

@@ -0,0 +1,484 @@
+#!/usr/bin/env node
+
+/**
+ * Knoxis Interactive Pair Programming
+ *
+ * Multi-turn pair programming with Groq acting as your pair programmer
+ * (reviewing plans, answering questions, giving feedback) between
+ * Claude Code coding phases.
+ *
+ * Flow:
+ *   Phase 1: Claude reads codebase + creates implementation plan
+ *   Knoxis (Groq): Reviews plan, answers questions, approves/adjusts
+ *   Phase 2: Claude implements with feedback applied
+ *   Knoxis (Groq): Reviews implementation, flags issues
+ *   Phase 3: Claude addresses feedback + verifies build
+ *
+ * Usage:
+ *   KNOXIS_TASK_FILE=/tmp/task.txt node knoxis-interactive-pair.js
+ *   node knoxis-interactive-pair.js "add a health check endpoint"
+ *
+ * Env:
+ *   GROQ_API_KEY           - Required for Knoxis feedback (falls back to single-shot without it)
+ *   KNOXIS_TASK_FILE       - Path to file containing the task description
+ *   KNOXIS_GROQ_MODEL      - Groq model (default: llama-3.3-70b-versatile)
+ *   KNOXIS_MAX_PHASE_MS    - Max time per Claude phase in ms (default: 600000 = 10min)
+ *
+ * ZERO EXTERNAL DEPENDENCIES - uses only Node.js built-in modules
+ */
+
+const { spawn, spawnSync } = require('child_process');
+const crypto = require('crypto');
+const https = require('https');
+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 MAX_PHASE_MS = parseInt(process.env.KNOXIS_MAX_PHASE_MS || '600000', 10);
+const GROQ_MODEL = process.env.KNOXIS_GROQ_MODEL || 'llama-3.3-70b-versatile';
+
+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 || '';
+
+// === LOAD TASK ===
+function loadTask() {
+  // 1. Task file (set by local agent)
+  const taskFile = process.env.KNOXIS_TASK_FILE;
+  if (taskFile && fs.existsSync(taskFile)) {
+    return fs.readFileSync(taskFile, 'utf8').trim();
+  }
+
+  // 2. CLI argument
+  if (process.argv.length > 2) {
+    return process.argv.slice(2).join(' ');
+  }
+
+  // 3. Extract from CLAUDE.md
+  const claudeMd = path.join(process.cwd(), 'CLAUDE.md');
+  if (fs.existsSync(claudeMd)) {
+    const content = fs.readFileSync(claudeMd, 'utf8');
+    const match = content.match(/## Current Task\n([\s\S]*?)(?=\n## )/);
+    if (match) return match[1].trim();
+  }
+
+  return null;
+}
+
+// === LOAD PROJECT CONTEXT (from CLAUDE.md) ===
+function loadProjectContext() {
+  const claudeMd = path.join(process.cwd(), 'CLAUDE.md');
+  if (fs.existsSync(claudeMd)) {
+    return fs.readFileSync(claudeMd, 'utf8');
+  }
+  return '';
+}
+
+// === SESSION LOG ===
+let sessionLog = '';
+const logDir = path.join(process.cwd(), '.knoxis', 'sessions');
+
+function initSessionLog() {
+  try {
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+  } catch (e) {}
+}
+
+function appendLog(text) {
+  sessionLog += text + '\n';
+}
+
+function saveSessionLog() {
+  try {
+    const logFile = path.join(logDir, `${new Date().toISOString().replace(/[:.]/g, '-')}-${SESSION_ID.substring(0, 8)}.log`);
+    fs.writeFileSync(logFile, sessionLog, 'utf8');
+    return logFile;
+  } catch (e) {
+    return null;
+  }
+}
+
+// === GROQ API ===
+function callGroq(systemPrompt, userMessage) {
+  return new Promise((resolve) => {
+    if (!GROQ_API_KEY) {
+      resolve('Looks good. Go ahead and implement it following the existing patterns in the codebase.');
+      return;
+    }
+
+    const payload = JSON.stringify({
+      model: GROQ_MODEL,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage }
+      ],
+      temperature: 0.3,
+      max_tokens: 2000
+    });
+
+    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.choices && json.choices[0]) {
+            resolve(json.choices[0].message.content);
+          } else if (json.error) {
+            console.error('  Groq error:', json.error.message || JSON.stringify(json.error));
+            resolve('Proceed with your best judgment following existing patterns.');
+          } else {
+            resolve('Proceed with your best judgment following existing patterns.');
+          }
+        } catch (e) {
+          resolve('Proceed with your best judgment following existing patterns.');
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      console.error('  Groq request failed:', err.message);
+      resolve('Proceed with your best judgment following existing patterns.');
+    });
+    req.setTimeout(30000, () => {
+      req.destroy();
+      resolve('Proceed with your best judgment following existing patterns.');
+    });
+
+    req.write(payload);
+    req.end();
+  });
+}
+
+// === RUN CLAUDE TURN ===
+function runClaudeTurn(message, isResume) {
+  return new Promise((resolve) => {
+    // Check claude is available
+    const which = spawnSync('which', ['claude'], { stdio: 'pipe' });
+    if (which.status !== 0) {
+      resolve({ stdout: '', stderr: 'claude CLI not found', code: 127 });
+      return;
+    }
+
+    const args = ['-p', '--dangerously-skip-permissions'];
+    if (isResume) {
+      args.push('--resume', SESSION_ID);
+    } else {
+      args.push('--session-id', SESSION_ID);
+    }
+
+    const proc = spawn('claude', args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', chunk => {
+      const text = chunk.toString();
+      process.stdout.write(text);
+      stdout += text;
+    });
+
+    proc.stderr.on('data', chunk => {
+      const text = chunk.toString();
+      // Only show non-debug stderr
+      if (!text.includes('Debug:') && !text.includes('trace')) {
+        process.stderr.write(text);
+      }
+      stderr += text;
+    });
+
+    const timeout = setTimeout(() => {
+      console.log('\n  Phase timed out after ' + (MAX_PHASE_MS / 60000).toFixed(0) + ' minutes');
+      try { proc.kill('SIGTERM'); } catch (e) {}
+      setTimeout(() => {
+        try { proc.kill('SIGKILL'); } catch (e) {}
+      }, 5000);
+    }, MAX_PHASE_MS);
+
+    proc.on('close', code => {
+      clearTimeout(timeout);
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code: code || 0 });
+    });
+
+    proc.on('error', err => {
+      clearTimeout(timeout);
+      resolve({ stdout: stdout.trim(), stderr: err.message, code: 1 });
+    });
+
+    proc.stdin.write(message);
+    proc.stdin.end();
+  });
+}
+
+// === FALLBACK: SINGLE-SHOT (existing behavior) ===
+async function runSingleShot(task) {
+  console.log('');
+  console.log('  Running in single-shot mode (no Groq pair programmer)');
+  console.log('');
+
+  const result = await runClaudeTurn(task, false);
+  return result.code || 0;
+}
+
+// === MAIN ===
+async function main() {
+  const task = loadTask();
+  if (!task) {
+    console.error('No task found. Set KNOXIS_TASK_FILE, pass as CLI argument, or include in CLAUDE.md.');
+    process.exit(1);
+  }
+
+  const projectContext = loadProjectContext();
+  const hasGroq = !!GROQ_API_KEY;
+
+  initSessionLog();
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        KNOXIS INTERACTIVE PAIR PROGRAMMING                  ║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log('  Task:    ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
+  console.log('  Session: ' + SESSION_ID);
+  console.log('  Pair:    ' + (hasGroq ? 'Groq (' + GROQ_MODEL + ')' : 'Disabled (no GROQ_API_KEY)'));
+  console.log('  Timeout: ' + (MAX_PHASE_MS / 60000).toFixed(0) + ' min per phase');
+  console.log('');
+
+  appendLog('# Knoxis Interactive Pair Programming Session');
+  appendLog('Session: ' + SESSION_ID);
+  appendLog('Task: ' + task);
+  appendLog('Date: ' + new Date().toISOString());
+  appendLog('');
+
+  // If no Groq, fall back to enhanced single-shot
+  if (!hasGroq) {
+    const code = await runSingleShot(task);
+    process.exit(code);
+  }
+
+  // Build Groq system prompt
+  // Trim project context to avoid exceeding Groq limits
+  const contextForGroq = projectContext.substring(0, 5000);
+  const groqSystem = [
+    'You are Knoxis, an experienced senior developer pair programming with Claude Code (an AI coding assistant).',
+    'The developer submitted this task remotely and is not available. You make decisions on their behalf.',
+    '',
+    'ORIGINAL TASK:',
+    task,
+    '',
+    'PROJECT CONTEXT (from CLAUDE.md):',
+    contextForGroq,
+    '',
+    'YOUR ROLE:',
+    '- Answer questions decisively. Pick the most pragmatic option.',
+    '- Review plans critically but constructively.',
+    '- If the plan is solid, approve it quickly: "Good plan. Proceed with implementation."',
+    '- If there are issues, be specific about what to change.',
+    '- Prefer approaches that follow existing patterns in the codebase.',
+    '- Keep responses concise (3-8 sentences). Claude has full context.',
+    '- NEVER ask Claude questions. You provide answers and direction only.',
+    '- If Claude lists multiple options, pick the most practical one.',
+    '- Push for minimal, focused changes. No scope creep.',
+  ].join('\n');
+
+
+  // ═══════════════════════════════════════════
+  // PHASE 1: PLANNING
+  // ═══════════════════════════════════════════
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  PHASE 1: Understanding & Planning');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  appendLog('## Phase 1: Planning\n');
+
+  const planPrompt = [
+    task,
+    '',
+    'Before implementing, I need you to:',
+    '1. Read the relevant existing code in this workspace',
+    '2. Understand the current patterns and conventions',
+    '3. Create a brief implementation plan (which files to change, what approach)',
+    '4. Note any key decisions or trade-offs you see',
+    '',
+    'Share your plan and then STOP. Do not implement yet. I will review it first.',
+  ].join('\n');
+
+  const phase1 = await runClaudeTurn(planPrompt, false);
+  appendLog(phase1.stdout + '\n');
+
+  if (phase1.code !== 0 && !phase1.stdout) {
+    console.log('');
+    console.log('  Phase 1 failed (exit ' + phase1.code + '). Falling back to single-shot.');
+    appendLog('Phase 1 failed. Falling back to single-shot.\n');
+    const code = await runSingleShot(task);
+    const logFile = saveSessionLog();
+    if (logFile) console.log('  Log: ' + logFile);
+    process.exit(code);
+  }
+
+
+  // ═══════════════════════════════════════════
+  // KNOXIS REVIEWS PLAN
+  // ═══════════════════════════════════════════
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  KNOXIS: Reviewing plan...');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  const planReview = await callGroq(
+    groqSystem,
+    'Claude produced the following plan:\n\n'
+      + phase1.stdout.substring(0, 8000)
+      + '\n\nReview this plan. Answer any questions Claude asked. Approve or suggest specific changes. Then tell Claude to proceed with implementation.'
+  );
+
+  console.log('');
+  console.log('  Knoxis: ' + planReview);
+  console.log('');
+  appendLog('## Knoxis Plan Review\n' + planReview + '\n');
+
+
+  // ═══════════════════════════════════════════
+  // PHASE 2: IMPLEMENTATION
+  // ═══════════════════════════════════════════
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  PHASE 2: Implementation');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  appendLog('## Phase 2: Implementation\n');
+
+  const phase2 = await runClaudeTurn(planReview, true);
+  appendLog(phase2.stdout.substring(0, 10000) + '\n');
+
+  // If resume failed (session not found), try context accumulation fallback
+  if (phase2.code !== 0 && phase2.stderr && phase2.stderr.includes('session')) {
+    console.log('');
+    console.log('  Session resume failed. Using context accumulation fallback.');
+    appendLog('Session resume failed. Using context accumulation.\n');
+
+    const fallbackPrompt = [
+      'Previously you created this plan:',
+      phase1.stdout.substring(0, 4000),
+      '',
+      'Feedback from your pair programmer:',
+      planReview,
+      '',
+      'Now implement the solution. Follow existing patterns in the codebase.',
+    ].join('\n');
+
+    const phase2b = await runClaudeTurn(fallbackPrompt, false);
+    // Use new session for subsequent turns
+    appendLog(phase2b.stdout.substring(0, 10000) + '\n');
+
+    // Skip to verification with this result
+    const verifyPrompt = 'Verify the changes compile/build correctly. Run the most relevant test or build command. Give a brief summary of what was done.';
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('  PHASE 3: Verification');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+
+    const phase3b = await runClaudeTurn(verifyPrompt, true);
+    appendLog('## Phase 3: Verification\n' + phase3b.stdout.substring(0, 5000) + '\n');
+
+    console.log('');
+    console.log('╔══════════════════════════════════════════════════════════════╗');
+    console.log('║        PAIR PROGRAMMING SESSION COMPLETE                    ║');
+    console.log('╚══════════════════════════════════════════════════════════════╝');
+    const logFile = saveSessionLog();
+    if (logFile) console.log('  Log: ' + logFile);
+    console.log('  Resume: claude --resume ' + SESSION_ID);
+    console.log('');
+    process.exit(phase3b.code || 0);
+  }
+
+
+  // ═══════════════════════════════════════════
+  // KNOXIS REVIEWS IMPLEMENTATION
+  // ═══════════════════════════════════════════
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  KNOXIS: Reviewing implementation...');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  const implReview = await callGroq(
+    groqSystem,
+    'Claude implemented the following:\n\n'
+      + phase2.stdout.substring(0, 8000)
+      + '\n\nReview the implementation. If there are issues, describe specifically what needs fixing. If it looks correct, tell Claude to verify the build/tests and summarize what was done.'
+  );
+
+  console.log('');
+  console.log('  Knoxis: ' + implReview);
+  console.log('');
+  appendLog('## Knoxis Implementation Review\n' + implReview + '\n');
+
+
+  // ═══════════════════════════════════════════
+  // PHASE 3: VERIFICATION & FIXES
+  // ═══════════════════════════════════════════
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  PHASE 3: Review & Verification');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  appendLog('## Phase 3: Verification\n');
+
+  const phase3 = await runClaudeTurn(
+    implReview
+      + '\n\nAfter addressing any feedback above, verify the changes compile/build correctly. Run the most relevant test or build command. Give a brief summary of everything that was done.',
+    true
+  );
+  appendLog(phase3.stdout.substring(0, 5000) + '\n');
+
+
+  // ═══════════════════════════════════════════
+  // DONE
+  // ═══════════════════════════════════════════
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        PAIR PROGRAMMING SESSION COMPLETE                    ║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log('  Session: ' + SESSION_ID);
+  console.log('  Resume:  claude --resume ' + SESSION_ID);
+  const logFile = saveSessionLog();
+  if (logFile) console.log('  Log:     ' + logFile);
+  console.log('');
+
+  process.exit(phase3.code || 0);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err.message || err);
+  const logFile = saveSessionLog();
+  if (logFile) console.error('Log: ' + logFile);
+  process.exit(1);
+});

package/lib/knoxis-local-agent.js

@@ -446,7 +446,7 @@ async function handleRequest(req, res) {
       status: 'healthy',
       platform: os.platform(),
       agent: 'knoxis-local-agent',
-      version: '2.3.0-stable',
+      version: '2.4.0-interactive',
       secure: serverMeta.secure,
       port: serverMeta.port,
       dependencies: 'none',
@@ -478,16 +478,40 @@ async function handleRequest(req, res) {
         return sendJSON(res, result.success ? 200 : 500, result, requestOrigin);
       }
 
+      // Write CLAUDE.md if provided
+      if (body.claudeMdContent && workspace && fs.existsSync(workspace)) {
+        try {
+          fs.writeFileSync(path.join(workspace, 'CLAUDE.md'), body.claudeMdContent, 'utf8');
+          console.log('📄 Wrote CLAUDE.md (' + body.claudeMdContent.length + ' chars)');
+        } catch (writeErr) {
+          console.warn('⚠️ Failed to write CLAUDE.md:', writeErr.message);
+        }
+      }
+
+      // If prompt is provided, write to temp file and pipe via stdin
+      // (same approach as WebSocket relay — avoids shell escaping issues)
+      let finalCommand = command;
+      let promptFile = null;
+      if (prompt && prompt.trim().length > 0) {
+        promptFile = path.join(os.tmpdir(), 'knoxis-task-' + (sessionId || Date.now()) + '.txt');
+        fs.writeFileSync(promptFile, prompt, 'utf8');
+        finalCommand = 'cat "' + promptFile + '" | claude --dangerously-skip-permissions';
+        console.log('📝 Task written to ' + promptFile + ' (' + prompt.length + ' chars)');
+      }
+
       if (platform === 'darwin') {
-        await openMacTerminal(workspace, command);
+        await openMacTerminal(workspace, finalCommand);
+        if (promptFile) setTimeout(() => { try { fs.unlinkSync(promptFile); } catch (e) {} }, 30000);
         return sendJSON(res, 200, { success: true, message: 'Terminal opened on macOS', platform: 'darwin' }, requestOrigin);
       }
       if (platform === 'win32') {
-        await openWindowsTerminal(workspace, command);
+        await openWindowsTerminal(workspace, finalCommand);
+        if (promptFile) setTimeout(() => { try { fs.unlinkSync(promptFile); } catch (e) {} }, 30000);
         return sendJSON(res, 200, { success: true, message: 'Terminal opened on Windows', platform: 'win32' }, requestOrigin);
       }
 
-      await openLinuxTerminal(workspace, command);
+      await openLinuxTerminal(workspace, finalCommand);
+      if (promptFile) setTimeout(() => { try { fs.unlinkSync(promptFile); } catch (e) {} }, 30000);
       return sendJSON(res, 200, { success: true, message: 'Terminal opened on Linux', platform: 'linux' }, requestOrigin);
 
     } catch (error) {
@@ -655,28 +679,54 @@ async function handleRequest(req, res) {
 
   // ===== PAIR PROGRAMMING ENDPOINTS =====
 
+  // Resolve the interactive pair programming script
+  function resolveInteractiveScript() {
+    const candidates = [
+      path.join(__dirname, 'knoxis-interactive-pair.js'),
+      path.join(__dirname, '..', 'knoxis-interactive-pair.js'),
+      path.join(os.homedir(), '.knoxis', 'agent', 'knoxis-interactive-pair.js'),
+      path.join(__dirname, '..', '..', 'knoxis-interactive-pair.js'),
+    ];
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    return null;
+  }
+
   // Start pair programming session (opens terminal)
   if (pathname === '/pair/start' && method === 'POST') {
     // Build CLAUDE.md content from task when backend doesn't provide claudeMdContent
-    function buildClaudeMdFromTask(taskText, workspacePath) {
+    function buildClaudeMdFromTask(taskText, workspacePath, interactive) {
       const lines = [];
       lines.push('# Project Instructions\n');
       lines.push('## Current Task');
       lines.push(taskText);
       lines.push('');
-      lines.push('## Working Agreement');
-      lines.push('- Work autonomously. Do not ask clarifying questions - make your best engineering judgment and proceed.');
-      lines.push('- Read and understand existing code before making changes.');
-      lines.push('- Follow existing patterns in the codebase.');
-      lines.push('- Keep changes minimal and focused on the task.');
-      lines.push('- Verify your work compiles/runs where possible.');
-      lines.push('- Be direct and concise in any output.');
+      if (interactive) {
+        lines.push('## Working Agreement');
+        lines.push('- You are pair programming with Knoxis, a senior developer who reviews your work between phases.');
+        lines.push('- Phase 1: Read the codebase and share your implementation plan with key decisions.');
+        lines.push('- Phase 2: After receiving feedback, implement the solution following existing patterns.');
+        lines.push('- Phase 3: After review, address any feedback and verify the build.');
+        lines.push('- Share your reasoning on decisions - your pair programmer will provide feedback.');
+        lines.push('- Follow existing patterns in the codebase.');
+        lines.push('- Keep changes minimal and focused on the task.');
+      } else {
+        lines.push('## Working Agreement');
+        lines.push('- Work autonomously. Do not ask clarifying questions - make your best engineering judgment and proceed.');
+        lines.push('- Read and understand existing code before making changes.');
+        lines.push('- Follow existing patterns in the codebase.');
+        lines.push('- Keep changes minimal and focused on the task.');
+        lines.push('- Verify your work compiles/runs where possible.');
+        lines.push('- Be direct and concise in any output.');
+      }
       return lines.join('\n');
     }
 
     try {
       const body = await parseBody(req);
       const { workspace, task, file, provider, headless, sessionId, claudeMdContent } = body;
+      const interactive = body.interactive === true || body.interactive === 'true';
 
       if (!task) {
         return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
@@ -695,7 +745,7 @@ async function handleRequest(req, res) {
       // Write CLAUDE.md for supplementary context.
       // If claudeMdContent was provided (from backend relay), use it directly.
       // Otherwise, build it from the task field.
-      const effectiveClaudeMd = claudeMdContent || buildClaudeMdFromTask(task, workspace);
+      const effectiveClaudeMd = claudeMdContent || buildClaudeMdFromTask(task, workspace, interactive);
       if (effectiveClaudeMd && fs.existsSync(workspaceDir)) {
         try {
           fs.writeFileSync(path.join(workspaceDir, 'CLAUDE.md'), effectiveClaudeMd, 'utf8');
@@ -705,14 +755,42 @@ async function handleRequest(req, res) {
         }
       }
 
-      // Write the actual task to a temp file and pipe it to Claude via stdin.
-      // This avoids shell escaping issues with quotes/backticks/etc in the task text.
+      // Write the actual task to a temp file
       const promptFile = path.join(os.tmpdir(), `knoxis-task-${sessionId || Date.now()}.txt`);
       const promptText = file ? `Working on file: ${file}\n\nTask: ${task}` : task;
       fs.writeFileSync(promptFile, promptText, 'utf8');
-      const command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+
+      // Determine the command to run
+      let command;
+      let mode = 'single-shot';
+
+      if (interactive) {
+        const scriptPath = resolveInteractiveScript();
+        if (scriptPath) {
+          // Interactive mode: multi-turn with Groq pair programmer
+          command = `KNOXIS_TASK_FILE="${promptFile}" node "${scriptPath}"`;
+          mode = 'interactive';
+          console.log(`🤝 Interactive mode: ${scriptPath}`);
+        } else {
+          // Interactive requested but script not found - fall back to single-shot
+          console.warn('⚠️ Interactive script not found, falling back to single-shot');
+          command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+        }
+      } else {
+        // Standard single-shot mode: pipe task to Claude
+        command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+      }
 
       if (headless) {
+        if (interactive && mode === 'interactive') {
+          // Headless interactive: run the script directly as a process
+          const result = await runHeadlessProcess({
+            workspace: workspaceDir,
+            command,
+            sessionLabel: sessionId || 'interactive-pair'
+          });
+          return sendJSON(res, result.success ? 200 : 500, { ...result, mode }, requestOrigin);
+        }
         const result = await runHeadlessProcess({
           workspace: workspaceDir,
           command: provider && String(provider).toLowerCase() === 'codex' ? 'codex' : 'claude',
@@ -731,9 +809,15 @@ async function handleRequest(req, res) {
         await openLinuxTerminal(workspaceDir, command);
       }
 
+      // Clean up prompt file after a delay (terminal needs time to read it)
+      if (!interactive) {
+        setTimeout(() => { try { fs.unlinkSync(promptFile); } catch (e) {} }, 30000);
+      }
+
       return sendJSON(res, 200, {
         success: true,
-        message: 'Pair programming session started',
+        message: interactive ? 'Interactive pair programming session started' : 'Pair programming session started',
+        mode,
         workspace: workspaceDir,
         task,
         file: file || null
@@ -1060,10 +1144,25 @@ function connectRelayWebSocket() {
           }
         }
 
+        const interactive = msg.interactive === true;
+
         if (taskPrompt) {
           promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
           fs.writeFileSync(promptFile, taskPrompt, 'utf8');
-          command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+
+          if (interactive) {
+            // Interactive mode: use multi-turn pair programming script
+            const scriptPath = resolveInteractiveScript();
+            if (scriptPath) {
+              command = `KNOXIS_TASK_FILE="${promptFile}" node "${scriptPath}"`;
+              console.log(`   🤝 Interactive mode: ${scriptPath}`);
+            } else {
+              command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+              console.warn(`   ⚠️ Interactive script not found, falling back to single-shot`);
+            }
+          } else {
+            command = `cat "${promptFile}" | claude --dangerously-skip-permissions`;
+          }
           console.log(`   📝 Task written to ${promptFile} (${taskPrompt.length} chars)`);
         } else {
           console.warn(`   ⚠️ No task prompt found — Claude will run with: ${command.substring(0, 80)}`);
@@ -1075,7 +1174,7 @@ function connectRelayWebSocket() {
             result = await runHeadlessProcess({
               workspace: wsDir,
               command,
-              prompt: msg.prompt,
+              prompt: interactive ? undefined : msg.prompt,
               sessionLabel: msg.requestId || 'relay'
             });
           } else {
@@ -1087,17 +1186,17 @@ function connectRelayWebSocket() {
             } else {
               await openLinuxTerminal(wsDir, command);
             }
-            result = { success: true, message: 'Terminal opened via relay' };
+            result = { success: true, message: interactive ? 'Interactive pair programming started via relay' : 'Terminal opened via relay', mode: interactive ? 'interactive' : 'single-shot' };
           }
         } catch (err) {
           result = { success: false, error: err.message };
         }
 
-        // Clean up temp prompt file (Claude already read it)
-        if (promptFile) {
+        // Clean up temp prompt file after delay (interactive script reads it at startup)
+        if (promptFile && !interactive) {
           setTimeout(() => {
             try { fs.unlinkSync(promptFile); } catch (e) {}
-          }, 5000); // Delay to ensure cat has finished piping
+          }, 5000);
         }
 
         // Send result back to backend
@@ -1240,7 +1339,7 @@ server.listen(serverMeta.port, () => {
   const scheme = serverMeta.secure ? 'https' : 'http';
   console.log('');
   console.log('╔══════════════════════════════════════════════════════════════╗');
-  console.log('║       🚀 KNOXIS LOCAL AGENT v2.3.0 (Prompt Pipe Fix)         ║');
+  console.log('║       🚀 KNOXIS LOCAL AGENT v2.4.0 (Interactive Pair)         ║');
   console.log('╚══════════════════════════════════════════════════════════════╝');
   console.log('');
   console.log(`🔒 Mode: ${serverMeta.secure ? 'HTTPS (Secure)' : 'HTTP (Insecure - see warning below)'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"