Meshaway

Protocol bridge that connects the GitHub Copilot SDK to ACP agents (Gemini CLI, OpenCode, etc.).

What is this?

Meshaway sits between your app (using the Copilot SDK) and any Agent Client Protocol (ACP) agent. You talk to the SDK as usual; the bridge translates requests to ACP and streams responses back, so you can use Gemini, OpenCode, or other ACP agents without changing your integration. Optionally run meshaway hub to get a small web UI to inspect sessions and try prompts in a playground.

Requirements

• Node.js 20+ (for the bridge and Hub).
• An ACP agent on your PATH or via your runtime (e.g. gemini, opencode). See the list of ACP agents.
• Some agents need API keys or auth (e.g. Gemini); set them as you would when running the agent directly.

Quick start

1. Install (macOS / Linux)

brew tap offbeatport/meshaway
brew install meshaway

2. Use with Copilot SDK

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  cliPath: "meshaway", // or path to binary, e.g. "./release/meshaway"
  cliArgs: [
    "bridge",
    "--agent",
    "gemini",
    "--agent-args",
    "--experimental-acp --model gemini-2.5-flash-lite",
  ],
});

await client.start();
const session = await client.createSession();
await session.send({ prompt: "Hello!" });

More in the examples folder. Use any ACP agent.

Adapters

Only the GitHub Copilot client adapter is supported right now. If you’d like another adapter, please open an issue.

Hub

Run meshaway hub to start the Hub on http://127.0.0.1:7337. The UI lets you:

• Sessions — List and inspect bridge sessions, view frames (prompts, assistant messages, tool calls), and export or delete sessions.
• Playground — Try prompts against a configured ACP agent (e.g. Gemini, OpenCode) without writing code; pick a preset and chat in the browser.

| Sessions | Playground | |----------|------------| | | |

Sessions

On the bridge sessions are kept in memory only: the bridge tracks session ids (SDK session ↔ agent session) and frames (e.g. prompts, ACP session/update events). Nothing is written to disk, so when the bridge process exits, that state is gone.

If you point the bridge at a Hub (--hub-url <url> or MESHAWAY_HUB_URL), the bridge syncs activity to the hub: it reports session start, each frame (prompt, assistant update, etc.), and session end. The hub stores that replica so you can open the Hub UI and see sessions and their frames. When you use the Playground in the Hub, it starts a bridge with MESHAWAY_HUB_URL and MESHAWAY_RUNNER_SESSION_ID so all frames for that run show up under one “runner” session in the UI.

Commands

| Command | Description | | -------------------------------- | ------------------------------------------ | | meshaway hub | Start Hub (monitor sessions, playground) | | meshaway bridge --agent <name> | Start Bridge in stdio mode for Copilot SDK |

Bridge options: --agent <cmd>, --agent-args "<space-separated flags>", --hub-url <url>, --log-level <level>.

Environment variables

| Variable | Used by | Purpose | | ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------ | | MESHAWAY_HUB_URL | Bridge | Send session/frame updates to this Hub URL (same as --hub-url). | | MESHAWAY_RUNNER_SESSION_ID | Bridge (when run from Hub Playground) | Report all frames under this session id so the Playground UI shows them. |

Limitations

• No persistence: Sessions and conversation history exist only in memory. After the bridge (or agent) restarts, context is gone; resumeSession reuses the session id but the agent starts with a new context.

Quota and API errors (e.g. “daily quota exceeded”) come from the agent or its provider; the bridge only forwards them.

Roadmap

If you have ideas to prioritise, feedback, or questions, please open an issue.

License

Apache-2.0