Code Council

One AI can miss things. A council of AIs catches more.

View Documentation | npm

Code Council runs your code through multiple AI models simultaneously, then shows you where they agree, where they disagree, and what only one model caught.

Example Output

## Consensus Analysis

### Unanimous (All 4 models agree) - High Confidence

**Critical: SQL Injection Vulnerability**
Location: src/api/users.ts:42

The user input is directly interpolated into the SQL query without sanitization.
Use parameterized queries instead.

---

### Majority (3 of 4 models) - Moderate Confidence

**High: Missing Input Validation**
Location: src/api/users.ts:38

The userId parameter is used without validation. Add type checking.

---

### Disagreement - Your Judgment Needed

**Session Token Expiration**
Location: src/api/auth.ts:28

- Kimi K2.5: "Tokens should expire after 24 hours"
- DeepSeek V3.2: "Current 7-day expiration is reasonable for this use case"
- Minimax M2.1: "No issue found"

---

### Single Model Finding - Worth Checking

**Low: Magic Number**
Location: src/utils/pagination.ts:12
Found by: GLM 4.7

The value 20 should be extracted to a named constant.

Why Multiple Models?

Different AI models have different strengths:

• One model might miss a security issue another catches
• Unanimous findings are almost certainly real problems
• Disagreements highlight where you should look closer
• Single-model findings might be noise, or might be the one model that saw something others missed

Think of it as getting 4 senior engineers to review your code at once.

Quick Start

MCP Server (Claude Desktop, Cursor, etc.)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "code-council": {
      "command": "npx",
      "args": ["-y", "@klitchevo/code-council"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Get your API key at OpenRouter.

That's it. Ask Claude: "Use review_code to check this function: [paste code]"

CLI (GitHub Actions, CI/CD)

Run reviews directly from command line:

# Review git changes
npx @klitchevo/code-council review git --review-type diff

# Review with inline PR comments format (for GitHub Actions)
npx @klitchevo/code-council review git --review-type diff --format pr-comments

# Review code from stdin
echo "function foo() {}" | npx @klitchevo/code-council review code

# Review with custom models
npx @klitchevo/code-council review git --models "anthropic/claude-sonnet-4,openai/gpt-4o"

# Show help
npx @klitchevo/code-council review --help

More setup options: See Configuration Guide for Cursor, VS Code, custom models, and advanced options.

GitHub Actions

Automatically review PRs with multiple AI models. Findings appear as inline comments on the exact lines of code. Code fixes use GitHub's suggestion syntax for one-click apply. Re-runs automatically clean up old comments.

Quick Setup

Generate the workflow file automatically:

npx @klitchevo/code-council setup workflow

This creates .github/workflows/code-council-review.yml with inline PR comments enabled.

Options:

• --simple - Use markdown format instead of inline comments
• --force - Overwrite existing workflow file

Manual Setup

Or create the workflow manually:

name: Code Council Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run Code Council Review
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: |
          npx @klitchevo/code-council review git \
            --review-type diff \
            --format pr-comments \
            > review.json

      - name: Post Review
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews \
            --method POST \
            --input review.json

Add OPENROUTER_API_KEY to your repository secrets (Settings > Secrets > Actions).

Use Cases

| Scenario | Tool | What You Get | |----------|------|--------------| | About to merge a PR | review_git_changes | Multi-model review of your diff | | Automated PR reviews | CLI review git | Multi-model review in GitHub Actions | | Planning a refactor | review_plan | Catch design issues before coding | | Reviewing React components | review_frontend | Accessibility + performance + UX focus | | Securing an API endpoint | review_backend | Security + architecture analysis | | Want deeper discussion | discuss_with_council | Multi-turn conversation with context | | Audit entire codebase | tps_audit | Flow, waste, bottlenecks analysis |

Full tool reference: See Tools Reference for all parameters and examples.

Reading the Results

Code Council shows confidence levels for each finding:

| Level | Meaning | Action | |-------|---------|--------| | Unanimous | All models agree | High confidence - fix this | | Majority | Most models agree | Likely valid - investigate | | Disagreement | Models conflict | Your judgment needed | | Single | One model found this | Worth checking |

Configuration

Code Council works out of the box with sensible defaults. For customization:

• Configuration Guide - MCP client setup, config files, environment variables
• Model Selection - Choose models, pricing, performance tradeoffs
• Tools Reference - Detailed tool parameters and examples

Custom Models Example

{
  "env": {
    "OPENROUTER_API_KEY": "your-api-key",
    "CODE_REVIEW_MODELS": ["anthropic/claude-sonnet-4.5", "openai/gpt-4o"]
  }
}

Cost

Default models are chosen for cost-effectiveness (~$0.01-0.05 per review).

Swap in Claude/GPT-4 for higher quality at higher cost (~$0.10-0.30 per review).

See Model Selection Guide for pricing details and optimization tips.

Requirements

• Node.js >= 18.0.0
• OpenRouter API key
• MCP-compatible client (Claude Desktop, Cursor, etc.)

Troubleshooting

"OPENROUTER_API_KEY environment variable is required" Add the API key to the env section of your MCP client configuration.

Reviews are slow This is expected when using multiple models. Consider using fewer models or faster models like Gemini Flash.

Models returning errors Check your OpenRouter credits and model availability at status.openrouter.ai.

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT

Links

• Documentation - Full docs and examples
• OpenRouter - Multi-model AI API
• Model Context Protocol - MCP specification
• Claude Desktop - MCP-compatible AI assistant