Claude Storm

A dual-agent brainstorming system that orchestrates two Claude Code CLI instances in strict alternating turns. Each agent maintains a persistent Claude session.

Try it now (no install needed):

uvx --from claude-storm storm start "Design a REST API for a todo app"

Prerequisites

• Claude Code CLI — must be installed and authenticated (claude command available on your $PATH). See the Claude Code docs for setup instructions.
• Python 3.11+

API usage: Claude Storm spawns Claude Code subprocesses — each agent turn is an API call billed through your Claude Code authentication (Anthropic API key or Claude Pro/Max subscription). Agents often finish early via consensus, so a session with --max-turns 20 typically uses fewer than 40 calls, plus a few more for deliverable compilation at the end.

Installation

# Run without installing (recommended for trying it out)
uvx --from claude-storm storm start "your topic"

# Install globally
pip install claude-storm

# Or with pipx
pipx install claude-storm

Once installed, the storm command is available:

storm start "your topic"

git clone https://github.com/phobologic/claude_storm.git
cd claude_storm
uv sync
uv run storm start "your topic"

Quick Start

# One-off brainstorming session
storm start "Design a REST API for a todo app" --max-turns 4

# Project-based workflow (recommended)
storm init --topic "Design a distributed task queue"
# Edit storm.toml to add roles, goal, deliverables...
storm start

Project Configuration

Run storm init to create a storm.toml in your project directory:

[session]
topic = """
Design a distributed task queue system that handles
job prioritization, retry logic, and horizontal scaling.
"""

goal = """
Favor battle-tested technologies; produce production-ready designs
with clear trade-off analysis for each decision.
"""

role_a = """
Systems Architect - Deep experience with distributed systems.
Favors pragmatic, battle-tested approaches.
"""

role_b = """
Reliability Engineer - Focuses on failure modes, observability,
and operational concerns.
"""

deliverables = [
    "Architecture overview document",
    "Data model specification",
    "Failure handling policy",
]

# Optional: directories of notes/docs agents can read for context
# reference_dirs = ["./research/notes"]

[options]
max_turns = 20
model = "sonnet"
auto_complete = true
interactive = false
# max_minutes = 30
# agent_timeout = 600
# truncate_conversation = true
# web_search = false

Sessions are stored in .storms/ alongside storm.toml (add to .gitignore).

Configuration Reference

[session]

[options]

Usage

# Initialize a project config
storm init [--topic "quick topic"]
storm init --force             # overwrite existing storm.toml

# Migrate existing config to latest schema
storm init --update

# Start a session (reads storm.toml if present, or pass a topic)
storm start [TOPIC] [OPTIONS]
storm start --config path/to/storm.toml
storm start "Quick topic" --max-turns 4

# With custom roles and a goal (one-off mode)
storm start "Microservices vs monolith" --roles "Advocate" "Skeptic" --auto-complete
storm start "API design" --goal "Prefer REST; produce an OpenAPI spec"

# Produce specific deliverables (repeatable)
storm start --deliverable "Architecture doc" --deliverable "Data model"

# CLI flags override TOML values
storm start --max-turns 6 --model opus
storm start --max-minutes 30           # stop after 30 minutes regardless of turns
storm start --agent-timeout 120        # shorten per-turn timeout to 2 minutes

# Give agents read-only access to reference materials (repeatable)
storm start --reference-dir ./research/notes --reference-dir ./design/specs

# Interactive mode — type nudges at any time to steer the conversation;
# agents can ask you questions via [ASK_USER]
storm start --interactive

# Enable web search (agents can use WebSearch + WebFetch)
storm start --web-search

# Enable verbose debug logging (agent prompts + raw responses written to debug.log)
storm --debug start "your topic"

# Resume a paused session (Ctrl+C to pause)
storm resume <session-id>
storm resume <session-id> --force  # recover after a hard kill

# List and inspect sessions
storm list
storm list --config path/to/storm.toml  # locate .storms/ from a specific config
storm show <session-id>                 # includes why the session stopped
storm show <session-id> --config path/to/storm.toml

Agent Protocol

Agents communicate via structured directives embedded in their responses.

Shared Output

Conversation Pacing

When deliverables or a goal are defined, agents receive pacing guidance based on turn progress:

Agreement nudges: After turn 3 with no agreements, agents are nudged to use [PROPOSE]. If 4+ turns pass since the last accepted agreement, agents get a reminder.

Deliverable compilation: After the session ends, each deliverable is compiled by a separate Claude instance from the conversation log, agreements, and matching draft artifacts.

Interactive Mode

• User nudges: Type at any time in the TUI to steer the conversation; queued and merged into the next turn prompt.
• Agent questions: [ASK_USER] pauses the agent to ask the user. The TUI defers the question if the user is mid-typing.
• Early clarification pacing: In interactive sessions, agents are encouraged to use [ASK_USER] in the first 20% of turns.
• Non-interactive: No user input during the session; [ASK_USER] is not available to agents.

TUI Navigation

The TUI auto-scrolls to follow new output. Scrolling up pauses auto-follow and shows a scroll indicator; scrolling back to the bottom (or pressing End) resumes it.

How It Works

1. Two Claude Code CLI instances are launched with persistent sessions
2. Agents take strict alternating turns responding to each other
3. Agents can produce shared artifacts (code, documents)
4. Agents formalize shared decisions using an agreement protocol ([PROPOSE]/[ACCEPT]/[REJECT]/[REVISE]); confirmed agreements persist to agreements.md and feed into deliverable compilation. Verbal agreement alone ("I agree", "good point") does not create a shared record — only [PROPOSE] + [ACCEPT] does. Pacing nudges encourage [PROPOSE] usage when no agreements have been recorded recently.
5. Pacing nudges guide agents through exploration, convergence, and deliverable production
6. In --auto-complete mode, agents signal [DONE] when the topic is well-explored
7. Sessions can be paused with Ctrl+C and resumed later; each session records why it stopped (visible via storm show)
8. When running in a terminal, a full-screen TUI provides live-streamed agent output, an animated thinking timer, and a persistent input bar for nudges (Shift+Enter for newlines); the header shows the session ID. Piped/non-TTY output falls back to plain Rich console

Security

Agent filesystem access is restricted via path-scoped --allowedTools patterns:

• Read/Glob/Grep: session directory + reference directories (if configured)
• Write/Edit: session directory only
• Bash/other tools: not available to agents

License

MIT