# Plurality AI

Think through a decision with several AI models. Plurality gathers independent perspectives, lets them respond to one another, and returns a decision memo with the disagreements and complete transcript preserved.

Use it as a personal MCP server in Codex, Claude Desktop or another MCP host, with your own OpenRouter key. The repository also includes the Nuxt website, shared deliberation engine, tests and reusable agent skills.

## Personal MCP quick start

Install **Node.js 22 or later** and get an [OpenRouter API key](https://openrouter.ai/keys). From a copy of this repository:

```bash
npm ci
node scripts/mcp-direct.mjs --help
```

Save your key outside the repository in a private file, for example `~/.config/plurality/openrouter-api-key`, readable only by you (`chmod 600`). Configure your MCP host with absolute paths:

```json
{
  "mcpServers": {
    "plurality": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/plurality-ai-mcp/scripts/mcp-direct.mjs"],
      "env": {
        "OPENROUTER_API_KEY_FILE": "/absolute/path/to/private/openrouter-api-key"
      }
    }
  }
}
```

Reconnect the host, then ask: **“Use Plurality to review this plan against my constraints.”**

The MCP needs no hosted app, subscription, Stripe account or Postgres database. OpenRouter charges for model usage. The launcher reads its process environment; it does **not** load `.env` automatically.

[Full setup and Codex configuration](docs/mcp-setup.md)

## What it does

- **Eight methods:** Quick Take, Consensus, Debate, Red Team, Peer Review, Forecast, Brainstorm and Oracle voting.
- **Named persona teams:** choose complementary roles and models, including multiple roles using the same model.
- **Preview and background work:** inspect the roster and call bounds, start a saved run, and retrieve it by ID.
- **Private history:** SQLite checkpoints retain complete responses, partial failures, usage and finish reasons. Export JSON or Markdown and record usefulness feedback.
- **Bounded recovery:** token-limit continuations are capped; interrupted and failed work stays inspectable. Network failures do not automatically replay paid calls.

Results lead with a memo; transcripts remain available through `plurality_result` and `plurality_export`. Runs live in `~/.local/share/plurality` by default, configurable with `PLURALITY_DATA_DIR`. This archive is private by file permissions, but is not encrypted at rest. Prompts and supplied evidence are sent to OpenRouter and the selected model providers.

Model agreement is not factual verification. Same-model personas are correlated, Oracle percentages are vote shares or ratings, and forecasts are not calibrated probabilities. A panel can cost more without producing a better answer; the included comparison harness helps evaluate that tradeoff.

## Development and checks

```bash
npm test
npm run build
npm run mcp:eval -- --fixture   # offline synthetic comparison
npm run mcp:eval               # preview the paid experiment; no generation
```

Live experiments require an explicit `--execute` and incur provider charges. Keep generated responses and personal data outside source control.

| Directory | Contents |
|---|---|
| `packages/core/` | Shared models, prompts, parsers and deliberation utilities |
| `server/utils/personal-*.ts` | Personal MCP planning, execution and SQLite persistence |
| `scripts/mcp-direct.mjs` | Personal stdio MCP entry point |
| `skills/` | Review, persona-team and Oracle agent skills |
| `experiments/` | Reproducible comparison code and synthetic cases |
| `app/`, `server/api/` | Nuxt website and authenticated hosted API |
| `tests/` | Offline unit, workflow and recovery checks |

## Self-hosting the website

The website is a separate setup with Supabase authentication, Postgres persistence and optional commercial integrations. It retains the original branding, pricing screens and deployment assumptions. The personal MCP is the simplest way to start.

```bash
cp .env.example .env
# Configure your own services and operator details.
npm run dev
```

[Website setup and deployment checklist](docs/self-hosting.md) · [Billing runbook](docs/stripe-launch-runbook.md)

## Contributing and security

See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and contribution scope, and [SECURITY.md](SECURITY.md) for secret handling and private vulnerability reporting. Both package manifests remain `private: true` to prevent accidental npm publication; this does not restrict using or modifying the source.

## License

[Apache License 2.0](LICENSE). Copyright © 2026 Thor Matthiasson. See [NOTICE](NOTICE). Dependencies retain their own licenses.