agent-parley

Agent Parley runs several coding agents on one repository, each in its own worktree, and records who owns what: every claim, handoff, wake and refusal.

curl -LsSf https://github.com/suneel944/agent-parley/releases/latest/download/install.sh | sh

Try it without an account: agent-parley demo runs the story this video is cut from, with stub lanes in a throwaway sandbox and no native CLI, model or network.

See it · Install · Run · Coordination · Monitoring · Providers · Commands · Limits

---

• Lanes keep moving without you. Idle lanes are woken, planned issues are dispatched, and a claim whose holder went silent moves to the fittest peer with its recovery checkpoint.
• Plans change inside bounds you set. A lane proposes a change with plan propose; it applies on its own only inside the plan's [revisions] envelope, and otherwise waits for plan approve.
• An optional run budget. budget enforce caps the tokens, calls or hours every lane spends together; once reached, nothing new starts until budget resume.
• Pull requests wake their lane. Finished checks, a new review or a merge conflict reach the owning lane as mail.
• Unattended integration only by policy. unattended set names the issues and the target branch; unattended run, or the service itself when the policy adds --auto, merges on the same gate as participant merge, and a failed integration holds every other merge until it is verified.
• Churn is caught per issue. An issue whose verification keeps failing is flagged in issue show, problems and a notification.
• Ownership stays explicit. Atomic claims, accepted handoffs, advisory reservations that name the blocking owner, and native hooks that refuse a branch switch before it runs.
• Readable by people and scripts. status, top and problems show what needs you; the readers take --json, and a failure prints one error document.

See it

Every terminal frame in the launch video at the top is captured command output from the shipped coordination path; only the native client is a stand-in, so no model runs. It is re-cut with docs/video. make demo-stub records the full nine-chapter walkthrough with scripts/record_demo.py; make demo records real claude and codex sessions with scripts/record_live.py.

agent-parley top reads like Linux top: three summary lines, one row per lane with its state, issues, mail, leases, denials, idle time and last prompt, and one note per problem under the table. Read-only, no model call, q quits.

A lane reads working while its session is alive and current, idle once its activity passes the inactivity threshold, and stopped only when its session process is gone: a quiet lane is not a lost one. Stopped lanes that hold nothing are counted in the summary; top --all draws them. top --serve serves the same view read-only to a browser tab and a Prometheus scraper on 127.0.0.1. Monitoring covers the columns, keys, filters, problems, metrics, the web view, watch and report usage, which lists what each resolved issue used.

Install

You need Git. No clone. The wheel needs no third-party runtime packages. One command installs everything on Linux, macOS and WSL2:

curl -LsSf https://github.com/suneel944/agent-parley/releases/latest/download/install.sh | sh

It installs uv only when uv is missing, then installs or upgrades agent-parley, adds the plugin to each of claude and codex found on PATH with agent-parley plugins install, and runs agent-parley doctor. It never uses sudo, and re-running it upgrades in place. It ends with the next command for the first of claude, codex, copilot, gemini, opencode and amp on PATH, such as Next: cd your-repo && agent-parley run gemini; only claude and codex take a plugin. With none of them on PATH it says to install one first and offers agent-parley demo.

To install by hand instead:

macOS

brew install uv
uv tool install agent-parley

Linux, or Windows through WSL2

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install agent-parley

Native Windows is not supported. On WSL2, keep the repository in the Linux file system, not under /mnt/c.

To track the default branch instead of the latest release, run uv tool install git+https://github.com/suneel944/agent-parley.

Then add the plugin to whichever of claude and codex you drive: agent-parley plugins install does it for each one on PATH, or run the commands yourself. One marketplace serves both. gemini, copilot, opencode and amp lanes take no plugin; the launcher configures them per session.

claude plugin marketplace add suneel944/agent-parley
claude plugin install agent-parley@agent-parley

codex plugin marketplace add suneel944/agent-parley
codex plugin add agent-parley@agent-parley

The plugin carries only the coordinate skill, which teaches an agent to read state, claim issues and hand work off. The launcher does the rest: worktrees, the coordination service, and per-session MCP configuration and hooks. The plugin without the launcher has nothing to coordinate through.

For a pinned, checksummed install, take a wheel from Releases instead. Checking install.sh against the release SHA256SUMS before it runs, shell completion, upgrades and the supported platforms are in Operations.

Run it

Not sure where to start? Run agent-parley with no arguments in the repository. It reads, and writes nothing: whether this is a Git checkout, whether it has a first commit and uncommitted changes, whether the project is registered, which of the six providers are on PATH and, for claude and codex, the only two that take a plugin, whether each has it, and whether the coordination service is running. It then names the next one to three commands for exactly that state, such as agent-parley plugins install, agent-parley run claude or agent-parley top, or agent-parley demo when no native CLI is installed. A checkout with no commits yet puts git commit first, and one with uncommitted changes puts git status first, because lanes start from the last commit.

Agent Parley coordinates native coding CLIs in one repository.

Found:
  Here      Git repository, clean
  Project   not registered
  CLIs      claude (plugin added), codex (plugin added)
  Service   not running

Next:
  agent-parley run claude  Register the repository and start a lane.

Full reference: agent-parley --help

Once the project is registered and its service runs, the screen also reads what agent-parley problems would list. A line such as Needs you 2 problems: … gives the count and the two most urgent rows, and agent-parley problems then leads the next commands. With lanes but no outbound notification transport, or one missing a setting it needs to send, a Notify off line appears and agent-parley notify setup joins the next commands. A project with nothing pending shows neither line.

From a committed, clean checkout, one terminal per agent:

# Terminal 1
agent-parley run claude

# Terminal 2
agent-parley run codex

That is the whole setup. The first run registers the repository, creates the lane's worktree and branch, starts the coordination service and hands you the native CLI.

Lanes start from the last commit. A repository with no commits yet cannot start one: setup and run stop with "This repository has no commits yet" and suggest a first commit. If the checkout has uncommitted or untracked changes when the project is first registered, they are stashed, not discarded, and the command prints the git stash apply <entry> line that restores them; run in a terminal prints it again after the native CLI exits. Until the entry is dropped, agent-parley in that checkout lists it as Stashed git stash apply <entry>. Commit first to carry the changes into the lanes.

Prompt the native CLI as you always do. Another account or provider is one more terminal. Each tab title names its lane, state and progress, such as [codex] idle with claim #412 - 2/5 done; the supervision key titles turns this off, and agent-parley title prints the same line for a Claude Code status line. agent-parley run codex --issue 412 claims issue 412 for the lane and opens it with the issue's text already read from the forge.

Then watch the work, and steer a lane without taking over its terminal:

agent-parley status   # this project's open work: issue, owner, state, PR
agent-parley top      # every lane live, including what enforcement denied
agent-parley problems # only what needs you now, oldest first
agent-parley say codex "Rebase onto main before you open the pull request."
agent-parley ask codex "Which test is still failing?"  # read-only, lane untouched

Work across several repositories, such as a front end and a back end, from one terminal. Every project you set up or run in is remembered in the state root, never in the repository, and a named workspace groups them:

agent-parley projects                      # registered projects, recent first
agent-parley run codex --project backend   # launch there, not in the cwd
agent-parley workspace set stack frontend backend
agent-parley up --workspace stack          # resume the stopped lanes of both
agent-parley status --workspace stack      # both projects in one view

Each project keeps its own claims, reservations and integration target; lanes stay on the local host.

agent-parley --help prints the grouped command list; agent-parley version prints the version and state directory. Single records read through show: issue show 42, participant show codex, provider show claude, credentials show work, and each of those, like status, top and problems, accepts --json. The mail readers take --as NAME, so you can open a lane's mail from the main checkout without acknowledging or marking anything for it.

Mail never blocks work: it arrives as context, most relevant first. A tool call is refused only when it is unsafe now, such as a write to a path a peer reserved or a git worktree add outside the lane's <lane>-wt/ directory. Broadcasts reach only the lanes they concern, and a newer note on a topic replaces the older one.

When a lane's work is ready, integrate it from the base checkout, or send it for review:

agent-parley participant merge codex
agent-parley participant pr codex

With pull_request.self_service on in the private project settings (off by default), a lane opens its own pull request once it has reported ready, passed the gate, stayed on its assigned branch and touched no peer's reservation. Each such pull request records what authorized it. Merging stays an operator step: participant merge, or unattended run for the issues a recorded unattended policy lists, which the service runs itself only when that policy was recorded with --auto.

Merged lanes are reclaimed by the service on its own; agent-parley gc runs the same sweep on demand:

agent-parley gc           # what would be reclaimed, and what is kept and why
agent-parley gc --apply   # reclaim the lanes whose work has landed
agent-parley gc --apply --force  # also dirty lane-made worktrees, checkpointed
agent-parley gc --project ROOT --apply  # drop a gone root's project state

A lane is reclaimed only when it is idle, holds no claim, has nothing uncommitted or unpushed, and its pull request merged or its branch is gone. Every kept lane is reported with the reason. A stray worktree is moved into the project state directory first, never deleted by the move, and uncommitted work is removed only with --force, after a recovery checkpoint. A quiet lane-made worktree whose unpushed commits already landed through another branch is removed without --force, its commits bundled into a recovery checkpoint first.

A lane that crashed, hung or lost its host comes back with one command:

agent-parley participant restart codex

A restart is refused while the session is alive and current; one silent past inactive_after is ended first. The lane's claims go into a recovery checkpoint, uncommitted work stays in place, and the new session starts in the same worktree. After a host restart every lane reads stopped and restarts the same way.

Running lanes covers bulk steering, pausing, merge plans, the pre-merge gate, approvals and lane setup.

What it enforces

• Ownership moves only through claims, accepted handoffs and one recorded recovery path. A process exit moves no issue. A lane holds at most max_claims_per_lane claims, two by default.
• Choosing work is a reading, not a guess. agent-parley issue next ranks the unclaimed, unblocked issues with a reason for each, and claims nothing.
• A lane suggests follow-up work; only you file it. Mail to @followup records the idea with its likely duplicates and the lane keeps working. agent-parley followup accept ID files the issue in the active milestone and offers it to an idle lane; followup list shows what waits.
• Native hooks decide before the tool runs. They block branch changes inside an assigned lane, catch drift after any bypass, and deliver bounded updates only when coordination state changes. A prompt you type is never refused; only a tool call is, naming the lane path to return to.
• A stalled claim moves in steps. It gets one wake, then an offer to the fittest peer with its recovery checkpoint, then release to the pool. A claim whose pull request already ended is never moved; agent-parley issue resolve closes it with the forge evidence. Only the opt-in run budget gates: it stops new wakes, dispatch, retries and launches until agent-parley budget resume.
• Reservations are advisory. Conflicts name the blocking owner and that owner's declared reason; nothing on disk is locked.
• Mail stays private; a decision does not. A message marked as a decision, or recorded with agent-parley decide, enters a project-wide log every lane can search, so settled questions stay settled.
• Your history stays yours. A commit, merge, tag or pull request that credits an assistant is denied before it lands. No flag skips the check.
• A stale install says so before it costs a turn. Launcher, plugin, store and service each state a version; a mismatch is refused with the command that fixes it.

Coordination documents each rule with its commands and evidence.

How it fits together

flowchart TD
    Repo[Your repository] --> Launcher[Agent Parley launcher]
    Launcher --> Claude[Participant · own worktree]
    Launcher --> Codex[Participant · own worktree]
    Claude <-->|Seventeen scoped MCP tools| Server[Local coordination service]
    Codex <-->|Seventeen scoped MCP tools| Server
    Server --> DB[(SQLite WAL · mail and reservations)]
    Claude --> Claims[Atomic issue claims and handoffs]
    Codex --> Claims
    DB --> Hooks[Native checkpoints · bounded updates]
    Claims --> Hooks
    Hooks -.-> Claude
    Hooks -.-> Codex

The coordination engine is built in-house with Python's standard library. It has no runtime dependencies and makes no model calls. Your existing logins and permission settings still apply.

Notifications when you step away

Agent Parley can forward the moments that need you to a Telegram bot, an email address, or a Slack, Discord, Teams or other HTTPS webhook. Email and webhooks are outbound only. The Telegram bot can also take status queries and decision answers back once inbound is on, as described in Asking for status from the chat. With inbound off, nothing arrives over the channel and a permission prompt is answered only in your terminal.

Fourteen changes notify: a handoff offered to a lane, a lane blocked on a permission prompt, a lane's tool call denied by its native permission check, a lane held by a native dialog, a lane still blocked past the escalation bound, a lane idle with no claim past stalled_after, issues waiting on an idle claim, a dead lane's claims waiting on your decision, a lane keeping a key refused to a peer past its deadline, an issue that is not converging, the enforced run budget running out, a lane run that finished, a hook refusal, and the inbound status path locking after repeated wrong passcodes. An unchanged situation sends nothing further. Sending never blocks a hook or tool call. Each of these situations is kept as a decision with a stable identifier, its options and a recommended one. So is each operator-owned agent-parley problems row younger than a day for an unresolved completion, an unacknowledged message, a bounced share, shares to a retired lane, a dirty worktree, a refused key still held, a second session, a refused recovery, an unverified integration, a wake needing attention, a wait on approval, a native dialog hold or a crossing ready, and those decisions are sent the same way. Nothing else notifies. A decision is retried with backoff on the next supervision poll until every transport accepts it, so a send cut short by a hook exiting still arrives. Decisions due together go out as one digest with one row of Telegram buttons each.

Store the Telegram settings once, and the service, hooks and lanes all read them. The token is read from a hidden prompt, or from standard input when piped, and is written owner-only to notify.json in the state directory; add --inbound to also store the status passcode. Environment variables still work and override a stored value for one process. agent-parley status, doctor and up say whether outbound and inbound are on, and why not.

agent-parley notify setup --chat 123456789
agent-parley notify test

export AGENT_PARLEY_NOTIFY=telegram,email
agent-parley notify test

A webhook receives one JSON POST per message. text suits Slack and Teams incoming webhooks, content suits Discord, and subject and body suit any other receiver. The URL is read from a hidden prompt or standard input, the signing secret from the next line, and both are stored owner-only beside the Telegram settings; the webhook is added to the transports already stored. Neither notify test nor an error ever prints the URL.

agent-parley notify setup --webhook   # paste https://hooks.slack.com/services/...
agent-parley notify test

notify test sends one message per transport, prints each answer and exits 1 when any transport refuses. With inbound configured it also says whether the running service is long polling Telegram.

Asking for status from the chat

The same Telegram bot takes two things back: status, with the filters agent-parley status takes, and answers to decisions. Tap a decision's button, send decide ID OPTION [NOTE], or reply to a one-decision message with the option and a note. The answer is recorded once, the message is edited to say who chose what and when, and the waiting lane gets it as mail that wakes it. A second answer is refused with the first one's name. An irreversible option needs a confirming tap. A note reaches the lane quoted, never as an instruction. A native prompt holding a lane, such as a tool permission or a question picker, arrives as a decision with the options the screen draws; the launcher presses the chosen option only while that same prompt is still on screen, and an option that widens a permission needs a confirming tap. No other text is typed into a session. The service long-polls the Bot API, so no port is opened and no webhook is registered.

Every typed message starts with a passcode, and both the passcode and the chat identifier must match. A button tap is accepted only from the configured chat and only for an open decision this state root issued:

hunter2-and-then-some status --pending
hunter2-and-then-some status codex
hunter2-and-then-some status --provider claude --issue 14
hunter2-and-then-some decide 3f9c2a1b7e40 decline wait for the rebase

The bot token and chat identifier are the outbound ones above. A wrong chat or passcode gets silence, not a hint. Five wrong passcodes in ten minutes lock the inbound path for an hour and send one notification. Only a salted hash of the passcode is held, compared in constant time and never stored or logged. The accepted message is deleted from the chat when the bot has permission.

With the passcode unset or short, the reader refuses to start and agent-parley status says so:

Notify: outbound on (telegram); inbound off: AGENT_PARLEY_INBOUND_PASSCODE must
be set and at least 12 characters; inbound status queries are off.

What it does not do

• No sandbox. Worktrees and reservations are coordination boundaries, not OS isolation. If you need isolation, a container tool such as container-use provides it; Agent Parley does not, and does not integrate with one.
• No silent merges. A lane integrates only through participant merge, or unattended run for an issue a recorded unattended policy lists; with --auto the service runs it and mails the lane every decision.
• No approvals on your behalf. Two opt-ins exist: approve_bridge_tools allows this project's own MCP tools in every CLI's own per-server allow except Amp's, which has none, plus the CLI run as one plain command in a claude lane, and auto_mode starts the claude client's own auto permission mode, whose classifier still decides each command. Record either with agent-parley approval resume --bridge-tools on or --auto-mode on. A CLI call combined with a variable, cd, ;, &&, a pipe or a redirect is refused with that one-command rule instead of stopping on a prompt.
• No unbounded wakes. Waking an idle lane for mail, pull request changes or authorized work has opt-outs, a bounded attempt count and the optional run budget.
• ready is not done. A ready report means ready for review, not verified completion.
• No token-saving claims. CONTEXT counts the bytes coordination injects and TOKENS repeats what a claude, codex, copilot, gemini or opencode lane's client counted; amp lanes report no token count. Neither is billed spend.

How it compares

Every tool below runs several coding agents at once, each in its own Git worktree. The difference is what happens between the worktrees. Each claim is taken from the project's own documentation, linked so you can check it.

None of them documents a searchable decision log shared by every lane, or a refusal to let an assistant sign your commits.

Hosted agents and container isolation answer a different question: where one agent runs, rather than how several share a repository.

Conductor is the smoother macOS app, and a board reads faster at a glance. Pick Agent Parley when several agents share one repository and "who owns this, on what evidence" must be recorded, not remembered.

Documentation

Contributing

Run make check before opening a PR: formatting, lint, typing, documentation rules, package builds and tests. A minor or major release also needs tests/test_fault_acceptance.py passing on the release commit.

Contributing · Architecture · Operations · Security · Code of Conduct · MIT license

Tried it? Questions, rough edges and setups worth showing are welcome in GitHub Discussions.