---
slug: "pi-meeting-blackboard"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Jarcis-cy/pi-meeting-blackboard@main/README.md"
repo: "https://github.com/Jarcis-cy/pi-meeting-blackboard"
source_file: "README.md"
branch: "main"
---
# 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-meeting-blackboard/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