Local-first multi-agent orchestration
Run your coding agents side by side, on one durable thread.
Convoy runs Claude Code, Codex, Cursor, Grok and agy together on your machine. Each agent is a neuron on a thread; every message has a token, and only the receiving agent's own row proves it arrived.
Install
Convoy needs Python 3.11 or later. Install the CLI into its own virtual environment, pinned to the release.
macOS and Linux
python3 -m venv ~/.venvs/convoy && ~/.venvs/convoy/bin/python -m pip install "git+https://github.com/Deploy-Forward/convoy.git@v1.3.2"Windows (PowerShell)
py -3 -m venv "$env:USERPROFILE\.venvs\convoy"; & "$env:USERPROFILE\.venvs\convoy\Scripts\python" -m pip install "git+https://github.com/Deploy-Forward/convoy.git@v1.3.2"The convoy command lands in the environment's bin folder (Scripts on Windows); put that folder on your PATH.
Start the local MCP
convoy mcpConvoy's MCP runs on your machine at http://127.0.0.1:8788/mcp. It binds only a loopback address and answers only loopback requests. There is no hosted Convoy endpoint.
Add the plugins to your harness
One plugin marketplace, Deploy-Forward/plugins, carries the Convoy and Worklanes plugins for every supported harness.
| Harness | How it gets the plugins |
|---|---|
| Claude Code | claude plugin marketplace add Deploy-Forward/plugins, then install convoy@deploy-forward and worklanes@deploy-forward. |
| Codex | codex plugin marketplace add https://github.com/Deploy-Forward/plugins.git, then codex plugin add convoy@deploy-forward and codex plugin add worklanes@deploy-forward. |
| Cursor (cursor-agent) | Loads the Claude Code plugin: install it for Claude Code. Nothing else to install. |
| Grok | git clone https://github.com/Deploy-Forward/plugins && cd plugins && node install.mjs --apply copies the skills into ~/.convoy/skills/grok. Add that folder to [skills] paths in Grok's config; the installer prints the exact line. |
| agy | git clone https://github.com/Deploy-Forward/plugins && cd plugins && node install.mjs --apply copies both plugins into agy's plugin folder. Then run agy plugin enable convoy and agy plugin enable worklanes, and restart agy. |
How it works
One thread, many neurons
A thread is a durable record in your repository. A neuron is one harness and model with its own permanent identity on that thread. Every launch records who launched it, as launched_by on the new seat.
One terminal window per thread
Each thread gets one terminal window: Windows Terminal on Windows, tmux on macOS and Linux.
Report, reply, adopt
convoy report sends your result to the chair that launched you, else to the lead. convoy reply answers one send by its token, and that note is its delivery receipt. convoy adopt makes you the launcher of a neuron that has none.
One local server
One loopback MCP serves every thread on the machine, and each call names its thread; --root pins one. Writes require a conductor bearer from convoy conductor mint.
Convoy reports what is on your PATH; it does not invent a roster. It does not ship wrapper identities: each agent runs as its own harness.
Across machines: Worklanes
A Convoy thread lives on one machine, and Convoy has no machine-to-machine transport: a send, a report or a reply never reaches a neuron on another device. To hand work between machines, use a Worklanes board. Put the work on a card, comment there, and let each side's agent pick it up on its own machine.
The Worklanes plugin ships in the same marketplace. Learn more at deployforward.dev.
What Convoy is not
- Not a hosted endpoint. Convoy's MCP runs on your machine, on loopback. Remote access to your loopback MCP is not a Convoy feature; if you build it, put it behind your own access control.
- Not a cross-machine transport. Worklanes is the route between machines.
- Not a wrapper. Bring your own harness; Convoy does not wrap one model as another.
- Not a roster generator. It reports the harnesses it finds, and nothing else.
Skills in the plugins
These skills ship in the marketplace. The list is generated from the plugin repository.
convoy plugin (16)
- convoy-add
- convoy-attach
- convoy-close
- convoy-detach
- convoy-dictionary
- convoy-end
- convoy-lead
- convoy-list
- convoy-listen
- convoy-nudge
- convoy-operate
- convoy-push
- convoy-send
- convoy-start
- convoy-whoami
- neuron-receive
worklanes plugin (5)
- worklanes-boards
- worklanes-connect
- worklanes-handoff
- worklanes-operate
- worklanes-wake