cc-reviewer 1.2.2 → 1.2.4

package/README.md

@@ -4,11 +4,19 @@ Get second-opinion feedback from OpenAI Codex and Google Gemini CLIs on Claude C
 
 ## Quick Install
 
+**Step 1: Add the MCP server**
 ```bash
 claude mcp add -s user cc-reviewer -- npx -y cc-reviewer
 ```
 
-That's it! Restart Claude Code and the tools are available.
+**Step 2: Install slash commands**
+```bash
+npx cc-reviewer-setup
+```
+
+**Step 3: Restart Claude Code**
+
+The MCP tools and slash commands (`/codex`, `/gemini`, `/multi`, `/council`) are now available.
 
 Verify with:
 ```bash
@@ -39,19 +47,21 @@ npm install -g @google/gemini-cli
 gemini  # follow auth prompts
 ```
 
-## Slash Commands (Optional)
+## Usage
 
-Copy the slash commands to your global commands folder:
+These tools provide **external second-opinion reviews** from Codex and Gemini CLIs. They are designed to complement Claude Code's native review capabilities, not replace them.
 
-```bash
-# Clone repo (if not already)
-git clone https://github.com/SimonRen/cc-reviewer.git
+**When to use:**
+- `/codex` or "review with codex" - Get external Codex review
+- `/gemini` or "review with gemini" - Get external Gemini review
+- `/multi` - Get parallel reviews from both CLIs
+- Council review - Get consensus-based feedback from multiple models
 
-# Copy commands
-cp cc-reviewer/commands/*.md ~/.claude/commands/
-```
+**For regular reviews:** Just say "review" and Claude Code will use its native capabilities. These external tools are only invoked when explicitly requested.
+
+## Slash Commands
 
-Then use:
+After running `npx cc-reviewer-setup`, these commands are available:
 
 ```bash
 /codex                    # Review with Codex

package/commands/codex-xhigh.md

@@ -0,0 +1,54 @@
+# Codex XHigh
+
+Get a deep-thinking review from OpenAI Codex CLI with xhigh reasoning effort.
+
+## Arguments
+- `$ARGUMENTS` - Optional: focus area or custom instructions
+
+## Instructions
+
+Use the `codex_feedback` MCP tool with `reasoningEffort: "xhigh"` for deeper analysis.
+
+1. Determine what to review:
+   - If we just completed work, summarize the changes made
+   - If user provided context, use that
+   - Default: review the current working directory
+
+2. Call the `codex_feedback` tool with:
+   - `workingDir`: current working directory
+   - `ccOutput`: brief summary of recent changes or context
+   - `reasoningEffort`: "xhigh" (this is the key difference from /codex)
+   - `focus`: extracted from $ARGUMENTS if it's a known focus area
+   - `customInstructions`: $ARGUMENTS if it's custom text
+
+3. After receiving feedback - VALIDATE before accepting:
+
+   IMPORTANT: Do NOT blindly accept external feedback. You must:
+
+   a. **Verify file references exist**
+      - Check any mentioned file:line actually exists
+      - Flag hallucinated paths immediately
+
+   b. **Cross-check claims by reading code**
+      - Read the actual files mentioned
+      - Verify the issue described matches reality
+
+   c. **Mark your confidence level for each finding:**
+      - ✓✓ Verified (you checked the code yourself)
+      - ✓ Likely (plausible but not verified)
+      - ? Uncertain (needs more investigation)
+      - ✗ Rejected (you disagree after checking)
+
+   d. **Make YOUR recommendation**
+      - Don't just relay their findings
+      - Apply your own judgment
+      - You may disagree with external feedback
+
+4. Present synthesis:
+   - Show validated findings with confidence levels
+   - Highlight anything that looks like a hallucination
+   - Offer to incorporate only verified/likely suggestions
+
+Note: xhigh reasoning takes longer but provides deeper analysis.
+
+$ARGUMENTS

package/commands/codex.md

@@ -0,0 +1,87 @@
+# Codex Feedback
+
+Get a review from OpenAI Codex CLI, specialized in correctness and security.
+
+## Arguments
+- `$ARGUMENTS` - Optional: focus area or custom instructions
+
+## Codex Strengths
+- **Correctness**: Logic errors, edge cases, bugs
+- **Security**: Vulnerabilities, injection attacks
+- **Performance**: Efficiency analysis
+
+## Before Calling - PREPARE THE HANDOFF
+
+### 1. Summarize What You Did (Brief!)
+```
+"Added user registration with email validation and password hashing."
+```
+
+### 2. List Your Uncertainties
+What should Codex verify?
+
+```
+UNCERTAINTIES:
+- "Is the email regex sufficient for validation?"
+- "Is bcrypt properly configured for password security?"
+```
+
+### 3. Ask Specific Questions
+```
+QUESTIONS:
+- "Are there SQL injection vectors I missed?"
+- "Is the rate limiting on registration adequate?"
+```
+
+## Tool Invocation
+
+Call `codex_feedback` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "ccOutput": "<structured handoff - see below>",
+  "outputType": "analysis",
+  "focusAreas": ["<from $ARGUMENTS>"],
+  "reasoningEffort": "high"  // or "xhigh" for deeper analysis
+}
+```
+
+### Structure your ccOutput:
+
+```
+SUMMARY:
+<what you did, 1-3 sentences>
+
+UNCERTAINTIES (verify these):
+1. <your uncertainty>
+2. <another uncertainty>
+
+QUESTIONS:
+1. <specific question>
+
+PRIORITY FILES:
+- <file to focus on>
+```
+
+## After Receiving Review
+
+1. **Verify file references exist**
+   - Check mentioned file:line locations
+   - Flag any that don't exist
+
+2. **Cross-check findings**
+   - Read the actual code
+   - Confirm the issue exists
+
+3. **Mark confidence:**
+   - ✓✓ Verified by you
+   - ✓ Plausible, not verified
+   - ? Needs investigation
+   - ✗ Rejected
+
+4. **Apply judgment**
+   - You may disagree with findings
+   - Make YOUR recommendation
+
+$ARGUMENTS

package/commands/council.md

@@ -0,0 +1,107 @@
+# Council Review
+
+Get a Council Review with automatic consensus from multiple AI models.
+
+## Arguments
+- `$ARGUMENTS` - Optional: focus area or custom instructions
+
+## Before Calling - PREPARE THE HANDOFF
+
+The quality of review depends on what you share. Before calling the tool:
+
+### 1. Summarize What You Did (1-3 sentences)
+```
+Example: "Implemented JWT authentication for the /api/users endpoints.
+Added token validation middleware and refresh token rotation."
+```
+
+### 2. List Your Uncertainties (CRITICAL!)
+What are you unsure about? What do you want verified?
+
+```
+Example uncertainties:
+- "Is the token expiry handling correct for edge cases?"
+- "Does the refresh rotation prevent token replay attacks?"
+- "Should I validate the audience claim?"
+```
+
+### 3. Formulate Specific Questions
+What do you specifically want the reviewer to answer?
+
+```
+Example questions:
+- "Is the bcrypt cost factor (12) appropriate for this use case?"
+- "Does this break backwards compatibility with existing sessions?"
+```
+
+### 4. Note Key Decisions (Optional)
+Major choices you made that reviewer should evaluate:
+
+```
+Example: "Chose JWT over sessions because the API is stateless.
+Alternative was Redis-backed sessions but added infrastructure complexity."
+```
+
+## Tool Invocation
+
+Call `council_feedback` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "ccOutput": "<your brief summary + uncertainties + questions>",
+  "outputType": "analysis",
+  "focusAreas": ["<from $ARGUMENTS if applicable>"],
+  "customPrompt": "<any specific instructions>"
+}
+```
+
+### Format your ccOutput like this:
+
+```
+SUMMARY:
+<1-3 sentences of what you did>
+
+UNCERTAINTIES (please verify):
+1. <uncertainty 1>
+2. <uncertainty 2>
+
+QUESTIONS:
+1. <specific question 1>
+2. <specific question 2>
+
+KEY DECISIONS:
+- <decision>: <rationale>
+
+PRIORITY FILES:
+- path/to/critical/file.ts
+- path/to/another/file.ts
+```
+
+## After Receiving Review
+
+### Validate the Response
+
+1. **Check uncertainty responses**
+   - Did reviewer verify your uncertain areas?
+   - Do you agree with their assessment?
+
+2. **Check question answers**
+   - Were your questions answered?
+   - Is the reasoning sound?
+
+3. **Evaluate new findings**
+   - For each finding, verify the file/line exists
+   - Read the code yourself to confirm
+   - Mark your confidence:
+     - ✓✓✓ Consensus + you verified
+     - ✓✓ Multiple models agreed
+     - ✓ Single source, plausible
+     - ? Needs investigation
+     - ✗ Rejected after checking
+
+4. **Resolve conflicts**
+   - If models disagree, YOU decide
+   - Don't just pick majority - read the code
+
+$ARGUMENTS

package/commands/gemini.md

@@ -0,0 +1,91 @@
+# Gemini Feedback
+
+Get a review from Google Gemini CLI, specialized in architecture and large-scale analysis.
+
+## Arguments
+- `$ARGUMENTS` - Optional: focus area or custom instructions
+
+## Gemini Strengths
+- **Architecture**: Design patterns, code structure
+- **Large Context**: Can analyze entire codebases
+- **Maintainability**: Code clarity, complexity
+- **Scalability**: System design concerns
+
+## Before Calling - PREPARE THE HANDOFF
+
+### 1. Summarize What You Did (Brief!)
+```
+"Refactored the payment service to use the repository pattern,
+extracted common validation logic into a shared module."
+```
+
+### 2. List Your Uncertainties
+What should Gemini verify?
+
+```
+UNCERTAINTIES:
+- "Does the new abstraction layer add unnecessary complexity?"
+- "Is the module boundary in the right place?"
+```
+
+### 3. Ask Specific Questions
+```
+QUESTIONS:
+- "Should PaymentValidator be its own service or stay as a utility?"
+- "Is there a better pattern for the retry logic?"
+```
+
+## Tool Invocation
+
+Call `gemini_feedback` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "ccOutput": "<structured handoff - see below>",
+  "outputType": "analysis",
+  "focusAreas": ["<from $ARGUMENTS>"]
+}
+```
+
+### Structure your ccOutput:
+
+```
+SUMMARY:
+<what you did, 1-3 sentences>
+
+UNCERTAINTIES (verify these):
+1. <your uncertainty>
+2. <another uncertainty>
+
+QUESTIONS:
+1. <specific question>
+
+KEY DECISIONS:
+- <decision>: <rationale>
+
+PRIORITY FILES:
+- <file to focus on>
+```
+
+## After Receiving Review
+
+1. **Verify file references exist**
+   - Check mentioned file:line locations
+   - Flag any that don't exist
+
+2. **Cross-check findings**
+   - Read the actual code
+   - Confirm the issue exists
+
+3. **Mark confidence:**
+   - ✓✓ Verified by you
+   - ✓ Plausible, not verified
+   - ? Needs investigation
+   - ✗ Rejected
+
+4. **Apply judgment**
+   - You may disagree with findings
+   - Make YOUR recommendation
+
+$ARGUMENTS

package/commands/multi.md

@@ -0,0 +1,99 @@
+# Multi Feedback
+
+Get parallel reviews from both Codex and Gemini, raw output for manual synthesis.
+
+## Arguments
+- `$ARGUMENTS` - Optional: focus area or custom instructions
+
+## When to Use
+
+- `/multi` - Raw parallel reviews, YOU synthesize
+- `/council` - Automatic consensus with confidence scores
+
+Use `/multi` when you want full control over synthesis.
+
+## Before Calling - PREPARE THE HANDOFF
+
+### 1. Summarize What You Did (Brief!)
+```
+"Implemented caching layer for the product catalog API using Redis.
+Added cache invalidation on product updates."
+```
+
+### 2. List Your Uncertainties
+```
+UNCERTAINTIES:
+- "Is the cache TTL appropriate for this data?"
+- "Does the invalidation handle all update scenarios?"
+- "Is the Redis connection pooling configured correctly?"
+```
+
+### 3. Ask Specific Questions
+```
+QUESTIONS:
+- "Should I use write-through or write-behind caching?"
+- "Is there a race condition in the invalidation logic?"
+```
+
+## Tool Invocation
+
+Call `multi_feedback` with:
+
+```json
+{
+  "workingDir": "<current directory>",
+  "ccOutput": "<structured handoff>",
+  "outputType": "analysis",
+  "focusAreas": ["<from $ARGUMENTS>"]
+}
+```
+
+### Structure your ccOutput:
+
+```
+SUMMARY:
+<what you did, 1-3 sentences>
+
+UNCERTAINTIES (verify these):
+1. <uncertainty>
+2. <uncertainty>
+
+QUESTIONS:
+1. <question>
+
+PRIORITY FILES:
+- <file>
+```
+
+## After Receiving Review
+
+You will receive separate reviews from each model.
+
+### Synthesize Manually
+
+1. **Find agreements** (both models say same thing)
+   - Higher confidence
+   - Still verify yourself
+
+2. **Identify conflicts** (they disagree)
+   - Read the code
+   - YOU decide who's right
+
+3. **Note unique insights**
+   - Findings only one model found
+   - Evaluate on merit
+
+4. **Verify all findings**
+   - Check file/line references exist
+   - Read actual code
+   - Mark your confidence:
+     - ✓✓ Verified
+     - ✓ Plausible
+     - ? Investigate
+     - ✗ Rejected
+
+5. **Make YOUR recommendation**
+   - Don't just relay findings
+   - Apply your judgment
+
+$ARGUMENTS

package/dist/setup.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Setup script for cc-reviewer slash commands
+ *
+ * Copies the slash command files to ~/.claude/commands/
+ */
+export {};

package/dist/setup.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Setup script for cc-reviewer slash commands
+ *
+ * Copies the slash command files to ~/.claude/commands/
+ */
+import { existsSync, mkdirSync, copyFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function setup() {
+    const commandsSource = join(__dirname, '..', 'commands');
+    const commandsTarget = join(homedir(), '.claude', 'commands');
+    console.log('CC Reviewer - Setup Slash Commands\n');
+    // Check if source commands exist
+    if (!existsSync(commandsSource)) {
+        console.error('Error: Commands directory not found in package.');
+        console.error('Expected at:', commandsSource);
+        process.exit(1);
+    }
+    // Create target directory if it doesn't exist
+    if (!existsSync(commandsTarget)) {
+        console.log(`Creating ${commandsTarget}...`);
+        mkdirSync(commandsTarget, { recursive: true });
+    }
+    // Copy command files
+    const files = readdirSync(commandsSource).filter(f => f.endsWith('.md'));
+    if (files.length === 0) {
+        console.error('Error: No command files found.');
+        process.exit(1);
+    }
+    console.log('Installing slash commands:\n');
+    for (const file of files) {
+        const source = join(commandsSource, file);
+        const target = join(commandsTarget, file);
+        const commandName = file.replace('.md', '');
+        copyFileSync(source, target);
+        console.log(`  /${commandName} -> ${target}`);
+    }
+    console.log('\n✓ Done! Restart Claude Code to use the commands.\n');
+    console.log('Available commands:');
+    console.log('  /codex       - Review with OpenAI Codex');
+    console.log('  /codex-xhigh - Review with Codex (xhigh reasoning)');
+    console.log('  /gemini      - Review with Google Gemini');
+    console.log('  /multi       - Review with both Codex and Gemini');
+    console.log('  /council     - Council review with consensus\n');
+}
+setup();

package/dist/tools/feedback.js

@@ -351,7 +351,7 @@ Install at least one:
 export const TOOL_DEFINITIONS = {
     codex_feedback: {
         name: 'codex_feedback',
-        description: "Get Codex's review of Claude Code's work. Codex focuses on correctness, edge cases, and performance.",
+        description: "ONLY use when user explicitly requests '/codex' or 'review with codex'. Get external second-opinion from OpenAI Codex CLI. Codex focuses on correctness, edge cases, and performance. DO NOT use for general 'review' requests.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -396,7 +396,7 @@ export const TOOL_DEFINITIONS = {
     },
     gemini_feedback: {
         name: 'gemini_feedback',
-        description: "Get Gemini's review of Claude Code's work. Gemini focuses on design patterns, scalability, and tech debt.",
+        description: "ONLY use when user explicitly requests '/gemini' or 'review with gemini'. Get external second-opinion from Google Gemini CLI. Gemini focuses on design patterns, scalability, and tech debt. DO NOT use for general 'review' requests.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -436,7 +436,7 @@ export const TOOL_DEFINITIONS = {
     },
     multi_feedback: {
         name: 'multi_feedback',
-        description: "Get parallel reviews from all available AI CLIs (Codex and Gemini). Returns combined feedback for synthesis.",
+        description: "ONLY use when user explicitly requests '/multi' or 'review with both codex and gemini'. Get parallel second-opinions from both external CLIs (Codex and Gemini). Returns combined feedback for synthesis. DO NOT use for general 'review' requests.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -476,7 +476,7 @@ export const TOOL_DEFINITIONS = {
     },
     council_feedback: {
         name: 'council_feedback',
-        description: "Get a Council Review with automatic consensus calculation. Runs multiple models in parallel, detects agreements/conflicts, and synthesizes findings with confidence scores.",
+        description: "ONLY use when user explicitly requests council review or consensus-based feedback. Get external second-opinions from multiple CLIs with automatic consensus calculation. Runs Codex and Gemini in parallel, detects agreements/conflicts, and synthesizes findings with confidence scores. DO NOT use for general 'review' requests.",
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "cc-reviewer",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "MCP server for Claude Code - Get second-opinion feedback from Codex/Gemini CLIs",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "cc-reviewer": "dist/index.js"
+    "cc-reviewer": "dist/index.js",
+    "cc-reviewer-setup": "dist/setup.js"
   },
   "files": [
     "dist/**/*",
+    "commands/**/*",
     "README.md",
     "LICENSE"
   ],