pi-brainstorm

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-brainstorm

Multi-agent brainstorming and debate sessions for [pi](https://github.com/earendil-works/pi-coding-agent).

`pi-brainstorm` lets configurable agents join the same discussion with distinct roles and prompts. The packaged defaults all use `neibu/gpt-5.5:xhigh`; their identities provide different reasoning lenses rather than different base models. Use `/brainstorm` for structured ideation or `/debate` for adversarial challenge.

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](https://github.com/Jarcis-cy/pi-brainstorm/blob/HEAD/README.zh-CN.md).

## Features

- Configurable multi-agent brainstorming (defaults: GPT-Progressive, GPT-Localist, GPT-Diagnostician, GPT-Critic; all backed by `neibu/gpt-5.5:xhigh`).
- Debate / battle mode where agents prosecute, stress-test, and challenge positions.
- Configuration-driven: add, remove, or customize participants via YAML.
- 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:

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

Install only this package from npm:

```bash
pi install npm:pi-brainstorm
```

From GitHub:

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

For local development:

```bash
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`:

```bash
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:

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

`pi-brainstorm` uses role-based participant agent files: `gpt-progressive-brainstormer`, `gpt-localist-brainstormer`, `gpt-diagnostician-brainstormer`, and `gpt-critic-brainstormer`. All packaged defaults run `neibu/gpt-5.5:xhigh` with different role prompts. 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):

```yaml
participants:
  - displayName: GPT-Analyst
    agentName: gpt-analyst-brainstormer
    description: GPT-5.5-backed nuanced analyst for multi-agent discussion sessions.
    model: neibu/gpt-5.5:xhigh
    roleTitle: Nuanced Analyst
    rolePrompt: |
      你是多 Agent 头脑风暴中的分析顾问。擅长细致入微的论证和长篇分析。用中文回答。
    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

```text
/brainstorm <topic>
/debate <topic>
```

`/brainstorm` starts an interactive three-round multi-agent 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

```text
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:

```text
.pi-meetings/YYYY-MM-DD-topic/
  manifest.json
  index.jsonl
  blackboard.md
  entries/
    0001-gpt-progressive-round_1.md
    0002-gpt-localist-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

```bash
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

pi-brainstorm

Multi-agent brainstorming and debate sessions for pi.

pi-brainstorm lets configurable agents join the same discussion with distinct roles and prompts. The packaged defaults all use neibu/gpt-5.5:xhigh; their identities provide different reasoning lenses rather than different base models. Use /brainstorm for structured ideation or /debate for adversarial challenge.

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

Configurable multi-agent brainstorming (defaults: GPT-Progressive, GPT-Localist, GPT-Diagnostician, GPT-Critic; all backed by neibu/gpt-5.5:xhigh).
Debate / battle mode where agents prosecute, stress-test, and challenge positions.
Configuration-driven: add, remove, or customize participants via YAML.
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 uses role-based participant agent files: gpt-progressive-brainstormer, gpt-localist-brainstormer, gpt-diagnostician-brainstormer, and gpt-critic-brainstormer. All packaged defaults run neibu/gpt-5.5:xhigh with different role prompts. 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):

Package default: config/default.yaml (shipped with the package)
User override: ~/.pi/agent/pi-brainstorm.yaml
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: GPT-Analyst
    agentName: gpt-analyst-brainstormer
    description: GPT-5.5-backed nuanced analyst for multi-agent discussion sessions.
    model: neibu/gpt-5.5:xhigh
    roleTitle: Nuanced Analyst
    rolePrompt: |
      你是多 Agent 头脑风暴中的分析顾问。擅长细致入微的论证和长篇分析。用中文回答。
    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 . 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-agent 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-progressive-round_1.md
    0002-gpt-localist-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