Metadata-Version: 2.5
Name: plural-agent
Version: 0.2.0
Summary: Multiplayer sessions for one AI agent: shared context, host approvals, attribution, isolation.
Project-URL: Homepage, https://github.com/Plural-Organization/Plural
Project-URL: Issues, https://github.com/Plural-Organization/Plural/issues
Project-URL: Changelog, https://github.com/Plural-Organization/Plural/releases
Author: Plural team
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,coding-agent,llm,multiplayer,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.21
Requires-Dist: anthropic>=2.3.0
Requires-Dist: cryptography>=44
Requires-Dist: openai>=3.37.0
Requires-Dist: pydantic-settings>=2.8
Requires-Dist: pydantic>=2.11
Requires-Dist: rich>=13.9
Requires-Dist: starlette>=0.46
Requires-Dist: structlog>=25.1
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.34
Requires-Dist: websockets>=15
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/assets/logo.png" alt="plural" width="96" height="96">

# plural

**the shared room for your coding agent.**

[install](#install) · [quick start](#quick-start) · [docs](#docs) · [security](SECURITY.md) · [contributing](CONTRIBUTING.md)

[![License](https://img.shields.io/badge/license-Apache--2.0-666666?labelColor=333333)](LICENSE)
[![Release](https://img.shields.io/github/v/release/Plural-Organization/Plural?label=release&labelColor=333333&color=666666)](https://github.com/Plural-Organization/Plural/releases/latest)
[![PyPI](https://img.shields.io/pypi/v/plural-agent?label=pypi&labelColor=333333&color=666666)](https://pypi.org/project/plural-agent/)
[![Python](https://img.shields.io/badge/python-3.12%2B-666666?labelColor=333333)](https://www.python.org/downloads/)

</div>

---

**one agent. one host. everyone in the room.**

- **a shared live session** — the host runs the agent on their machine with their own key. teammates join from a terminal and watch every reply, tool call and diff as it happens.
- **two ways to prompt** — in `open` mode everyone talks to the agent directly. in `review` mode the host approves each prompt first. switch any time.
- **you approve what matters** — write and exec actions always wait for the host, and a run started by a guest can never be waved through by a rule.
- **see who is doing what** — participants, who is typing, a prompt queue, and an attribution on every turn.
- **tools you can follow** — each call is one line. open it to see the live output of a command or a numbered diff.
- **full screen, in your terminal** — a side panel, themes, mouse and keyboard, copy on select. one binary, no runtime to install.
- **your model, your key** — anthropic, any openai-compatible endpoint, or a local model through ollama. api keys only, never subscription logins.
- **event-sourced** — an append-only log is the source of truth. reconnect, replay and audit come for free.
- **direct or relayed** — connect over your network, or through a relay that never decides permissions and never stores content.

---

## install

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

macos and linux, arm64 and x64. windows through wsl. the script installs [uv](https://docs.astral.sh/uv/), the host (`plural-host`) and the `plural` client, and checks the download.

## quick start

start in the project you want the agent to work on:

```bash
cd your-project
plural
```

the first line in the conversation is an invite. send it to a teammate:

```bash
plural join "ws://…"
```

without a key the host runs a scripted demo agent. for a real model:

```bash
ANTHROPIC_API_KEY=sk-ant-… plural
```

`/help` lists the commands, `F2` opens the settings, `ctrl+o` opens the tool details.

## docs

[usage](docs/usage.md) · [configuration](docs/configuration.md) · [relay deployment](deploy/) · [wire protocol](docs/protocol.md) · [threat model](docs/threat-model.md) · [design decisions](docs/adr/) · [development](docs/development.md)

## acknowledgements

plural learns from [pi](https://github.com/badlogic/pi-mono), [opencode](https://github.com/sst/opencode), [hermes](https://github.com/NousResearch/hermes-agent) and [herdr](https://github.com/herdrdev/herdr).

## license

plural is licensed under the [apache license 2.0](LICENSE).
