⚔️ ai-battle

Structured roundtable discussions among multiple AI Agents

Auto-managed rounds · Consensus detection · Full session recording

中文 · NPM · Issues · PRs · License

---

Table of Contents

• Features
• Quick Start
• Installation
• Prerequisites
• Usage
• Examples
• How It Works
• Built-in Agents
• Output Structure
• Extend Agent
• Environment Variables
• Contributing
• License

✨ Features

Feature	Description
🤖 Multi-Agent Roundtable	Mix and match Claude / Codex / Gemini freely
🔁 Self-Debate	Same agent can take multiple seats (e.g. gemini,gemini)
🔨 Referee Mode	Independent referee summarizes each round, detects consensus, generates final report
👁️ God Mode	Inject supplementary instructions after each round to steer the discussion
💾 Session Recording	Saves raw Agent CLI output (stream-json / json / raw)
🔄 Resume Support	Automatically resumes from the last round after interruption
🔌 Extensible	Implement 3 functions + register to add a new agent

🚀 Quick Start

# Create a discussion directory
mkdir my-topic && cd my-topic

# Define the topic
echo "Microservices vs Monolith: pros and cons?" > problem.md

# Start the discussion (auto-fetches latest version)
npx ai-battle --agents claude,gemini --rounds 8

📦 Installation

Recommended: No install needed, use npx directly

npx ai-battle --agents claude,gemini --rounds 5

npx fetches the latest version automatically — no manual updates required.

Global install:

npm install -g ai-battle

Prerequisites

• bash 4+
• jq
• At least 2 Agent CLI tools: claude / codex / gemini

📖 Usage

ai-battle [options]
ai-battle help

Option	Description	Default
--agents, -a <a1,a2>	Select participating agents (supports same-type)	claude,codex
--rounds, -r <N>	Max discussion rounds	10
--god, -g	Enable god mode (inject info after each round)	—
--referee [agent]	Enable referee mode (per-round summary + SUMMARY.md)	—

💡 Examples

# Same-type agent self-debate
ai-battle --agents gemini,gemini

# Three-way roundtable
ai-battle --agents claude,codex,gemini --rounds 5

# Referee mode
ai-battle --agents claude,codex,gemini --referee --rounds 5

# Specify claude as referee
ai-battle --agents codex,gemini --referee claude --rounds 5

# God mode + Referee
ai-battle --agents claude,codex --referee --god

🔄 How It Works

sequenceDiagram
    participant U as 👤 User
    participant S as 📜 ai-battle
    participant A as 🤖 Agent A
    participant B as 🤖 Agent B
    participant R as 🔨 Referee

    U->>S: ai-battle --agents A,B --referee

    rect rgb(40, 40, 60)
        Note over S: Phase 1: Initialize
        S->>S: Load .env / Check problem.md
        S->>A: check_A() availability
        S->>B: check_B() availability
    end

    rect rgb(30, 50, 40)
        Note over S: Round 1: Concurrent independent thinking
        par
            S->>A: call_A(problem)
            A-->>S: Response A
        and
            S->>B: call_B(problem)
            B-->>S: Response B
        end
    end

    rect rgb(40, 40, 60)
        Note over S: Round 2+: Sequential interaction
        loop Each agent takes turn
            S->>A: call_A(B's last response)
            A-->>S: Response A
            S->>B: call_B(A's latest response)
            B-->>S: Response B
        end

        opt --referee mode
            S->>R: call_referee(all responses)
            R-->>S: Summary / CONSENSUS verdict
        end

        opt --god mode
            S->>U: Enter supplementary info
            U-->>S: God mode injection
        end
    end

    alt Consensus reached
        S->>S: Save consensus.md
        opt Referee mode
            S->>R: generate_final_summary()
            R-->>S: SUMMARY.md
        end
        S->>U: 🎉 Consensus reached!
    else No consensus
        S->>U: Add more rounds?
    end

Loading

🤖 Built-in Agents

Agent	Backend	Check Command
claude	Claude CLI	claude -p "hello"
codex	Codex CLI	codex exec "hello"
gemini	Gemini CLI	gemini -p "hello"

📁 Output Structure

my-topic/
├── problem.md                    # Discussion topic (user-created)
├── referee.md                    # Custom referee prompt (optional)
├── SUMMARY.md                    # Final summary (generated by referee)
├── .env                          # Environment variables (auto-loaded)
└── .ai-battle/                   # All runtime artifacts
    ├── rounds/                   # Per-round discussion records
    │   ├── round_1_claude.md
    │   ├── round_1_gemini.md
    │   ├── referee_round_2.md    # Referee summary (--referee)
    │   └── god_round_1.md        # God mode injection (--god)
    ├── sessions/                 # Raw Agent CLI output
    ├── agents/                   # Agent instruction files
    ├── consensus.md              # Consensus conclusion (if reached)
    ├── config.json               # Session config
    └── battle.log                # Full log (tail -f to watch live)

🔌 Extend Agent

Implement 3 functions and register:

# 1. Implement functions
check_myagent()          { ... }  # Availability check, return 0/1
call_myagent()           { ... }  # Call agent: $1=system_prompt $2=user_msg $3=session_tag
generate_myagent_md()    { ... }  # Generate instruction file: $1=max_rounds $2=problem

# 2. Register
register_agent "myagent"

🔑 Environment Variables

Claude

Variable	Description
ANTHROPIC_BASE_URL	API endpoint
ANTHROPIC_AUTH_TOKEN	Auth token
ANTHROPIC_DEFAULT_SONNET_MODEL	Model name
API_TIMEOUT_MS	Timeout (ms)

Codex

Variable	Description	Default
CODEX_MODEL	Model name	gpt-5.3-codex

Gemini

Variable	Description
GEMINI_API_KEY	API key

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT © Alfons