agent-parley 0.9.0

Separate worktrees. Shared context. One screen.

Run several coding agents at once and know who owns what.
Every claim, handoff and refusal is recorded, attributed and visible.

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

See it

One screen for every lane: session state, branch drift, issues owned, handoffs pending, unread mail, held reservations, delivered context, what enforcement denied, and what that lane's own client recorded for its session. Read-only, no model call, q quits.

A lane reads active while it is serving coordination calls, idle once a live lane passes the inactivity threshold, and stopped only when its recorded session process is gone. A quiet lane is not a lost one. Every frame on this page is real command output from a demo project; only the state and project paths are shortened.

Monitoring covers the whole view: the columns, the keys, the filters, problems, metrics and watch.

Install

Linux, macOS or WSL2 with the repository in the Linux file system, Git, and uv. No clone. The wheel needs no third-party runtime packages.

uv tool install agent-parley
# to track the default branch instead:
# uv tool install git+https://github.com/suneel944/agent-parley

Then add the plugin to whichever CLI you drive. One marketplace serves both.

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 the shared coordinate skill, so an agent can read coordination state, claim an issue and hand work off in its own words. It is deliberately skill-only: the launcher supplies MCP configuration and lifecycle hooks per session, and it is also what creates the worktrees and runs the coordination service. The plugin alone gives an agent the skill and nothing to coordinate through.

For a pinned, checksummed install, take a wheel from Releases instead. Shell completion, upgrades and the supported platforms are in Operations.

Run it

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 that participant's worktree and branch, starts the coordination service, and hands you the native CLI. Prompt it exactly as you always do. A new name creates its own lane, so a second account of the same provider, or another provider, is one more terminal.

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

agent-parley status   # one table per project: ownership, activity, outcomes
agent-parley top      # every lane live, including what enforcement denied
agent-parley problems # only what needs you now, oldest first
agent-parley say claude-2 "Rebase onto main before you open the pull request."

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

agent-parley participant merge claude-2
agent-parley participant pr claude-2

Running lanes covers the rest of the operator surface: deferred and bulk steering, pausing, stopping and restarting a lane, the merge plan for several lanes at once, the pre-merge gate, recorded approvals, and the setup command every new lane runs.

What it enforces

• Ownership changes only through explicit claims and accepted handoffs. No timeout and no process exit moves an issue, and a recorded dependency informs rather than gates.
• 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 actually changes.
• A deadline reports; it never transfers. A budget informs; it does not gate. Both mark the lane and stop nothing.
• Reservations are advisory. Conflicts name the blocking owner and that owner's declared reason; nothing on disk is locked.
• Your history stays yours. No lane signs its work, and a commit, merge, tag or pull request that credits an assistant is denied before it lands, with no flag that skips the check.
• An out-of-date install says so before it costs a turn. The launcher, the plugin, the store and the running service each state a version, and a mismatch is refused at the boundary with the command that fixes it.

Each of these is documented in full, with the commands and the recorded evidence, in Coordination.

How it fits together

flowchart TD
    Repo[Your repository] --> Launcher[Agent Parley launcher]
    Launcher --> Claude[Participant · own worktree]
    Launcher --> Codex[Participant · own worktree]
    Claude <-->|Ten scoped MCP tools| Server[Local coordination service]
    Codex <-->|Ten 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.

What it does not do

Worktrees and reservations are coordination boundaries, not OS sandboxes. Agent Parley integrates a lane only when you run participant merge, and it never approves a command. The runtime can wake an idle lane to review pending mail, with global and per-lane opt-outs and a bounded number of attempts per backlog. Reported ready is ready for review, not verified completion. Token usage still depends on the native agents: CONTEXT reports the bytes coordination itself injects and TOKENS repeats what a lane's own client counted, and neither is billed spend or a claim about a token-saving percentage.

Documentation

Contributing

Run make check before opening a PR. It checks formatting, lint, typing, documentation rules, package builds, and behavior tests.

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