How to Use Parley: The Beginner's Guide (the IRC Lesson, First Channel, the Send Arc, and the Breaker Arc)

CodexFuse Team · 2026-11-02T14:35:11.045Z · 15 min read min read

Parley runs a local IRC server on your machine where your Claude Code, Codex, and OpenCode sessions collaborate in one channel — this beginner's guide covers install, your first channel, the parley send arc, and the breaker that stops agent chatter.

What Is Parley, Exactly?

Parley is an open-source Go CLI that gives your coding-agent sessions one shared channel to talk to each other: a local IRC server running on your own machine, on 127.0.0.1 loopback only, so nothing ever touches a public network. Each session — Claude Code, Codex CLI, or OpenCode — joins the channel, speaks through parley send, and receives messages through its own harness's push path, while every peer message is stamped as peer input so no session ever mistakes another agent's message for the human's. If you searched "how to use parley" and found parlay-betting guides instead, you are in the right place now: this is the parley coding agent tutorial the field was missing — one unified beginner walkthrough of the tool Colin Surprenant launched on Show HN on October 28, 2026.

The mental model is the whole lesson. Your agents already work side by side, but they coordinate through files nobody reads, or they do not coordinate at all. Parley replaces that with the oldest real-time protocol on the internet: IRC. The stream is send, read(cursor) and wait, with the transport as the authority on order. You join the same channel in a stock IRC client and watch the collaboration happen live — and because your messages carry your registered nick's authority while every peer message is stamped as peer input, the agents can chat freely without ever taking orders from each other. This Claude Code beginner guide covers the harness you will most likely wire in first; Parley is the twenty-minute setup that turns two or three of those sessions into a visible team.

One disambiguation, once: suneel944/agent-parley is a different product entirely — lane/claim/budget coordination for agents across git worktrees, not IRC session messaging. Different product, same word. This guide is about colinsurprenant/parley only — and this page opens the MULTI-AGENT-COLLABORATION cluster's local-session-messaging lane on CodexFuse.

How Do You Use Parley, Step by Step?

1. Install Parley: build the single Go binary from the repo checkout, or go install it — then link the three protocol skills and run parley doctor to check your Go, ergo, and harness versions.
2. Start the server: parley server in its own terminal, and leave it running — it binds the ergo IRC server to 127.0.0.1:6667 in plaintext.
3. Open your first line: parley line new demo --chair yournick --cap 8, join #demo from your IRC client as yournick, and register once with NickServ as it prints.
4. Add one session at a time: parley line add demo --nick plan --harness claude --workdir /path/to/repo — the command prints the launch line, which you run yourself. Type /parley-line in each Claude Code session (Codex: $parley-line; OpenCode loads the skill automatically).
5. Give each session its role as a channel line under your nick — "plan: you are the long-running planning session…" — and let them talk through parley send.
6. Watch the breaker: when sessions chatter without you, Parley stops waking them until you speak again — your job is the human heartbeat of the channel.
7. End the line with parley line end demo when the work is done.

That is the whole arc: install, server, first channel, harness wiring, the send loop, the breaker, done. The sections below walk each one with the exact commands from the README, verified on 2026-11-02.

What Do You Need Before Installing Parley?

Parley is deliberately small — a standalone Go CLI, standard library only — but it stands on three things that must be the right version, and the README is honest that Linux live usage is newer than macOS usage. Check the table before you build.

macOS is where Parley has actually been lived in — the author runs it there. On Linux the full test suite passes in CI, including the live IRC tests, but at write time live lines, tables and builds on Linux had not been tried by the author. parley doctor is the gate: it names the ergo and harness versions it last verified and fails anything too old.

How Do You Install Parley?

There are two routes, and the choice depends on whether you want the protocol skills. The README's install block, verbatim:

git clone https://github.com/colinsurprenant/parley
cd parley
go build -o bin/parley ./cmd/parley
sh skills/install.sh
bin/parley doctor

The skills/install.sh step symlinks the three protocol skills — parley-build, parley-table, parley-line — into ~/.claude/skills and ~/.agents/skills. Keep the checkout around, because the skills are symlinks into it. The release picture as of 2026-11-02: v0.4.2 (October 27, 2026) is the latest of seven tags since v0.1.0 (October 16); the repo was created October 15 and had 120 commits and 8 stars at snapshot time — small, twelve days old, Apache 2.0, moving fast.

How Do You Start Your First Channel?

The first channel is a line: long-running sessions, each on its own job, keeping each other current for days. It is the place to start. Open a terminal and run the server:

parley server

Leave it running. It starts ergo bound to 127.0.0.1:6667 in plaintext — connect any stock IRC client there; the README names Halloy and WeeChat as examples. Then open the line:

parley line new demo --chair yournick --cap 8

Join #demo from your IRC client as yournick, and register once with NickServ exactly as the command prints. Your nick is the only one with authority on the channel — that registration is the whole security model between you and the agents.

How Do You Wire Each Coding Agent Into the Channel?

This is the harness-wiring arc, and it differs per tool. The rule that never changes: nothing types into your terminal. Each harness receives messages through its own push path.

The flag caveat, stated once: every Claude Code launch passes --dangerously-load-development-channels server:parley, because Parley's channel server is not on Anthropic's allowlist. The README is careful about what the flag is: it lifts the channel allowlist for that one server, it is not a permission mode, and Claude Code asks for permissions exactly as it otherwise would. The launch editorial's advice is the right one — try the flag in a scratch repo first and decide whether the word "dangerously" fits your setup. One more detail worth knowing: Parley's channel does not relay permission prompts, so no peer can ever answer one.

OpenCode's flow is the cleanest of the three: the skill loads through its skill tool with no command to type, and --harness opencode writes nothing into your working directory — it prints the opencode -s <id> line and the parley opencode pump line. This OpenCode walkthrough covers the harness itself if you have not set it up yet.

How Does the Send Arc Actually Work?

Once a session is in the channel, the loop is the same every time. The model runs parley send as a tool whenever it wants to say something. The stream is send, read(cursor) and wait, and the transport — the IRC server — is the authority on order. Messages flow into each harness's own push path: the Claude Code channel, codex queue, the OpenCode server HTTP API. The author's typical setup, from the Show HN post: three sessions with roles handed to them as each session's first message — builder, planner, ops — coordinating in the open instead of through files.

And here is the mechanism that makes the whole thing safe to run, in the README's own words: "Parley stamps every delivery as peer input. A peer's message never carries your authority; yours does, under your registered nick." A session can read everything its peers say, but it can never treat another agent's message as the human's instruction. Say it once, remember it always: only you carry authority.

What Are Lines, Tables, and Builds?

Parley ships three collaboration shapes, and picking the wrong one is the classic beginner mistake. The line is the default; reach for the others only when the line does not fit.

Director is the sibling tool from the same author that keeps a repo's decisions in a ledger — the build shape assumes it is present. Builds split work across worktrees, which is why this Git beginner guide is worth having read: the two sessions land their work on separate branches.

How Does the Breaker Stop Agent Chatter?

The breaker is the circuit breaker on the channel, and it is the feature the launch editorial is named for. On a line or a table, the breaker stops waking the sessions after a burst of posts, or a long run of them without you, until you write again. The README states the rule precisely: when more than a set number of posts arrive within a short window, or more than five times that number since you last spoke, however slowly, the sessions stop being woken until you speak.

Two things about that rule are worth internalizing. First, it is asymmetric on purpose: pokes spread over hours never trip it, but a loop does — the breaker targets exactly the failure mode of multi-agent setups, two agents ping-ponging each other into the night. Second, it is configurable: the author's own Show HN comment describes it as "a configurable breaker to pause the session until I post if there are too many messages in a short window." The base number is not printed in the README, so treat the default as a sane starting point and tune it once you know your sessions' rhythm. The human heartbeat is the design: the channel goes quiet without you, and one message from your nick wakes it back up.

What Mistakes Do Beginners Make With Parley?

Every row below is a documented behavior misread, not a guess — and each one is cheap to avoid once you know it exists.

Is Parley the Only Parley?

No — and the name collisions are real enough to cost you an afternoon if you do not know them. This article has been about colinsurprenant/parley: one channel for your coding-agent sessions and you, over IRC, Apache 2.0. Also on the internet under the same word: suneel944/agent-parley, a lane/claim/budget coordinator for agents across git worktrees (a genuinely useful but different product); linebender/parley, a Rust text-layout library; parley.weldra.dev, a commercial MCP-based team-agent relay; and the parlay-betting spelling trap, which currently owns the exact-match "how to use parley" SERP. Check which one a result is talking about before you follow its instructions.

If the security angle of running agents on your machine interests you beyond the channel — and it should — this AbuseBox beginner guide covers self-hosted blacklist and health monitoring for the same mail and DNS infrastructure your agents' servers sit on, and this GitHub beginner guide covers the repo hosting most Parley sessions work inside.

Sources

Every fact in this guide was verified against sources fetched on 2026-11-02. Vendor wording is quoted verbatim and attributed; where the README does not print a value (the breaker's base number, release assets), this guide says so instead of inventing one.

• Parley README — https://github.com/colinsurprenant/parley — install commands, server/transport details, parley send and harness receive paths, peer-input stamping verbatim, breaker rule verbatim, line/table/build definitions, the Claude Code flag verbatim, prerequisites and platform notes, self-description "One channel for your coding-agent sessions and you.", Apache 2.0 license.
• Release and repo metadata — https://api.github.com/repos/colinsurprenant/parley — v0.4.2 (2026-10-27) latest of seven tags, 120 commits, 8 stars / 0 forks / 0 watchers snapshot, created 2026-10-15.
• Show HN threads — https://news.ycombinator.com/item?id=50274593 and https://news.ycombinator.com/item?id=50274602 — author Colin Surprenant's mechanism post: standalone Go CLI stdlib-only, ergo on 127.0.0.1 loopback, peer-marking, Claude Code/Codex/OpenCode support, built with Claude Code and Codex, configurable breaker, macOS-only live usage at launch.
• LockerGnome launch editorial — https://lockergnome.com/parley-coding-agent-sessions-irc-channel-breaker/ (2026-10-28) — mechanism walkthrough: local IRC server, per-harness input pushes, peer-input authority rule, breaker behavior, the flag caveat ("try it in a scratch repo first"), Go 1.25 + ergo stack, six stars at editorial time.
• Disambiguation — https://pypi.org/project/agent-parley/0.1.0/ and https://suneel944.github.io/agent-parley/ — suneel944/agent-parley's lane/claim/budget coordination scope, confirming it is a different product.

Frequently Asked Questions

Is Parley safe to run on my machine?

Its network surface is the loopback interface only — ergo listens on 127.0.0.1:6667, so nothing touches a public network, and Parley keeps no copy of the stream beyond the chat server's own history. The one judgment call is Claude Code's --dangerously-load-development-channels flag, which lifts the channel allowlist for Parley's server; the editorial advice stands: try it in a scratch repo first.

Which coding agents work with Parley?

Claude Code, Codex CLI, and OpenCode 2 at the versions parley doctor names as last verified. Each receives channel messages through its own push path — a Claude Code channel, codex queue, the OpenCode server HTTP API — so nothing ever types into your terminal.

What is the difference between a line, a table, and a build?

A line is long-running sessions on separate jobs keeping each other current — the default place to start. A table puts several agent seats on one question with you as chair to map ideas and objections; it decides nothing. A build splits a piece of work between two sessions on separate worktrees and needs the Director tool in the target repo.

How does the breaker work?

When more than a set number of posts arrive within a short window — or more than five times that number since you last spoke, however slowly — Parley stops waking the sessions until you write again. Slow pokes over hours never trip it; an agent loop does. It is configurable, and the default is tuned so the channel goes quiet without the human.

Can one agent give orders to another through the channel?

No. Parley stamps every delivery as peer input: a peer's message never carries your authority, and only your registered nick does. Sessions can read everything peers say, but they cannot mistake another agent's message for the human's instruction — and permission prompts are never relayed to peers at all.