agent-parley 0.1.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 · Enforce · Filter · Providers · Docs · Limits

See it

Launch a lane, see who owns what, watch every lane at once, narrow to one provider, and watch a hook refuse a branch switch inside an assigned lane.

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

Every frame on this page is real command output from a demo project. Only the state and project paths are shortened.

Install

Linux with pidfd support, 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-local

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

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.

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:

agent-parley credentials add account-2 --config-home ~/.claude-account-2
agent-parley run claude-2 --provider claude --credentials account-2

Then watch the work:

agent-parley status   # ownership, activity and reported results
agent-parley top      # every lane live, including what enforcement denied

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

agent-parley participant merge claude-2

It always records a merge commit, refuses on a running session, a dirty tree or a drifted lane, and leaves a conflict in place for you to resolve. It never resets, cleans, stashes or force-switches.

What it enforces

Ownership changes only through explicit claims and accepted handoffs. No timeout and no process exit moves an issue. agent-parley status reports who owns what, which handoff is waiting on an offer ID, and any lane that left its assigned branch. An owner can record that one issue waits on another with agent-parley issue block 42 --on 17; the listing then names who holds the blocking issue, and every lane sees the change at its next checkpoint. A recorded dependency informs, it does not gate.

Native hooks decide before the tool runs. They block branch changes inside an assigned lane, catch drift after any bypass, and deliver short updates only when coordination state actually changes. Each notice is capped at 1,536 UTF-8 bytes; an unchanged checkpoint adds no context at all.

Seven scoped MCP tools carry the coordination. Conflicting reservations grant nothing and name the blocking owner with that owner's declared reason. Sends need an idempotency key, so a retry returns the original message instead of a duplicate. Fetching an inbox never marks a message read.

Enforcement is recorded, not discarded. Every hook decision carries an enumerated reason and lands in that participant's event log; every served call is recorded inside the transaction that carried its effect. That is why top can show what was denied, to whom, and how often.

That history is bounded, and it can leave the state directory. A lane keeps two event files and discards records older than fourteen days, so top reports recent enforcement rather than the whole project. --since narrows any count to a window, and events export writes the retained records as JSON Lines you can keep for as long as you need:

agent-parley top --since 6h
agent-parley events export --since 7d --output enforcement.jsonl

Watch one provider

With a dozen lanes open, the whole table is rarely what you want. --provider narrows the view to the participants driven by one provider, and the header counts only the rows it shows:

agent-parley top --provider codex
agent-parley top --provider claude --provider codex

Providers and accounts

A provider states which native CLI drives a participant and how that CLI reaches a model. Every provider drives one of two adapters, which is why two plugin installations cover all of them:

claude and codex work out of the box. The deepseek, kimi and grok presets carry no endpoint, so their base URL and key must be exported in the launching shell; the launcher refuses to start when a required variable is unset rather than falling back to another account. Coordination state records variable names and config directories, never credential values.

Credential profiles point a provider's config-home variable at a separate directory, so one provider can run under several logins. Up to 32 participants per project.

How it fits together

flowchart TD
    Repo[Your repository] --> Launcher[Agent Parley launcher]
    Launcher --> Claude[Participant · own worktree]
    Launcher --> Codex[Participant · own worktree]
    Claude <-->|Seven scoped MCP tools| Server[Local coordination service]
    Codex <-->|Seven 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 Bridge does not merge branches, approve commands, or wake idle agents. Reported ready is ready for review, not verified completion. Token usage still depends on the native agents; the bridge reports injected bytes rather than claiming a token-saving percentage.

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