agent-mesh

README

Agent Mesh

Stop copy-pasting context between your AI agents. Let them talk to each other.

Run multiple AI coding agents in separate terminals across different projects, and let them query each other for project-specific expertise. No manual context-passing, no cloud, all local.

---

Demo

You ask the web-frontend agent in plain language; it routes the question to payments-api, which answers from its live context, and the answer flows back on its own, without you relaying anything between the two.

How it works

Each agent session joins a mesh: a lightweight, machine-local registry of nodes with a durable mailbox. Agents route questions to each other by project name. The target host adapter surfaces each query when that host can receive it, the agent answers from its open project context, and the correlated response returns to the asker.

Nothing leaves your machine: the mesh is local state, and each agent answers from context it already has.

Quickstart

Two commands to set up. Then you drive the whole mesh by talking to your agent, with no mesh commands to memorize.

1. Install the mesh CLI (curl / Go alternatives under Install):

go install github.com/mertbarutcuoglu/agent-mesh/cmd/mesh@latest

2. Install the plugin for your agent (Claude Code shown here; see Supported agents for the others):

/plugin marketplace add mertbarutcuoglu/agent-mesh
/plugin install agent-mesh@agent-mesh

3. Open two terminals in two different projects, start your agent in each, and just talk to it.

In the backend project, tell your agent to join as a responder:

Join the mesh myapp as payments-api in responder mode. You're the backend API expert (REST endpoints, DB schema, auth).

In the frontend project, join and ask across projects in one breath:

Join the mesh myapp as web-frontend, then ask payments-api what fields the User response returns.

Your agent routes the question, payments-api answers from its live context, and the answer comes back to your session, exactly what the demo above shows. No commands typed, no context relayed by hand.

Prefer the raw CLI? Every step maps to a mesh command; see the Command reference. The first time your agent shells out to mesh ..., the host asks for permission; choose "Always allow this pattern" and it won't ask again.

Install

The mesh binary is installed once, independently of any plugin:

# curl (downloads the release binary)
curl -fsSL https://raw.githubusercontent.com/mertbarutcuoglu/agent-mesh/main/install.sh | sh

# Go
go install github.com/mertbarutcuoglu/agent-mesh/cmd/mesh@latest

Or grab a release binary from Releases.

Updating

mesh update           # install the newest release
mesh update --check   # report the newest release without installing

mesh update replaces the binary in place when it was installed from a release archive at a writable path, verifying the download against the release checksums.txt first. For go install builds, read-only locations, and platforms with no published archive it prints the right command for your install method instead. Pin a specific release, or roll back, with mesh update --version vX.Y.Z.

Host plugins update separately, through your host's own plugin manager — see docs/PLUGINS.md.

Supported agents

Agent Mesh ships host-native plugin packages in plugins/. Each one bundles the same agent guidance (routing, asking, replying, etiquette) plus host-specific hooks and commands. Plugins never compile or install the mesh binary, and never write into your host config. Pick your host below, then see docs/PLUGINS.md for full setup, receiving-message behavior, and limitations.

Host	Install	Responder mode	Notes
Claude Code	/plugin marketplace add mertbarutcuoglu/agent-mesh → /plugin install agent-mesh@agent-mesh	✅ Monitor-backed	Prompt hook + verified persistent responder monitor + slash commands.
Codex	codex plugin marketplace add mertbarutcuoglu/agent-mesh → codex plugin add agent-mesh@agent-mesh	⚠️ Next turn	UserPromptSubmit injects queued work at the next prompt; it cannot start a turn.
GitHub Copilot CLI	copilot plugin install mertbarutcuoglu/agent-mesh:plugins/copilot/agent-mesh	⚠️ Next stop	agentStop can continue the active loop with queued work; it cannot wake a stopped session.
Cursor CLI	cursor-agent --plugin-dir plugins/cursor/agent-mesh (local checkout)	⚠️ Manual	Manual inbox inspection or one-shot terminal wait; join with --agent cursor.
Pi	pi install ./plugins/pi/agent-mesh (local checkout)	⚠️ Next turn	before_agent_start injects queued work when a turn begins.

Command reference

Command	Description
mesh join <mesh> --project <name>	Register this session as a node
mesh list / mesh ls	List meshes on this machine
mesh leave	Leave the mesh
mesh ping	Refresh this node's active session lease
mesh peers	List nodes; --json includes live delivery_mode and reachable routing data
mesh ask "<q>" --to <name>	Ask a peer; waits when reachable, otherwise queues immediately
mesh reply <msg-id> "<answer>"	Reply to a query
mesh inbox	List pending messages (--json for structured output)
mesh inbox --wait [--wait-timeout <duration>] [--responder-only]	Manual one-shot wait (55s default), then exit
mesh inbox --wait --monitor --responder-only --wait-timeout 0	Persistent line-oriented host monitor
mesh broadcast "<msg>"	Send a message to every active peer
mesh gc	Retire stale nodes and expire overdue messages
mesh contract --role ... --topics ...	Update this node's capability contract
mesh status	Show mesh + node + inbox state
mesh update	Check for a newer release and install it (--check to report only, --json, --version vX.Y.Z to pin)

Run mesh --help or mesh <cmd> --help for full flag lists. mesh runs through each host's shell tool, so the host may ask for command approval the first time; allow the mesh pattern (or Shell(mesh) in Cursor's CLI permissions) and it won't ask again.

Documentation

• docs/PLUGINS.md: full per-host plugin setup and behavior
• docs/CURSOR_CLI.md: Cursor permission setup and manual fallback

Development

go build -o mesh ./cmd/mesh
go test -race ./...

Plugin packages under plugins/ are hand-maintained: the plugin file is the canonical source. internal/plugingen holds lint tests that validate plugin manifests, enforce /agent-mesh:mesh* slash-command namespacing, and enforce cross-host skill parity: every host's SKILL.md must carry the same command-contract snippets, so editing one host's contract without the others fails CI. For a one-off external check:

claude plugin validate plugins/claude-code/agent-mesh
claude plugin validate .   # validates marketplace.json

License

MIT © Mert Barutcuoglu