Plural turns a solo AI agent session into a shared one. The agent runs on the host's machine with the host's API key. Teammates join from a terminal or a browser, watch the run live, and propose prompts. The host stays in control: every proposal and every risky tool call goes through the host's approval.

┌────────────┐        ┌──────────────┐        ┌─────────────┐
│  guest TUI │◀──ws──▶│              │◀──ws──▶│  host       │
├────────────┤        │  relay       │        │  ├ agent    │──▶ LLM API
│  guest web │◀──ws──▶│  (optional,  │        │  ├ policy   │
└────────────┘        │   dumb pipe) │        │  ├ tools    │──▶ workspace
                      └──────────────┘        │  └ event log│
                                              └─────────────┘

Features

• Shared live session. Everyone sees the same transcript, tool calls and diffs as they stream.
• Proposals, not prompts. Guests suggest prompts. The host approves, edits or rejects them.
• Host-only approvals. Write and exec actions need host consent. Guest-originated turns are tainted and always ask. Rejected actions are not re-asked: after repeated rejections of the same kind the agent is told to ask the user instead, and "Block (session)" denies a whole command class.
• Attribution. Every turn records who wrote it and who approved it.
• Policy engine. Allow, ask and deny rules with last-match-wins. Base deny rules cannot be overridden.
• Event-sourced. An append-only SQLite log is the source of truth. Reconnect, replay and audit come for free.
• Isolation. Tools are confined to the workspace. Secret paths are denied and output is redacted.
• Direct or relayed. Connect over LAN directly, or through a relay that never sees permissions and never stores content.
• Terminal clients. A Textual TUI and a plain line mode. A browser client is in progress.
• Bring your own key. API keys only. Plural never touches subscription credentials.

Requirements

• Python 3.12 or newer
• uv 0.5+
• macOS or Linux (Windows through WSL)
• Node.js 22+ (only to work on the in-progress web client)

Installation

curl -fsSL https://raw.githubusercontent.com/Plural-Organization/Plural/main/install.sh | sh

The script installs uv if it is missing, then Plural. Or install it yourself:

uv tool install plural-agent

The package is plural-agent; it installs the plural command. Other ways:

pipx install plural-agent
uvx --from plural-agent plural host

From source, clone the repository and run from its root:

uv sync

Check your environment:

plural doctor

Quick start

Start a session in your project:

uv run plural host --workspace .

The host prints a one-time invite link and opens the TUI. Send the link to a teammate:

uv run plural join "ws://127.0.0.1:7777/r_…?invite=…" --name alia

The default provider is fake, a scripted demo that needs no API key. Plain text lists the workspace. $ cmd asks to run cmd through bash and waits for host approval.

Through a relay

uv run plural relay --bind 0.0.0.0 --port 8787
uv run plural host --relay wss://relay.example.com

A ready-made deployment with Caddy and TLS lives in deploy/.

Usage

Commands

Run plural <command> --help for all options.

TUI keys

Prompt-line commands work in the TUI and in plural join --plain: /abort, /compact, /policy (list rules), /policy allow|ask|deny <tool> <pattern>, /policy rm <rule id>.

Configuration

Every setting can be passed as an environment variable with the PLURAL_ prefix.

Providers

Two adapters cover most models: anthropic uses the official Anthropic SDK, and openai speaks the OpenAI Chat Completions format, which also covers OpenRouter, Groq, Gemini, DeepSeek and local servers such as Ollama.

PLURAL_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-... plural host

PLURAL_PROVIDER=openai PLURAL_MODEL=gpt-5 OPENAI_API_KEY=sk-... plural host

PLURAL_PROVIDER=openai PLURAL_MODEL=qwen2.5-coder PLURAL_BASE_URL=http://localhost:11434/v1 plural host

How it works

1. The host starts a session. A SessionActor owns the room and processes every command in order: append to the log, reduce state, publish.
2. A guest joins with an invite and receives a signed Ed25519 capability token bound to the room and connection.
3. The guest proposes a prompt. The host approves it, and it enters the agent's queue attributed as [alia, proposal approved by host].
4. The agent loop streams the model's reply. Each tool call is prepared, evaluated by the PolicyGate, and either runs, waits for the host, or is denied.
5. Every event goes to the event log first and is then fanned out to clients. A client that reconnects asks for events since its last seq.

Security model

• The agent and the API key live only on the host. Guests never see the key.
• Permission decisions are made only by the host. The relay is a dumb pipe.
• No tool runs without passing the PolicyGate. There are no bypasses.
• Tools are confined to the workspace with realpath checks and a deny-list for secret files such as .env, keys and credentials.
• bash runs with a clean environment, in its own process group, with a timeout.
• Secrets are redacted before anything is written to the log or sent to clients.

See SECURITY.md to report a vulnerability and docs/threat-model.md for the full threat model.

Architecture

Plural is a hexagonal, event-sourced Python app. Layers are enforced with import-linter.

src/plural/
├── protocol/   wire models, envelope, codec          (pure)
├── core/       state reducer, roles, policy engine   (pure)
├── security/   tokens, host keys, redaction
├── agent/      harness: loop, tools, sandbox, providers
├── storage/    SQLite event store, migrations, export
├── host/       session actor, gateway, transports
├── relay/      dumb relay router
├── client/     connection, reconnect, projection
├── cli/        Typer entry point
└── tui/        Textual app
web/            browser client (in progress)

• core and protocol do no I/O.
• agent knows nothing about transports or storage.
• relay knows nothing about sessions, policy or content.
• client knows nothing about the host internals.

Design notes: docs/adr/ · Wire protocol: docs/protocol.md

Development

uv sync
uv run pytest

Full check, the same one CI runs:

uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run lint-imports && uv run pytest

Regenerate the protocol JSON schema for the web client:

uv run python scripts/gen_schema.py

Web client (in progress):

cd web
npm ci
npm run dev

Roadmap

• Protocol, event log and session actor
• Policy engine and host approvals
• Workspace tools and local sandbox
• Direct and relay transports
• TUI and plain clients
• Anthropic and OpenAI-compatible providers
• Web client (in progress)
• Context compaction
• Container sandbox
• End-to-end and load tests

Contributing

Contributions are welcome. Read CONTRIBUTING.md first. In short:

• Open an issue before large changes.
• Use Conventional Commits.
• New dependencies need discussion, and large ones need an ADR.
• Make sure the full check passes.

Acknowledgements

Plural learns from Pi, OpenCode and Hermes.

License

Plural is licensed under the Apache License 2.0.