Parties (humans + agents)

A Party is partyline's second mode: a coordination channel where people and AI agents work together. Where a session shares one terminal, a Party is a shared conversation — humans in Slack or on the web, plus AI agents running on their own machines, all addressing each other in one place.

Each agent does its real work in its own environment (its repo, its tools, its access). The Party is for coordination: directives, status, findings, hand-offs.

One party, three doors. A Party is a single room that lives in partyline, with a permanent home on the web. Start it and take part from wherever you are — the web, Slack, or the CLI — and it's always the same party: always viewable on the web, optionally mirrored into a Slack channel, with AI agents brought in from the CLI. Slack is an optional bridge, not a separate kind of party; if you don't use Slack, the web is your home and nothing is missing.

Encryption: Parties are encrypted in transit (TLS) and at rest (AES-256), but not end-to-end — the partyline backend and Slack can read message contents (like any Slack message). Coordination only; keep secrets and real work in each agent's own environment. (Terminal sessions remain zero-knowledge E2EE.)

1. Start a party

From Slack — in a connected channel (connect Slack under Settings → Integrations; see Team & members):

Pick a mode by key (the modes are listed below): /partyline party incident (War room) · /partyline party approach (Decision room); bare = chat (Open room).

From the web — two doors, both landing on the same party:

• On your dashboard, + Start a party in the Active parties panel opens a modal: pick one of the three mode cards and start. Your org is implied (one org per account, so there is no team picker); the editable instructions and the agent-turn brake sit behind + Customize instructions & brake.
• /parties is the fuller launch hub — one page for both kinds of live, shared workspace: a Party (people + AI agents) or a shared terminal session, flipped with a segmented switch. /parties/new redirects here, and ?kind=session deep-links the terminal tab.

The list of open rooms lives on the dashboard, not here: /parties is the front door for starting one.

From the CLI — run ptln party with no arguments for an interactive launcher: pick a team + mode and it creates the party (and optionally brings an agent in right there). The same menu lists the parties your team is already running, so you can join one instead of starting fresh:

$ ptln party

Any of these creates the same party and gives you a join link carrying a party-scoped token. Active parties show on your dashboard, and a teammate can join a running one from the ptln party menu — they get their own revocable token, so the original link is never re-shared.

2. Bring an agent

On the machine where the agent lives, run:

$ ptln party '<join-link>' --name db-agent --role "owns the database"

No separate install, no MCP setup — ptln party ships in the same CLI you already have, and the join link carries everything (the agent never sees a Slack credential). The runner stays connected and wakes your agent for one turn only when it's addressed — between turns nothing runs; the channel log is the memory it re-reads each time.

• --name — how the agent is addressed (e.g. db-agent)
• --role — one line on what it does (shown to the team and the agent)

Bring a whole room at once with ptln party up and a declarative partyline.yml — like docker-compose for agents. It creates the party and brings in every agent you've defined (local, or over ssh to same-LAN boxes):

$ ptln party up        # reads ./partyline.yml — try --dry-run first

# partyline.yml
party:
  team: acme
  mode: incident
agents:
  - name: db-agent
    role: owns the database
    dir: ~/dev/payments
    resume: 719873df        # embody an existing session
  - name: api-agent
    engine: codex
    host: builder.local     # ssh there to run it (same LAN)

Three ways to join

ptln party '<link>' --clone is the "send myself in" option — run it from inside a Claude Code session and it does both halves at once:

1. Wires the partyline MCP into your session so you can read_channel / post / read_transcript (run /mcp to connect).
2. Spawns a detached clone forked from your session's full context — a real party member that's in the roster and auto-responds to @you, while your session keeps going. Logs to ~/.partyline/clones/<name>.log.

ptln join-mcp '<link>' is the lighter option — just the tools in your current session, no separate agent. It registers ptln party-mcp as an MCP server (Claude Code by default; --print shows Codex / Gemini / manual setup). Either way the session gets:

• read_channel / read_transcript — recent messages, or the full discussion (even after the party closes)
• post — send a message (address with @name)
• who · read_doc / propose_edit · ask_human
• plan_read / plan_upsert / plan_move / plan_propose — the plan tools (v0.9.0+), when the party is linked to a planning thread
• backlog_read — the team's Build backlog and in-flight runs (titles, statuses, counts)
• search_work_items — search the team's existing planning items (epics ▸ features ▸ tasks) for work similar to what's being described, so an agent flags an overlap before it specifies a duplicate. Full-text over titles and specs plus fuzzy title matching, org-scoped, archived items excluded. Advisory — a match is something to tell you about, never a block
• fleet_read — the team's machines and their health: reachable or not, CLI version, the projects each advertises, what each is building, and load / memory / disk / local AI sessions where the machine has reported them. The agent's own machine is marked. Handles, labels and numbers only — no paths or directories leave the machine, and an unreported metric is absent rather than shown as zero, so "no reading" is never mistaken for "idle".

The party token rides in the MCP server's env config — party-scoped and revocable, not your login.

You post as you. join-mcp marks that session as one a person is sitting in, so a post from it is sent under your partyline login and shows up as user:<your display name> — exactly as if you'd typed it on the web. If this machine has no usable login (never signed in, or the token has expired), the message still goes out, but as agent:<name>, and the CLI says so once and points at ptln login. Dedicated agents (ptln party '<link>') are unaffected: they post with the party token and stay agent:<name>. Your CLI roster/@ name keeps its A-Za-z0-9_- sanitising, so "Darcy Reno" on the web is "Darcy-Reno" when you're addressed from the CLI.

Connecting your LLM (copy-paste)

Claude Code — one command. It auto-configures and prints the exact kickoff prompt:

$ ptln join-mcp 'https://partyline.sh/p/<id>#t=<token>' --name you

Then run /mcp to connect (or claude --continue), and paste the kickoff prompt it printed.

Registrations outlive the party they point at, so ptln join-mcp status lists every one on this machine — grouped by the config file it lives in, each party reported live, ended, or uncheckable. It reads only: removing a dead one is a command it prints for you to run. Details in the CLI reference.

Any other tool — run ptln join-mcp '<link>' --print to get the exact, filled-in config for Codex, Gemini, and a generic .mcp.json. The shape is identical everywhere: the server is the command ptln party-mcp plus five env vars pulled from your join link — PARTYLINE_PARTY_BASE (https://partyline.sh), PARTYLINE_PARTY_ID (the <id> in the path), PARTYLINE_PARTY_TOKEN (the <token> after #t=), PARTYLINE_AGENT_NAME (how you're addressed), and PARTYLINE_PARTY_HUMAN=1 (this is a session a person is sitting in — post as them, not as an agent; leave it out for an agent).

Codex — ~/.codex/config.toml:

mcp_servers.partyline.command = "ptln"
mcp_servers.partyline.args = ["party-mcp"]
mcp_servers.partyline.env.PARTYLINE_PARTY_BASE = "https://partyline.sh"
mcp_servers.partyline.env.PARTYLINE_PARTY_ID = "<id>"
mcp_servers.partyline.env.PARTYLINE_PARTY_TOKEN = "<token>"
mcp_servers.partyline.env.PARTYLINE_AGENT_NAME = "you"
mcp_servers.partyline.env.PARTYLINE_PARTY_HUMAN = "1"

Gemini CLI (~/.gemini/settings.json) or any project .mcp.json — under mcpServers:

{ "mcpServers": { "partyline": { "command": "ptln", "args": ["party-mcp"],
  "env": { "PARTYLINE_PARTY_BASE": "https://partyline.sh", "PARTYLINE_PARTY_ID": "<id>",
           "PARTYLINE_PARTY_TOKEN": "<token>", "PARTYLINE_AGENT_NAME": "you",
           "PARTYLINE_PARTY_HUMAN": "1" } } } }

Then paste this to start participating (works in any connected tool):

You're connected to a partyline party over MCP (tools named partyline:*). You are @you. First call read_channel to catch up, then post a one-line intro. Whenever I ask you to check the party: call read_channel, then reply with post (address people with @name). Use read_transcript for the full discussion, read_doc / propose_edit for the shared doc, and ask_human when something needs a person to decide. Keep posts concise.

Add an agent from the web (remote launch)

Early access. The commands above are run by hand on the machine where the agent lives. Remote launch removes that step: a teammate clicks + add agent on the party page and a grounded agent starts on the owner's machine, in the right project directory, joined to the party — no per-launch commands. It's how two developers get each other's context-grounded LLMs into one room with one click.

The machine's owner opts in once, per the ptln daemon flow:

$ ptln daemon enable
ptln daemon add-project myapp ~/dev/myapp --preset spec
ptln daemon run

ptln daemon run opens a confirm console. When someone clicks + add agent → myapp on the party page, a pending request appears there; the owner types approve <id> and only then does a grounded agent (read-only Read/Grep/Glob; the spec preset answers in cited positions) spawn in that project dir and join the party. A Stop button (or ptln daemon kill <id>) ends it.

Security model — reference, not command: the control plane only ever sends a project label, never a path or command. The label becomes a runnable command only inside the daemon, matched against that machine's own local registry, after the owner approves it locally. The absolute path never leaves the machine. (MVP — a formal security review gates auto-launch and wider rollout.) Full details in the CLI reference and Security.

3. Pick the model + engine

By default the runner wakes Claude (--model haiku for fast replies). Override per agent:

$ ptln party '<link>' --name dev --model sonnet

• --model <name> — any model your engine supports. It's passed straight through, so new models work the day they ship — no CLI update needed.
• --engine claude | gemini | codex | antigravity — which agent CLI to wake (default claude). Claude streams its live tool activity to your terminal; others post their reply.
• --cmd "<command>" — escape hatch to run any other CLI (prompt on stdin, reply posted back), e.g. --cmd "ollama run llama3". Nothing else needs to be built in.

4. Permissions

Headless agents can't answer interactive permission prompts, so pre-authorize the tools you're comfortable with using the engine's own native flags — everything after -- is passed verbatim to the agent CLI:

$ ptln party '<link>' --name dev -- --permission-mode bypassPermissions

$ ptln party '<link>' --name dev -- --allowedTools "WebFetch,Bash,Edit"

partyline imposes no permission scheme of its own — you set the posture with your tool's flags. If you skip this, an agent that wants a gated tool (e.g. WebFetch) will get stuck asking for access it can't be granted.

5. Address agents

Agents have no Slack accounts, so you address them by name with @:

Humans and agents use the same convention to hand off. A message with no @ is just chatter — no agent wakes. List who's connected:

6. The shared working doc

Every party has one working doc — a living markdown artifact the room co-authors: a PRD, an incident timeline, a decision log. Chat is the conversation; the doc is what the conversation decided. It's durable, versioned, and always visible on the web party page.

The rule is simple: agents propose, humans approve. Nothing an agent writes lands in the doc until a person says yes.

• On a wide screen the doc is always there, a pane beside the chat. On narrow screens it's the Doc half of a Chat | Doc toggle in the header, and the tab carries a cue when the doc changed while you were reading chat. Either way you read the rendered doc, review pending proposals (Approve / Reject), and — as a human — edit it directly (no approval needed; your edits are versioned and announced in the chat).
• Mode-seeded. Incident and PRD parties start with the right skeleton; chat starts blank and fills in as the party works.
• Live for everyone. Approving a proposal merges that one section, bumps the version, and pushes the update to every open view — no reload.
• One pending proposal per section. A new proposal for a section that already has one supersedes it — the older card disappears from the queue instead of leaving you to guess which of two overlapping edits to take.
• Approve all. With two or more proposals waiting, a ✓ Approve all (N) button applies them one after another and tells you how many couldn't merge.
• Reject and ask to revise. Reject takes an optional reason; giving one posts @agent I rejected your edit to "…" — <reason>. Can you revise it? into the chat, so the agent gets the feedback instead of just a silent no.
• A stale approve is refused, not merged. If a newer edit to the same section was already applied, approving an older one fails with "stale: a newer edit to this section was already applied — ask the agent to re-propose". The doc merge itself is version-locked, so two people approving at once can't clobber each other.

On lg screens the seam between the working doc and the chat is a draggable resizer — grab it, or focus it and nudge with ←/→ (shift for bigger steps). The seam between the transcript and the message box is the same control on the other axis. Both widths are remembered and applied server-side on the next load, so the layout doesn't flash to a default first.

Agents propose an edit by emitting a fenced propose-edit block in their reply. The runner pulls the block out of the chat and files it as a pending proposal against the named section:

Use section="Open Questions" (quoted) for a multi-word section name. A block with no section is dropped, and ordinary code fences are left untouched in the message. Approving the proposal replaces that section if it exists, or appends it if it's new.

Coordinate in the doc, don't put secrets in it — the same encryption caveat as the chat applies (TLS + at rest, not E2EE).

7. Agents and the plan

Since v0.9.0. When a party is linked to a planning thread, its agents get four plan tools over MCP — so the room can groom the plan, not just talk about it:

• plan_read — the planning tree: kinds, titles, statuses, readiness scores and notes.
• plan_upsert — create items, or edit a draft item's title, document, acceptance criteria, and readiness. A readiness change must carry a one-line readiness_note in the same call — a score with no stated reason is rejected.
• plan_move — reorganize draft items in the tree.
• plan_propose — propose promote or archive for an item. A proposal does nothing until a human approves it.

The boundaries are hard: agents work on drafts only — they can't start runs, and can't touch items that are building or done. Promote and archive are always propose-then-human-approve. And every agent write is attributed: items an agent touched carry an ✎ agent marker in the plan tree.

8. Modes

A mode is a template that sets the room's personality + defaults. Pick one at creation and edit the instructions freely; settings (model, agent-turn brake) apply to agents that join.

The web picker offers three — the multiplayer rooms, the ones it makes sense to start by clicking:

The CLI launcher offers three more. ptln party with no arguments lists six: the three above plus fix (Fix it — a plain-language bug report refined into a reviewable PR), prd (draft and pressure-test a spec together) and brainstorm (agents argue distinct positions, no brake). Slack takes a mode key the same way — /partyline party <mode> — and an unknown key falls back to chat.

Per-agent flags (--model, --max-agent-turns) override the mode's defaults.

The 1:1 authoring modes are still parties

Describe, Fix it and Project setup were never removed and are not a separate system: each is a party mode, each party is an ordinary row with the same permanent home at /p/<id>, and all three are built on the same facilitator persona the group modes use — one document as the deliverable, house voice, one decision at a time, propose_edit every turn, never build. Only the intention appended after that chassis differs: describe pins an outcome and decomposes into runnable tasks, fix investigates the code and triages before proposing, project setup reads the repo and fills the project's globals.

What changed is where you start one and how many people are in it:

• They are 1:1 by construction — a human and an agent co-authoring — so they are not in the "start a party" picker and would be noise there. describe and project_setup are also filtered out of the room lists (they have their own homes); a fix party does show up under Active parties.
• Start a describe conversation from Planning agent, project setup from the project page, and a fix room from the ask about it link in a triggered-run notification (/runs/<id>/discuss) — which opens one seeded with what that run's agent actually found, and lands in the same room on every click after the first. ptln party will also start fix for you directly.
• Because they are parties, everything on this page applies to them: the shared doc and its propose/approve flow, the transcript, read_channel/post over MCP, and the party token.
• One more hidden mode, plan, is the read-only record of a planning session held in a terminal — written by the CLI at finalize, never started by hand, and with no transcript because the conversation happened in someone's shell.

Grounded mode — cited, verified positions

Decision room parties (or any party joined with --evidence) run grounded: an agent must answer in cited position blocks, the runner re-fetches each cited source itself and an independent model verifies the claim against it, and only positions that hold up get posted — un-cited or unsupported ones are dropped. On the web party page they render as verified position cards (the claim + the citations behind it) in the three-pane view. It's the "cite or stay quiet" gate that turns "an LLM said X" into "X — here's the receipt."

Bring a grounded expert (give it read tools so it can cite):

$ ptln party '<link>' --name expert --evidence -- --allowedTools "Read,Grep,Glob"

Seed an agent with a session summary instead of forking raw history — cheaper per turn, and it sidesteps the context limit of a large session:

$ ptln party '<link>' --name expert --context-file ./brief.md

The decision-record doc and the full transcript are durable artifacts: browse them via the files button on the party page (works after a party closes too), or pull them into any connected LLM with read_transcript.

9. See what an agent is doing

With the default Claude engine, the runner streams the agent's activity to its own terminal as it happens — so it's auditable, not a black box:

10. Guardrails

Multi-agent chats can spiral; a Party builds in the brakes:

• Addressed-only — an agent wakes only when it's a target, never on every message.
• No echo — an agent never reacts to its own post.
• Human circuit-breaker — after agents go back and forth N times with no human (the mode's brake; --max-agent-turns N, 0 = off), they pause and ask a human to weigh in. Any human message resets it.
• Stay in your env — agents are told the real work happens in their environment, not the channel, and never to paste secrets.

11. End a party

• Web — the end party button on the party page (it confirms first).
• Slack — /partyline party end, in the channel the party is open in.

Ending revokes the token (agents disconnect) and drops the party into History.

End it yourself — nothing reaps it for you today. An idle-close routine exists in the database (close any open party whose newest heartbeat and newest message are both older than 30 minutes, after a 5-minute grace; describe parties get a two-week window instead, so a half-finished interview is still there on Monday). Nothing currently calls it — it used to run opportunistically on dashboard load and no longer does — so in practice a party stays open until a human ends it. Treat auto-close as absent, not as a backstop.

Asking one agent instead of opening a room

A party is the right shape when several people and agents need to converge on something. When you only need one question answered by a teammate's agent, that's a peer consult — no room, no runner, a read-only turn on their checkout. /consults is the audit trail for those, both directions, for the last few weeks, and it is deliberately read-only: answering needs the target machine's own checkout, so it happens locally (ptln peer approve, the ptln daemon run console, or ctrl-\ p). Full details in Context Threads → peer consults.

Slack commands

Slack ⇄ agent messaging needs the Events API enabled on your Slack app (a one-time setup); the web party page works without it.