cc-reviewer 1.5.3 → 1.7.0

package/commands/ask-codex.md

@@ -0,0 +1,35 @@
+# Ask Codex
+
+Ask OpenAI Codex CLI for help as a peer engineer.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## Codex Strengths
+- **Correctness**: Logic errors, edge cases, bugs
+- **Performance**: Efficiency, complexity analysis
+- **Security**: Vulnerability detection
+
+## Tool Invocation
+
+Call `ask_codex` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Response
+
+1. **Read the answer** and key points
+2. **Check file references** — verify they exist
+3. **Evaluate suggested actions** — do they make sense?
+4. **Apply your judgment** — you may disagree
+5. **Act on the suggestions** or ask follow-up questions
+
+$ARGUMENTS

package/commands/ask-gemini.md

@@ -0,0 +1,35 @@
+# Ask Gemini
+
+Ask Google Gemini CLI for help as a peer engineer.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## Gemini Strengths
+- **Architecture**: Design patterns, structure
+- **Scalability**: Load handling, bottlenecks
+- **Maintainability**: Code clarity, tech debt
+
+## Tool Invocation
+
+Call `ask_gemini` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Response
+
+1. **Read the answer** and key points
+2. **Check file references** — verify they exist
+3. **Evaluate suggested actions** — do they make sense?
+4. **Apply your judgment** — you may disagree
+5. **Act on the suggestions** or ask follow-up questions
+
+$ARGUMENTS

package/commands/ask-multi.md

@@ -0,0 +1,38 @@
+# Ask Multi
+
+Ask both Codex and Gemini for help in parallel — get multiple perspectives.
+
+## Arguments
+- `$ARGUMENTS` - Your question or request
+
+## When to Use
+
+Use `/ask-multi` when you want perspectives from both models on the same question.
+
+## Tool Invocation
+
+Call `ask_multi` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "prompt": "<your question or request from $ARGUMENTS>",
+  "taskType": "<infer from request: plan|debug|explain|question|fix|explore|general>",
+  "relevantFiles": ["<files related to the question>"],
+  "context": "<any error messages or prior analysis>"
+}
+```
+
+## After Receiving Responses
+
+You will receive separate responses from each model.
+
+### Synthesize
+
+1. **Find agreements** — both models say the same thing (higher confidence)
+2. **Identify conflicts** — they disagree (YOU decide who's right)
+3. **Note unique insights** — findings only one model provided
+4. **Verify file references** — check they exist
+5. **Make YOUR recommendation** — don't just relay, apply judgment
+
+$ARGUMENTS

package/dist/adapters/base.d.ts

@@ -5,8 +5,8 @@
  * Makes it easy to add new models (Ollama, Azure, etc.) without
  * changing the core orchestration logic.
  */
-import { ReviewOutput } from '../schema.js';
-import { FocusArea, OutputType, ReasoningEffort } from '../types.js';
+import { ReviewOutput, PeerOutput } from '../schema.js';
+import { FocusArea, OutputType, ReasoningEffort, TaskType } from '../types.js';
 export interface ReviewerCapabilities {
     /** Display name for this reviewer */
     name: string;
@@ -43,6 +43,24 @@ export interface ReviewRequest {
     /** Expert role configuration (optional override) */
     expertRole?: ExpertRole;
 }
+export interface PeerRequest {
+    /** Working directory containing the code */
+    workingDir: string;
+    /** The question or request from CC */
+    prompt: string;
+    /** Hint about the type of task */
+    taskType?: TaskType;
+    /** Files the peer should focus on */
+    relevantFiles?: string[];
+    /** Additional context (error messages, prior analysis) */
+    context?: string;
+    /** Areas to focus on */
+    focusAreas?: FocusArea[];
+    /** Custom instructions from the user */
+    customPrompt?: string;
+    /** Reasoning effort level (for models that support it) */
+    reasoningEffort?: ReasoningEffort;
+}
 export interface ExpertRole {
     name: string;
     description: string;
@@ -74,6 +92,20 @@ export interface ReviewError {
     message: string;
     details?: Record<string, unknown>;
 }
+export interface PeerSuccess {
+    success: true;
+    output: PeerOutput;
+    rawOutput?: string;
+    executionTimeMs: number;
+}
+export interface PeerFailure {
+    success: false;
+    error: ReviewError;
+    suggestion?: string;
+    rawOutput?: string;
+    executionTimeMs: number;
+}
+export type PeerResult = PeerSuccess | PeerFailure;
 /**
  * Base interface that all reviewer adapters must implement.
  * This allows easy addition of new AI CLIs without changing orchestration logic.
@@ -87,6 +119,8 @@ export interface ReviewerAdapter {
     isAvailable(): Promise<boolean>;
     /** Run a review and return structured output */
     runReview(request: ReviewRequest): Promise<ReviewResult>;
+    /** Run a general-purpose peer request and return structured output */
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
     /**
      * Optional: Run peer review of another model's output
      * Future capability - not currently implemented by any adapter

package/dist/adapters/codex.d.ts

@@ -4,13 +4,15 @@
  * Implements the ReviewerAdapter interface for OpenAI's Codex CLI.
  * Specializes in correctness, edge cases, and performance analysis.
  */
-import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult } from './base.js';
+import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult, PeerRequest, PeerResult } from './base.js';
 export declare class CodexAdapter implements ReviewerAdapter {
     readonly id = "codex";
     getCapabilities(): ReviewerCapabilities;
     isAvailable(): Promise<boolean>;
     runReview(request: ReviewRequest): Promise<ReviewResult>;
     private runWithRetry;
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
+    private runPeerWithRetry;
     private runCli;
     private categorizeError;
     private getSuggestion;

package/dist/adapters/codex.js

@@ -9,8 +9,8 @@ import { existsSync, writeFileSync, unlinkSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { registerAdapter, } from './base.js';
-import { parseReviewOutput, parseLegacyMarkdownOutput, getReviewOutputJsonSchema } from '../schema.js';
-import { buildSimpleHandoff, buildHandoffPrompt, selectRole, } from '../handoff.js';
+import { parseReviewOutput, parseLegacyMarkdownOutput, getReviewOutputJsonSchema, getPeerOutputJsonSchema, parsePeerOutput } from '../schema.js';
+import { buildSimpleHandoff, buildHandoffPrompt, buildPeerPrompt, selectRole, } from '../handoff.js';
 // =============================================================================
 // CONFIGURATION
 // =============================================================================
@@ -89,7 +89,7 @@ export class CodexAdapter {
                     (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
             }
             // Run the CLI
-            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high');
+            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high', getReviewOutputJsonSchema);
             // Handle CLI errors
             if (result.exitCode !== 0) {
                 const error = this.categorizeError(result.stderr);
@@ -214,14 +214,105 @@ export class CodexAdapter {
             };
         }
     }
-    runCli(prompt, workingDir, reasoningEffort) {
+    async runPeerRequest(request) {
+        const startTime = Date.now();
+        if (!existsSync(request.workingDir)) {
+            return {
+                success: false,
+                error: {
+                    type: 'cli_error',
+                    message: `Working directory does not exist: ${request.workingDir}`,
+                },
+                suggestion: 'Check that the working directory path is correct',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        return this.runPeerWithRetry(request, 0, startTime);
+    }
+    async runPeerWithRetry(request, attempt, startTime, previousError, previousOutput) {
+        try {
+            let prompt = buildPeerPrompt({
+                workingDir: request.workingDir,
+                prompt: request.prompt,
+                taskType: request.taskType,
+                relevantFiles: request.relevantFiles,
+                context: request.context,
+                focusAreas: request.focusAreas,
+                customInstructions: request.customPrompt,
+                outputFormat: 'json',
+            });
+            if (attempt > 0) {
+                prompt += `\n\n---\n\n# RETRY ATTEMPT ${attempt + 1}\n\n` +
+                    `Previous output had issues: ${previousError}\n` +
+                    `Please fix these issues and provide valid JSON output.\n` +
+                    (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
+            }
+            const result = await this.runCli(prompt, request.workingDir, request.reasoningEffort || 'high', getPeerOutputJsonSchema);
+            if (result.exitCode !== 0) {
+                const error = this.categorizeError(result.stderr);
+                return {
+                    success: false,
+                    error,
+                    suggestion: this.getSuggestion(error),
+                    rawOutput: result.stderr,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            if (result.truncated) {
+                return {
+                    success: false,
+                    error: { type: 'cli_error', message: 'Output exceeded maximum buffer size (1MB)' },
+                    suggestion: 'Try a more focused request',
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            const output = parsePeerOutput(result.stdout);
+            if (!output) {
+                if (attempt < MAX_RETRIES) {
+                    return this.runPeerWithRetry(request, attempt + 1, startTime, 'Output did not match expected JSON schema', result.stdout);
+                }
+                return {
+                    success: false,
+                    error: { type: 'parse_error', message: 'Failed to parse peer output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) } },
+                    suggestion: 'The model may not be following the output format.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            return {
+                success: true,
+                output,
+                rawOutput: result.stdout,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                return { success: false, error: { type: 'cli_not_found', message: 'Codex CLI not found' },
+                    suggestion: 'Install with: npm install -g @openai/codex', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'No output for 2 minutes' },
+                    suggestion: 'Try a simpler request', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'MAX_TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'Task exceeded 60 minute maximum' },
+                    suggestion: 'Try a smaller scope', executionTimeMs: Date.now() - startTime };
+            }
+            return { success: false, error: { type: 'cli_error', message: err.message },
+                executionTimeMs: Date.now() - startTime };
+        }
+    }
+    runCli(prompt, workingDir, reasoningEffort, schemaGetter) {
         return new Promise((resolve, reject) => {
             // Create temp schema file for structured output
             let schemaFile = null;
             try {
                 const tempDir = mkdtempSync(join(tmpdir(), 'codex-schema-'));
                 schemaFile = join(tempDir, 'schema.json');
-                const schema = getReviewOutputJsonSchema();
+                const schema = schemaGetter();
                 writeFileSync(schemaFile, JSON.stringify(schema, null, 2), 'utf-8');
             }
             catch (err) {

package/dist/adapters/gemini.d.ts

@@ -4,13 +4,15 @@
  * Implements the ReviewerAdapter interface for Google's Gemini CLI.
  * Specializes in architecture, design patterns, and large-context analysis.
  */
-import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult } from './base.js';
+import { ReviewerAdapter, ReviewerCapabilities, ReviewRequest, ReviewResult, PeerRequest, PeerResult } from './base.js';
 export declare class GeminiAdapter implements ReviewerAdapter {
     readonly id = "gemini";
     getCapabilities(): ReviewerCapabilities;
     isAvailable(): Promise<boolean>;
     runReview(request: ReviewRequest): Promise<ReviewResult>;
     private runWithRetry;
+    runPeerRequest(request: PeerRequest): Promise<PeerResult>;
+    private runPeerWithRetry;
     private runCli;
     private categorizeError;
     private getSuggestion;

package/dist/adapters/gemini.js

@@ -7,8 +7,8 @@
 import { spawn } from 'child_process';
 import { existsSync } from 'fs';
 import { registerAdapter, } from './base.js';
-import { parseReviewOutput, parseLegacyMarkdownOutput } from '../schema.js';
-import { buildSimpleHandoff, buildHandoffPrompt, selectRole, } from '../handoff.js';
+import { parseReviewOutput, parseLegacyMarkdownOutput, parsePeerOutput } from '../schema.js';
+import { buildSimpleHandoff, buildHandoffPrompt, buildPeerPrompt, selectRole, } from '../handoff.js';
 // =============================================================================
 // CONFIGURATION
 // =============================================================================
@@ -212,6 +212,92 @@ export class GeminiAdapter {
             };
         }
     }
+    async runPeerRequest(request) {
+        const startTime = Date.now();
+        if (!existsSync(request.workingDir)) {
+            return {
+                success: false,
+                error: { type: 'cli_error', message: `Working directory does not exist: ${request.workingDir}` },
+                suggestion: 'Check that the working directory path is correct',
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        return this.runPeerWithRetry(request, 0, startTime);
+    }
+    async runPeerWithRetry(request, attempt, startTime, previousError, previousOutput) {
+        try {
+            let prompt = buildPeerPrompt({
+                workingDir: request.workingDir,
+                prompt: request.prompt,
+                taskType: request.taskType,
+                relevantFiles: request.relevantFiles,
+                context: request.context,
+                focusAreas: request.focusAreas,
+                customInstructions: request.customPrompt,
+                outputFormat: 'json',
+            });
+            if (attempt > 0) {
+                prompt += `\n\n---\n\n# RETRY ATTEMPT ${attempt + 1}\n\n` +
+                    `Previous output had issues: ${previousError}\n` +
+                    `Please fix these issues and provide valid JSON output.\n` +
+                    (previousOutput ? `\nPrevious output (for reference):\n${previousOutput.slice(0, 500)}...` : '');
+            }
+            const result = await this.runCli(prompt, request.workingDir);
+            if (result.exitCode !== 0) {
+                const error = this.categorizeError(result.stderr);
+                return {
+                    success: false, error,
+                    suggestion: this.getSuggestion(error),
+                    rawOutput: result.stderr,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            if (result.truncated) {
+                return {
+                    success: false,
+                    error: { type: 'cli_error', message: 'Output exceeded maximum buffer size (1MB)' },
+                    suggestion: 'Try a more focused request',
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            const output = parsePeerOutput(result.stdout);
+            if (!output) {
+                if (attempt < MAX_RETRIES) {
+                    return this.runPeerWithRetry(request, attempt + 1, startTime, 'Output did not match expected JSON schema', result.stdout);
+                }
+                return {
+                    success: false,
+                    error: { type: 'parse_error', message: 'Failed to parse peer output after retries',
+                        details: { rawOutput: result.stdout.slice(0, 1000) } },
+                    suggestion: 'The model may not be following the output format.',
+                    rawOutput: result.stdout,
+                    executionTimeMs: Date.now() - startTime,
+                };
+            }
+            return {
+                success: true, output,
+                rawOutput: result.stdout,
+                executionTimeMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                return { success: false, error: { type: 'cli_not_found', message: 'Gemini CLI not found' },
+                    suggestion: 'Install with: npm install -g @google/gemini-cli', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'No output for 10 minutes' },
+                    suggestion: 'Try a simpler request', executionTimeMs: Date.now() - startTime };
+            }
+            if (err.message === 'MAX_TIMEOUT') {
+                return { success: false, error: { type: 'timeout', message: 'Task exceeded 60 minute maximum' },
+                    suggestion: 'Try a smaller scope', executionTimeMs: Date.now() - startTime };
+            }
+            return { success: false, error: { type: 'cli_error', message: err.message },
+                executionTimeMs: Date.now() - startTime };
+        }
+    }
     runCli(prompt, workingDir) {
         return new Promise((resolve, reject) => {
             // Gemini CLI uses --yolo for auto-approval, prompt passed via stdin

package/dist/handoff.d.ts

@@ -230,3 +230,18 @@ export declare function buildSimpleHandoff(workingDir: string, ccOutput: string,
  * CC should call this to add its specific concerns
  */
 export declare function enhanceHandoff(handoff: Handoff, uncertainties?: Uncertainty[], questions?: Question[], decisions?: Decision[]): Handoff;
+export interface PeerPromptOptions {
+    workingDir: string;
+    prompt: string;
+    taskType?: string;
+    relevantFiles?: string[];
+    context?: string;
+    focusAreas?: FocusArea[];
+    customInstructions?: string;
+    outputFormat: 'json';
+}
+/**
+ * Build a prompt for general-purpose peer assistance (not review).
+ * The peer acts as a collaborative coworker, not a critic.
+ */
+export declare function buildPeerPrompt(options: PeerPromptOptions): string;

package/dist/handoff.js

@@ -476,3 +476,125 @@ export function enhanceHandoff(handoff, uncertainties, questions, decisions) {
         decisions: decisions || handoff.decisions,
     };
 }
+/**
+ * Build a prompt for general-purpose peer assistance (not review).
+ * The peer acts as a collaborative coworker, not a critic.
+ */
+export function buildPeerPrompt(options) {
+    const { workingDir, prompt, taskType, relevantFiles, context, focusAreas, customInstructions } = options;
+    // Select role based on focus areas (reuse existing role selection)
+    const role = selectRole(focusAreas);
+    const sections = [];
+    // SECTION 1: ROLE (adapted from review role)
+    sections.push(`# ROLE: ${role.name} — Peer Engineer
+
+${role.systemPrompt}
+
+You are acting as a collaborative peer engineer, NOT a reviewer.
+Your job is to help Claude Code (CC) with whatever it needs:
+planning, debugging, explaining, fixing, exploring, or answering questions.
+Be direct, specific, and actionable.`);
+    // SECTION 2: TASK
+    const taskLabel = taskType ? ` [${taskType.toUpperCase()}]` : '';
+    sections.push(`
+---
+
+# YOUR TASK${taskLabel}
+
+**Working Directory:** \`${workingDir}\`
+
+**CC's Request:**
+${prompt}
+${context ? `\n**Additional Context:**\n${context}` : ''}`);
+    // SECTION 3: RELEVANT FILES
+    if (relevantFiles && relevantFiles.length > 0) {
+        sections.push(`
+---
+
+# RELEVANT FILES
+
+CC suggests focusing on these files:
+${relevantFiles.map(f => `- \`${f}\``).join('\n')}
+
+Read these files to understand the context. Also explore related files if needed.`);
+    }
+    // SECTION 4: FOCUS AREAS
+    if (focusAreas && focusAreas.length > 0) {
+        sections.push(`
+---
+
+# FOCUS AREAS
+
+Prioritize these aspects: ${focusAreas.join(', ')}`);
+    }
+    // SECTION 5: CUSTOM INSTRUCTIONS
+    if (customInstructions) {
+        sections.push(`
+---
+
+# ADDITIONAL INSTRUCTIONS
+
+${customInstructions}`);
+    }
+    // SECTION 6: HOW TO WORK
+    sections.push(`
+---
+
+# HOW TO WORK
+
+1. Read the relevant files in the working directory
+2. Use \`git log --oneline -10\` and \`git diff\` if useful
+3. Think through the problem step by step
+4. Provide a clear, actionable answer
+5. Reference specific files and line numbers
+6. Suggest concrete next steps`);
+    // SECTION 7: OUTPUT FORMAT
+    sections.push(`
+---
+
+# OUTPUT FORMAT
+
+Respond with valid JSON:
+
+\`\`\`json
+{
+  "responder": "<your-name>",
+  "answer": "Your detailed response in markdown",
+  "confidence": 0.0-1.0,
+  "key_points": ["Point 1", "Point 2"],
+  "suggested_actions": [
+    {
+      "action": "What to do",
+      "priority": "high|medium|low",
+      "file": "path/to/file.ts",
+      "rationale": "Why"
+    }
+  ],
+  "file_references": [
+    {
+      "path": "path/to/file.ts",
+      "lines": "10-25",
+      "relevance": "Why this file matters"
+    }
+  ],
+  "alternatives": [
+    {
+      "topic": "The decision point",
+      "current_approach": "What exists now",
+      "alternative": "Different approach",
+      "tradeoffs": { "pros": ["..."], "cons": ["..."] },
+      "recommendation": "strongly_prefer|consider|situational|informational"
+    }
+  ],
+  "execution_notes": "Any notes about your process"
+}
+\`\`\`
+
+**Rules:**
+- Read files before making claims
+- Reference specific file paths and line numbers
+- Be concrete and actionable — no vague suggestions
+- Confidence reflects how sure YOU are about your answer
+- Include alternatives when there are meaningful tradeoffs`);
+    return sections.join('\n');
+}

package/dist/index.js

@@ -19,6 +19,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { handleCodexReview, handleGeminiReview, handleMultiReview, ReviewInputSchema, TOOL_DEFINITIONS } from './tools/feedback.js';
+import { handleAskCodex, handleAskGemini, handleAskMulti, PEER_TOOL_DEFINITIONS, } from './tools/peer.js';
+import { PeerInputSchema } from './schema.js';
 import { logCliStatus } from './cli/check.js';
 import { installCommands } from './commands.js';
 // Handle --setup flag: install commands and exit
@@ -51,6 +53,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             TOOL_DEFINITIONS.codex_review,
             TOOL_DEFINITIONS.gemini_review,
             TOOL_DEFINITIONS.multi_review,
+            PEER_TOOL_DEFINITIONS.ask_codex,
+            PEER_TOOL_DEFINITIONS.ask_gemini,
+            PEER_TOOL_DEFINITIONS.ask_multi,
         ],
     };
 });
@@ -71,6 +76,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const input = ReviewInputSchema.parse(args);
                 return await handleMultiReview(input);
             }
+            case 'ask_codex': {
+                const input = PeerInputSchema.parse(args);
+                return await handleAskCodex(input);
+            }
+            case 'ask_gemini': {
+                const input = PeerInputSchema.parse(args);
+                return await handleAskGemini(input);
+            }
+            case 'ask_multi': {
+                const input = PeerInputSchema.parse(args);
+                return await handleAskMulti(input);
+            }
             default:
                 return {
                     content: [{