Warroom

Local multi-agent debate engine for strategy derivation.

Warroom orchestrates structured, multi-round debates between specialized AI expert agents using local CLI tools (Claude Code, Gemini CLI, Codex CLI) — no API keys required. Each expert agent analyzes a problem from its unique perspective, critiques other agents' proposals, and iteratively refines strategies through up to 10 rounds of structured discussion.

한국어 README

How It Works

Seed Data → Expert Agents → Multi-Round Debate → Strategy Report
                  ↑                   ↓
              CLI Rotation        Synthesis
          (Claude/Gemini/Codex)

Round 1 — Independent Analysis: Each expert analyzes the seed data from their specialist perspective.
Round 2 — Mutual Critique: Agents review and challenge each other's proposals.
Rounds 3-9 — Deepening: Each round focuses on a topic-specific analytical lens (configurable per topic via lenses.yaml).
Round 10 — Final Convergence: Agents deliver definitive positions with ratings and consensus identification.
Synthesis: A final LLM call produces a structured strategy report with action plans and risk matrices.

CLI Rotation

A key design principle: the same expert agent is powered by a different LLM each round. This prevents echo chambers and ensures genuine diversity of thought. For example, the "Claude Expert" might be powered by Gemini CLI in Round 1, then Claude Code in Round 2.

Built-in Topics

AEO/GEO Strategy (`aeo-geo`)

AI Engine Optimization / Generative Engine Optimization — the default topic combining 9 agents (6 platform + 3 strategy experts) to optimize content visibility across AI-powered search engines.

Platform Experts (agents/platforms/):

Agent	Specialization
ChatGPT Expert	OpenAI search integration, content surfacing patterns
Claude Expert	Anthropic Claude's training data preferences, depth-first content
Gemini Expert	Google Gemini's search-grounded responses, SGE optimization
Perplexity Expert	Perplexity's citation-heavy, source-ranking behavior
Naver Expert	Naver CUE: (Korean AI search), Korean-language optimization
China LLM Expert	Baidu ERNIE, Alibaba Tongyi, Chinese market dynamics

Strategy Experts (agents/strategy/):

Agent	Role
Content Architect	Content structure, schema markup, cross-platform content strategy
Competitor Analyst	Competitive intelligence, market positioning, gap analysis
Devil's Advocate	Stress-testing proposals, challenging assumptions, surfacing risks

Code Review (`code-review`)

Multi-perspective code review with 5 specialized reviewers that analyze PRs and diffs through different lenses.

Reviewers (agents/code-review/):

Agent	Focus
Security Reviewer	OWASP Top 10, auth/authz, input validation, dependency CVEs
Architecture Reviewer	SOLID, coupling/cohesion, API contracts, design patterns
Performance Reviewer	Algorithmic complexity, N+1 queries, memory, concurrency
Test Reviewer	Coverage gaps, edge cases, assertion quality, test design
Devil's Advocate	Challenges over-engineering, questions abstraction value, defends simplicity

Code Review Lenses (rounds 3-9):

Round	Lens
3	Code Quality & Readability
4	Security & Risk Analysis
5	Architecture & Design Impact
6	Testing & Edge Cases
7	Performance & Scalability
8	Maintainability & Evolution
9	Final Verdict (ship / revise / block)

Quick Start

Prerequisites

Python 3.12+
At least one CLI agent installed and on PATH:
- Claude Code (claude)
- Gemini CLI (gemini)
- Codex CLI (codex) — optional

Installation

git clone https://github.com/first-fluke/warroom.git
cd warroom
python -m venv .venv && source .venv/bin/activate
pip install -e .

Run a Debate

# AEO/GEO strategy debate
warroom run --topic aeo-geo --input inputs/sample-probe-result.json

# Code review debate
warroom run --topic code-review --input inputs/sample-code-review.json

# Specify rounds and report language
warroom run --topic code-review --input inputs/sample-code-review.json \
  --rounds 5 --lang ko

# Add extra context
warroom run --topic aeo-geo --input inputs/sample-probe-result.json \
  --context "Focus on US market entry strategy"

# Run without seed data (context-only mode)
warroom run --topic aeo-geo --context "How to optimize for AI-powered search engines"

Report Language

The --lang option controls the language of the final strategy report:

# English (default)
warroom run --topic code-review --input inputs/sample-code-review.json --lang en

# Korean
warroom run --topic code-review --input inputs/sample-code-review.json --lang ko

# Japanese
warroom run --topic aeo-geo --input inputs/sample-probe-result.json --lang ja

# Chinese
warroom run --topic aeo-geo --input inputs/sample-probe-result.json --lang zh

The report command also supports --lang:

warroom report outputs/debate-20260318-141950.json --lang ko

Other Commands

# List available topics and agent counts
warroom topics

# Re-generate a strategy report from a saved session
warroom report outputs/debate-20260318-141950.json

# Use a specific LLM and language for report generation
warroom report outputs/debate-20260318-141950.json --agent gemini --lang ko

Input Format

Input is a JSON file passed via --input. The format depends on the topic.

AEO/GEO Input (`inputs/sample-probe-result.json`)

{
  "client": "Example Corp",
  "industry": "K-Beauty / Skincare",
  "target_markets": ["Korea", "US", "Japan"],
  "probe_results": {
    "chatgpt": {
      "query": "best Korean skincare brands for sensitive skin",
      "mentioned": false,
      "competitors_mentioned": ["Laneige", "COSRX", "Innisfree"],
      "position": null
    },
    "gemini": {
      "query": "best Korean skincare brands for sensitive skin",
      "mentioned": true,
      "competitors_mentioned": ["Laneige", "COSRX"],
      "position": 5
    }
  },
  "current_content": {
    "website": "https://example-corp.com",
    "blog_posts": 45,
    "structured_data": false,
    "languages": ["ko", "en"]
  }
}

Code Review Input (`inputs/sample-code-review.json`)

{
  "pr_title": "Add rate limiting middleware to API gateway",
  "pr_description": "Implements token-bucket rate limiting with Redis backend.",
  "repository": "acme/api-gateway",
  "language": "Python",
  "framework": "FastAPI",
  "files_changed": 5,
  "diff": "diff --git a/src/middleware/rate_limiter.py ...",
  "context": {
    "related_issues": ["#142", "#198"],
    "base_branch": "main",
    "author_notes": "Looking for feedback on the Redis integration approach."
  }
}

Output

Warroom produces two outputs per session in the outputs/ directory:

1. Debate Session (`debate-YYYYMMDD-HHMMSS.json`)

Full record of every round — which agent said what, which LLM powered them, and timestamps.

2. Strategy Report (`report-YYYYMMDD-HHMMSS.md`)

A structured markdown report containing:

Executive Summary
Consensus Strategies (agreed by majority of agents)
Contested Strategies (with both sides of the argument)
Prioritized Action Plan (table with impact, risk, and ownership)
Risk Matrix (likelihood, impact, mitigation)
Key Metrics to Track

Adding a New Topic

Warroom is topic-agnostic. To create a new debate topic:

Create a directory under agents/:
```
mkdir agents/my-topic
```

Add expert agent files (one .md per agent):

---
cli: claude
---
# Expert Role Name

You are a specialist in [domain].

## Your Expertise
- Point 1
- Point 2

## Your Perspective
Description of this agent's analytical lens.

(Optional) Add a lenses.yaml for topic-specific deepening lenses:

3:
  name: "Lens Name"
  tasks:
    - "Task description 1"
    - "Task description 2"
4:
  name: "Another Lens"
  tasks:
    - "Task description"

If omitted, the default AEO/GEO lenses are used.

Run the debate:

warroom run --topic my-topic --input your-data.json

Agent File Format

Frontmatter (optional): cli: claude|gemini|codex sets the starting CLI. If omitted, CLIs are assigned via round-robin.
First # heading: Used as the agent's display name/role.
Body: The system prompt defining the agent's expertise and perspective.

Architecture

warroom/
├── agents/                    # Expert agent prompt files
│   ├── platforms/             #   AEO/GEO platform experts
│   │   ├── chatgpt-expert.md
│   │   ├── claude-expert.md
│   │   ├── gemini-expert.md
│   │   ├── perplexity-expert.md
│   │   ├── naver-expert.md
│   │   └── china-llm-expert.md
│   ├── strategy/              #   AEO/GEO strategy experts
│   │   ├── content-architect.md
│   │   ├── competitor-analyst.md
│   │   └── devils-advocate.md
│   └── code-review/           #   Code review experts
│       ├── lenses.yaml        #     Topic-specific round lenses
│       ├── security-reviewer.md
│       ├── architecture-reviewer.md
│       ├── performance-reviewer.md
│       ├── test-reviewer.md
│       └── devils-advocate.md
├── src/
│   ├── cli.py                 # CLI entry point (Click)
│   ├── debate/
│   │   ├── orchestrator.py    # Debate engine: rounds, CLI rotation, lenses
│   │   └── synthesizer.py     # Final report generation + language support
│   └── memory/                # File-based long-term memory (future)
├── inputs/                    # Seed data files
│   ├── sample-probe-result.json
│   └── sample-code-review.json
├── outputs/                   # Generated debate sessions & reports
├── tests/                     # Test suite
├── pyproject.toml
└── .env.example

Configuration

Copy .env.example to .env to customize:

cp .env.example .env

Variable	Default	Description
`CLAUDE_CLI`	`claude`	Path to Claude Code CLI
`GEMINI_CLI`	`gemini`	Path to Gemini CLI
`CODEX_CLI`	`codex`	Path to Codex CLI
`DEFAULT_AGENT`	`claude`	Default agent for synthesis
`WARROOM_API_PORT`	`9100`	API server port (optional)
`WARROOM_FRONTEND_PORT`	`4100`	Frontend port (optional)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run linter
ruff check src/ tests/

# Run tests
pytest -v

# Run with API server (optional)
pip install -e ".[api]"

License

MIT License - see LICENSE for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Warroom

How It Works

CLI Rotation

Built-in Topics

AEO/GEO Strategy (`aeo-geo`)

Code Review (`code-review`)

Quick Start

Prerequisites

Installation

Run a Debate

Report Language

Other Commands

Input Format

AEO/GEO Input (`inputs/sample-probe-result.json`)

Code Review Input (`inputs/sample-code-review.json`)

Output

1. Debate Session (`debate-YYYYMMDD-HHMMSS.json`)

2. Strategy Report (`report-YYYYMMDD-HHMMSS.md`)

Adding a New Topic

Agent File Format

Architecture

Configuration

Development

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
agents		agents
inputs		inputs
outputs		outputs
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Warroom

How It Works

CLI Rotation

Built-in Topics

AEO/GEO Strategy (aeo-geo)

Code Review (code-review)

Quick Start

Prerequisites

Installation

Run a Debate

Report Language

Other Commands

Input Format

AEO/GEO Input (inputs/sample-probe-result.json)

Code Review Input (inputs/sample-code-review.json)

Output

1. Debate Session (debate-YYYYMMDD-HHMMSS.json)

2. Strategy Report (report-YYYYMMDD-HHMMSS.md)

Adding a New Topic

Agent File Format

Architecture

Configuration

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

AEO/GEO Strategy (`aeo-geo`)

Code Review (`code-review`)

AEO/GEO Input (`inputs/sample-probe-result.json`)

Code Review Input (`inputs/sample-code-review.json`)

1. Debate Session (`debate-YYYYMMDD-HHMMSS.json`)

2. Strategy Report (`report-YYYYMMDD-HHMMSS.md`)

Packages