totool-council 0.1.1

A council of 3 AI critics that must reach consensus on code quality decisions

Code Review Council

A CLI tool that uses a council of 3 AI critics to reach consensus on code quality decisions.

Overview

Code Review Council (ttc) is a command-line tool that employs three specialized AI critics to review your code:

Critic	Focus
🔒 Security Specialist	Vulnerabilities, secrets, security best practices
⚡ Performance Engineer	Efficiency, resource usage, scalability
📝 Clean Code Advocate	Maintainability, readability, code organization

The three critics must reach consensus before approving code, ensuring thorough and balanced reviews.

Exit Codes

• 0 = ✅ Approved (all critics agree)
• 1 = ⚠️ Needs Work (minor issues, some approval)
• 2 = ❌ Rejected (significant issues)

Features

• Multi-AI Provider Support - DeepSeek, Mistral, Kimi, MiniMax, Claude, and any provider with chat completions API
• Consensus-Based Decisions - 3-council system requires majority approval
• Security-First Design - Built-in secret scanning with 50+ patterns
• Flexible Review Strategies - Hierarchical, parallel, chunked reviews
• Customizable Critics - Default brutal prompts with extensive customization options
• Rich Output - Color-coded terminal output with progress indicators
• CI/CD Integration - Exit codes for automated pipelines

Quick Start

Installation

# Install from source
pip install -e .

# Or with optional async support
pip install -e ".[async]"

# Or with all features
pip install -e ".[all]"

Configuration

Create ~/.ttc/config.json with your provider configuration:

{
  "active_provider": "deepseek",
  "providers": [
    {
      "name": "deepseek",
      "model": "deepseek-chat",
      "base_url": "https://api.deepseek.com",
      "api_key": "your-deepseek-key"
    }
  ]
}

Custom Providers: You can add any AI provider with a chat completions API by specifying the base_url, model, and api_key. Works with Kimi, MiniMax, Claude, and many others. See QUICKSTART.md for details.

Basic Usage

# Review a single file
ttc review myfile.py

# Review entire project
ttc review /path/to/project

# Switch providers by editing config.json (set active_provider)
# Then run:
ttc review src/

# Streaming mode for large projects
ttc review --streaming large-project/

# Custom critics directory
ttc review --critics-dir ./my-critics src/

Documentation

• Quick Start Guide - Get up and running in minutes
• Usage Guide - Detailed usage instructions and examples
• Critics README - Customizing AI critics

How It Works

┌─────────────────┐
│   Your Code     │
└────────┬────────┘
         │
    ┌────▼─────┐
    │  Council │
    └────┬─────┘
         │
    ┌────┴────┬──────────┬──────────┐
    │         │          │          │
┌───▼───┐ ┌──▼─────┐ ┌──▼───────┐ ┌▼────────┐
│Security│ │Perform.│ │Clean Code│ │Consensus│
│Critic  │ │Critic  │ │Critic    │ │Builder  │
└───┬───┘ └──┬─────┘ └──┬───────┘ └┬────────┘
    │        │          │          │
    └────────┴──────────┴──────────┘
                    │
            ┌───────▼────────┐
            │ Final Decision │
            └────────────────┘

Security Features

• Secret Scanning - 50+ patterns including AWS keys, GitHub tokens, API keys
• SSL Validation - Certificate verification for all API calls
• TOCTOU Prevention - Time-of-check to time-of-use attack protection
• Secure Config - API keys stored in user directory, never committed

AI Providers

I've tested with DeepSeek, ZAI, Mistral, Claude, and OpenAI. Other providers should work as long as they have a standard chat completions API.

To add a provider, specify the base_url, model, and api_key in your config:

{
  "active_provider": "your-provider",
  "providers": [
    {
      "name": "your-provider",
      "model": "model-name",
      "base_url": "https://api.provider.com",
      "api_key": "your-api-key"
    }
  ]
}

Development

Running Tests

pytest

Project Structure

totool/
├── council/                # Main Python package
│   ├── critics/           # AI critic configurations
│   ├── data/              # Configuration data
│   └── ...
├── tests/                 # Test suite
├── docs/                  # Documentation
└── pyproject.toml         # Package configuration

See .claude/CLAUDE.md for detailed architecture and development reference.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Links

• GitHub Issues
• Documentation
• Quick Start
• Usage Guide