council-cli 0.1.1
Two AI agents brainstorm, debate, and research together
Requires Python: >=3.8
Keywords: ai, brainstorm, debate, claude, agents

# council-cli

Two AI agents brainstorm, debate, and research together using Claude Code.

Council launches two Claude Code instances that analyze your codebase in alternating rounds, tagging their points with AGREE/DISAGREE/REFINE to drive toward consensus.

## Installation

```bash
pip install council-cli
```

Or install from source:

```bash
git clone https://github.com/david/council-cli
cd council-cli
pip install -e .
```

## Prerequisites

- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`npm install -g @anthropic-ai/claude-code`)

## Usage

### Standard Mode (formal rounds)

```bash
# 5-round council on error handling in current directory
council "Review error handling"

# 3 rounds on auth security
council -r 3 "Is the auth system secure?"

# Analyze a specific project, save to custom file
council -d ./my-project -o report.md "Code quality review"

# Verbose mode — see prompts being sent
council -v "Performance bottlenecks"

# Dry run — validate arguments without calling Claude
council --dry-run "Test topic"
```

### Live Brainstorm Mode (`--live`)

Short, conversational back-and-forth exchanges instead of formal rounds. Feels like two engineers at a whiteboard.

```bash
# Default 10 exchanges
council --live "Should we refactor the auth system?"

# 20 exchanges for a deeper brainstorm
council --live --exchanges 20 "Performance vs readability"
```

### Research Mode (`--research`)

Agents do deep web research and lateral thinking before brainstorming grounded in real data.

```bash
# Research mode with default 10 brainstorm exchanges
council --research "AI code review tools market"

# Research mode with 6 brainstorm exchanges
council --research --exchanges 6 "Developer productivity tools"
```

## Flags

| Flag | Description |
|------|-------------|
| `topic` | The analysis topic or question (required) |
| `-r, --rounds N` | Number of analysis rounds in standard mode (default: 5) |
| `-d, --dir DIR` | Working directory for analysis (default: `.`) |
| `-o, --output FILE` | Output file path for transcript (default: `council_transcript.md`) |
| `-v, --verbose` | Enable verbose output |
| `--live` | Live brainstorm mode |
| `--research` | Research mode (web search + lateral thinking + brainstorm) |
| `--exchanges N` | Number of exchanges in `--live`/`--research` mode (default: 10) |
| `--dry-run` | Validate arguments without running |

## How It Works

1. **Standard Mode**: Agent-Alpha analyzes the topic, Agent-Beta critiques, they go back and forth for N rounds, then produce a consensus.
2. **Live Mode**: Agents exchange short messages like a real conversation, then summarize key takeaways.
3. **Research Mode**: Alpha does deep web research, Beta does lateral thinking on the findings, then both brainstorm grounded in real data.

## Output

Council saves a markdown transcript to `council_transcript.md` (or your `-o` path) with metadata, round-by-round discussion, and final conclusions.

## License

MIT