pi-brainstorm

Multi-model brainstorming and debate sessions for pi.

pi-brainstorm lets different models from different providers join the same discussion. Use /brainstorm for a structured round-robin ideation session, or /debate for a more adversarial battle where agents challenge each other's assumptions until the discussion converges.

The plugin stores each participant's full contribution in a local meeting blackboard under .pi-meetings/.... The blackboard is an implementation feature: it keeps the main chat focused on compact cards, summaries, conflicts, and conclusions while preserving the complete transcript on disk.

中文说明见 README.zh-CN.md.

Features

• Multi-model brainstorming with configurable participants (default: GPT, DeepSeek, MiniMax, GLM).
• Debate / battle mode where agents prosecute, stress-test, and challenge positions.
• Configuration-driven: add, remove, or customize participants via YAML.
• Round-by-round summaries focused on consensus, disagreement, and next questions.
• Full participant contributions stored as Markdown files under .pi-meetings/.
• Compact visible cards in the main conversation instead of long pasted transcripts.
• JSONL index for lightweight cross-round context.
• Managed agent files generated from config — update one YAML, all agents sync.

Install

Recommended one-line install:

pi install npm:@narumitw/pi-subagents && pi install npm:pi-brainstorm

Install only this package from npm:

pi install npm:pi-brainstorm

From GitHub:

pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.4.3

For local development:

pi install /Users/jarcis/Project/pi-brainstorm

Prerequisites

pi-brainstorm orchestrates participants through Pi's subagent tool. Install the subagent tool separately before using /brainstorm or /debate:

pi install npm:@narumitw/pi-subagents

@narumitw/pi-subagents registers the subagent tool used by this package to run participant agents in isolated Pi subprocesses. It is a runtime prerequisite, not bundled inside pi-brainstorm.

For reference, Pi's coding-agent distribution also includes an example implementation at:

/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/

pi-brainstorm also needs participant agents such as gpt-brainstormer, deepseek-brainstormer, minimax-brainstormer, and glm-brainstormer. On first use, the extension can create or update managed user-level agent files from its YAML configuration. Existing unmanaged agent files are left untouched.

@narumitw/pi-subagents applies a hard subprocess timeout. If timeoutMs is not set, it uses PI_SUBAGENT_TIMEOUT_MS, or 600000 milliseconds (10 minutes) when that environment variable is unset. Long participant output is not itself a timeout condition, but generating very long output can take longer and may hit that wall-clock timeout. Participant full text is written to .pi-meetings/...; the main chat should only receive short WROTE_ENTRY summaries and facilitator synthesis.

Configuration

Participants are defined in YAML. The extension loads config in this order (later overrides earlier):

1. Package default: config/default.yaml (shipped with the package)
2. User override: ~/.pi/agent/pi-brainstorm.yaml
3. Project override: .pi-brainstorm.yaml or .pi/pi-brainstorm.yaml

Arrays (e.g. participants) replace entirely; objects deep-merge.

Adding a new participant

Create ~/.pi/agent/pi-brainstorm.yaml (user-level) or .pi-brainstorm.yaml (project-level):

participants:
  - displayName: Claude
    agentName: claude-brainstormer
    description: Claude brainstorming consultant. Nuanced analyst for multi-model discussion sessions.
    model: anthropic/claude-sonnet-4-20250514:xhigh
    roleTitle: Nuanced Analyst
    rolePrompt: |
      你是多模型头脑风暴中的分析顾问。擅长细致入微的论证和长篇分析。用中文回答。
    whatYouDo:
      - 提供细致、深入的逐点分析
      - 识别细微差别和边缘情况
      - 撰写结构清晰的长篇论证
    debatePersona:
      label: THE ANALYST
      prompt: |
        DEBATE MODE. You are THE ANALYST. Dissect every argument with precision. Find the weakest link in every chain of reasoning. Use Chinese.
    brainstormRole: Nuanced analyst

To replace the default participants entirely, define a full participants list in your override file.

User-level config can create or update managed agent files in ~/.pi/agent/agents/ after confirmation. Project-level config is used for the current session, but it does not auto-write global agent files; create those agents manually or move the config to ~/.pi/agent/pi-brainstorm.yaml when you want automatic sync.

Managed agent files

Agent files generated by pi-brainstorm contain <!-- managed-by: pi-brainstorm -->. These files are overwritten when the config changes. Existing agent files without this marker are never touched.

Commands

/brainstorm <topic>
/debate <topic>

/brainstorm starts an interactive three-round multi-model brainstorming session. After Round 1 and Round 2, the facilitator should stop, summarize the round, and wait for your feedback or permission before continuing.

/debate starts an open-ended multi-agent battle that should continue until convergence or user intervention.

How It Works

participant model -> meeting_append_entry -> .pi-meetings/... files
participant model -> short WROTE_ENTRY summary -> facilitator context
file watcher -> compact visible card -> main chat
facilitator -> round checkpoint / consensus / disagreement / final synthesis

The blackboard files are the source of truth for the session. The facilitator can read the index or specific entries when producing summaries.

Tools

The extension registers four tools:

• meeting_rename (facilitator-only) renames the meeting directory to a human-readable title before Round 1 starts.
• meeting_append_entry writes a full participant contribution to disk and returns only a short reference.
• meeting_read_index lists entries by id, speaker, phase, summary, and path.
• meeting_read_entry reads one full entry when the facilitator or a participant needs it.

Files

Each session writes an append-only folder under the current working directory:

.pi-meetings/YYYY-MM-DD-topic/
  manifest.json
  index.jsonl
  blackboard.md
  entries/
    0001-gpt-round_1.md
    0002-deepseek-round_1.md

blackboard.md is the full transcript. index.jsonl is the compact context entry point. Full participant text lives in entries/.

Safety

The extension validates that meeting paths stay under the current workspace's .pi-meetings/ directory and rejects symlinked meeting paths, entry files, index files, and blackboard files. Entry writes use exclusive creation to avoid overwriting existing files.

Development

npm pack --dry-run

The extension is TypeScript loaded by pi through its extension loader. Runtime dependencies imported from pi (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, and typebox) are declared as peer dependencies per pi package guidance.

License

MIT