totool-council 0.1.4
A council of 3 AI critics that must reach consensus on code quality decisions
License: MIT
Requires Python: >=3.7
Keywords: code-review, ai, cli, development-tools

# Code Review Council

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

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)](pyproject.toml)

## 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

```bash
# 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:

```json
{
  "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](docs/QUICKSTART.md#custom-ai-providers) for details.

### Basic Usage

```bash
# 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](docs/QUICKSTART.md)** - Get up and running in minutes
- **[Usage Guide](docs/USAGE.md)** - Detailed usage instructions and examples
- **[Critics README](council/critics/README.md)** - 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:

```json
{
  "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

```bash
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](.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](LICENSE) for details.

## Links

- [GitHub Issues](https://github.com/yourusername/totool/issues)
- [Documentation](docs/)
- [Quick Start](docs/QUICKSTART.md)
- [Usage Guide](docs/USAGE.md)