⚔️ Clash

Two AI models. One synthesized answer.

A terminal-first assistant that queries Codex and Gemini in parallel, then merges their responses into a single, structured output.

Installation • Quick Start • Commands • How It Works • Requirements

---

✨ Features

• 🧠 Multi-Agent Debate — Queries Codex and Gemini with opposing stances (affirmative/negative)
• 🔄 Tit-for-Tat Rebuttals — Each model critiques the other's proposal for better coverage
• ⚖️ Smart Judge — Rules-based judge with rubric scoring detects consensus for early stopping
• 🔀 Extractive Synthesis — Merges proposals + debate insights (no third model needed)
• 📋 Planning Mode — Turn ideas into implementation plans with assumptions, steps, and risks
• 🔍 Review Mode — Get code reviews of your git diff with must-fix/should-fix categorization
• ⚡ Read-Only — Never modifies your code; pure analysis and planning

---

Installation

Prerequisites

• Python 3.9 or higher
• uv package manager (recommended)
• Codex CLI installed and authenticated
• Gemini CLI installed and authenticated

Install uv (if not already installed)

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Clash

# Clone the repository
git clone https://github.com/your-org/clash.git
cd clash

# Create virtual environment and install with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Why uv? uv is a blazing-fast Python package installer and resolver written in Rust. It provides faster installs, better dependency resolution, and simplified environment management compared to traditional pip.

---

Quick Start

# Launch the REPL (no activation needed!)
uv run clash

Alternative: Activate the virtual environment first, then run clash:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate
clash

 ██████╗██╗      █████╗ ███████╗██╗  ██╗
██╔════╝██║     ██╔══██╗██╔════╝██║  ██║
██║     ██║     ███████║███████╗███████║
██║     ██║     ██╔══██║╚════██║██╔══██║
╚██████╗███████╗██║  ██║███████║██║  ██║
 ╚═════╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
  Two models. One answer.

  Commands: /plan /review /help /exit

> /plan
(plan) > Build a REST API for user authentication

# → Both models propose → Synthesized plan appears

> /review
(review) > Focus on error handling

# → Reads git diff → Synthesized review appears

---

Commands

Command	Description
/plan	Switch to planning mode — turns prompts into implementation plans
/review	Switch to review mode — reviews your current git diff
/help	Show available commands
/exit	Exit the REPL

---

How It Works

Clash uses a MAD-lite (Multi-Agent Debate) architecture:

┌─────────────────────── Round 0: Proposals ───────────────────────┐
│                                                                  │
│   ┌─────────────┐     ┌─────────────┐                            │
│   │   Codex     │     │   Gemini    │                            │
│   │  (affirm)   │     │  (negate)   │                            │
│   └──────┬──────┘     └──────┬──────┘                            │
└──────────┼──────────────────┼────────────────────────────────────┘
           │                  │
           │    ───cross───   │
           │                  │
┌──────────┴──────────────────┴────────────────────────────────────┐
│                      Round 1: Rebuttals                          │
│                                                                  │
│   ┌─────────────┐     ┌─────────────┐                            │
│   │   Codex     │     │   Gemini    │                            │
│   │  rebuts B   │     │  rebuts A   │                            │
│   └──────┬──────┘     └──────┬──────┘                            │
└──────────┼──────────────────┼────────────────────────────────────┘
           │                  │
           └────────┬─────────┘
                    ▼
            ┌───────────┐
            │   Judge   │  ← rubric scoring, early stop detection
            └─────┬─────┘
                  ▼
          ┌───────────────┐
          │  Synthesizer  │ ← extractive merge of proposals + insights
          └───────┬───────┘
                  ▼
            Final Answer

1. Round 0: Your prompt goes to Codex (affirmative) and Gemini (negative) in parallel
2. Round 1: Each model critiques the other’s proposal (capped at 3 issues + 1 improvement)
3. Judge: Rules-based scoring detects if consensus or clear winner emerged → early stop
4. Synthesize: Merges best proposal with high-signal debate insights

---

Documentation

• Developer Guide — Architecture, extension points, and internals

---

License

Apache 2.0