claude-storm 0.1.2

Dual-agent brainstorming system using Claude Code CLI sessions

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 and has access to a markdown-based memory filesystem for long-term notes.

Installation

uv sync

Quick Start

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

# Project-based workflow (recommended)
uv run storm init --topic "Design a distributed task queue"
# Edit storm.toml to add roles, goal, deliverables...
uv run 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 = ["/path/to/research/notes"]

[options]
max_turns = 20
model = "sonnet"
auto_complete = true
interactive = false
# truncate_conversation = true

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

Configuration Reference

[session]

Key	Default	Description
topic	(required)	The subject or question under discussion. Multi-line strings supported.
goal	—	Desired outcome or success criterion. Reinforced in pacing, summary, and deliverable compilation. Describes direction/quality, not a specific document.
role_a / role_b	—	Agent personas. Become the agent's system prompt, replacing Claude Code's default instructions. First line is used as the TUI display label — keep it short (a title); additional lines provide detailed persona guidance.
deliverables	[]	Documents to produce as [ARTIFACT] files. Drives pacing and post-session compilation. Also settable via --deliverable CLI flag. Draft artifacts with matching filenames are used as foundations.
reference_dirs	[]	Read-only directories agents can browse via Read/Glob/Grep.

[options]

Key	Default	Description
max_turns	20	Turn budget. Shapes percentage-based pacing.
model	"sonnet"	Claude model to use ("sonnet", "opus", or a full model ID).
auto_complete	true	Allow agents to signal [DONE]. Requires both agents to agree.
interactive	false	Enable user nudges and [ASK_USER] questions.
truncate_conversation	true	Truncate conversation to last ~50k chars during deliverable compilation.

Usage

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

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

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

# With custom roles (one-off mode)
uv run storm start "Microservices vs monolith" --roles "Advocate" "Skeptic" --auto-complete

# CLI flags override TOML values
uv run storm start --max-turns 6 --model opus

# Give agents read-only access to reference materials (repeatable)
uv run 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]
uv run storm start --interactive

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

# List and inspect sessions
uv run storm list
uv run storm show <session-id>            # includes why the session stopped

Agent Protocol

Agents communicate via structured directives embedded in their responses.

Private Tools

Directive	Syntax	Description
[MEMORY]	[MEMORY title="..." tags="t1,t2"]content[/MEMORY]	Save a note to the agent's private long-term memory. Use for working notes, open questions, and ideas in development.
[MEMORY_SEARCH]	[MEMORY_SEARCH query="..."]	Search saved memories. Results appear in the agent's next turn.

Shared Output

Directive	Syntax	Description
[PROPOSE]	[PROPOSE title="..."]content[/PROPOSE]	Propose a shared agreement for the other agent to confirm.
[ACCEPT]	[ACCEPT id="..."]	Accept a pending proposal by ID.
[REJECT]	[REJECT id="..." reason="..."]	Reject a pending proposal with explanation.
[REVISE]	[REVISE id="..."]new content[/REVISE]	Propose a revision to an existing confirmed agreement. Creates a new pending proposal.
[ARTIFACT]	[ARTIFACT filename="..."]content[/ARTIFACT]	Produce a shared output file (code, document, etc.).
[DONE]	[DONE reason="..."]	Signal that brainstorming is complete. The other agent must confirm; if they disagree, conversation continues.
[ASK_USER]	[ASK_USER]question[/ASK_USER]	Pause to ask the human user a question (interactive mode only).

Conversation Pacing

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

Progress	Guidance
≤20% (interactive)	Use [ASK_USER] to clarify intent before narrowing
Default	Continue brainstorming, save ideas with [MEMORY]
50%	Start narrowing; produce draft [ARTIFACT] files
75%	Finalize artifacts, resolve open questions
Final 2 turns	Complete all artifacts; produce any missing deliverables

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 agent memories, agreements, conversation log, 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.

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. Each agent can save notes to its memory filesystem for long-term retention
4. Agents can produce shared artifacts (code, documents)
5. 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.
6. Pacing nudges guide agents through exploration, convergence, and deliverable production
7. In --auto-complete mode, agents signal [DONE] when the topic is well-explored
8. Sessions can be paused with Ctrl+C and resumed later; each session records why it stopped (visible via storm show)
9. When running in a terminal, a full-screen TUI provides scrollable 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