Agent Squad

Built on the Agent-to-Agent (A2A) protocol, Agent Squad connects your assistant to all your agents in chat apps like iMessage and WhatsApp through a single MCP server.

Agent Squad runs as a persistent macOS app. It keeps your agent directory and conversations in one place, exposes a single MCP server, and can connect that server to ChatGPT through a tunnel.

How it fits together

Your assistant ── MCP ── Agent Squad kernel ── Surface libraries ── Agents
                              │
                        macOS desktop app

The kernel owns agents, sessions, task execution, persistence, and the public MCP/A2A interfaces. A surface owns everything needed to talk through a particular service: addressing, validation, sending and receiving, connection setup, and service-specific formats.

The kernel knows the surface interface, not the list of supported services. Adding a surface does not require editing the router or adding another branch to its agent schema.

Related MCP server: mcp-whatsapp

Supported surfaces

Agents describe their own skills. Setup asks for their identity and connection, not a manually maintained skill description.

Agent-to-Agent Protocol

Agents that already implement the A2A protocol can connect directly by URL. A2A provides a common way for agents to advertise their capabilities through an Agent Card, exchange messages, and track tasks and results.

Add an agent using its A2A URL. Agent Squad discovers its Agent Card, validates the advertised endpoint, and handles A2A 0.3 or 1.0 JSON-RPC communication. The agent joins the same squad and is available through the same MCP server as your messaging-based agents.

To expose your own agent over A2A, follow the setup guide for your agent:

• Hermes A2A setup: enable the A2A gateway platform and publish an Agent Card with your agent's skills and reachable URL.

• OpenClaw A2A setup: enable the A2A channel, configure its advertised URL and peer access, and choose which agents appear in its Agent Card.

The A2A library owns discovery, protocol-version handling, remote task status, and reply normalization, keeping those details out of the kernel.

Try it locally

For the full app, you need macOS 14+, Node 22+, a Swift toolchain, and Xcode with Icon Composer for the app icon. A stable Apple Development or Developer ID signing identity is needed for an installed build.

npm ci
npm run check
npm run app
npm run app:install
open "/Applications/Agent Squad.app"

Quit the app before installing an update. The bundle includes Node and its dependencies, so users do not need a separate Node installation to run it. For signing, SDK overrides, or a disposable unsigned development build, see development.

For kernel and surface development, Node is enough:

npm ci
npm run check
AGENT_SQUAD_DATA_DIR=/tmp/agent-squad-dev AGENT_SQUAD_PORT=0 npm run dev

The standalone gateway prints its local port on startup. Use an isolated data directory so development does not touch your normal agents or linked accounts.

Connect your squad

1. Open Settings → Connectors and enable the surface you want to use. iMessage needs Messages automation and Full Disk Access; WhatsApp uses a linked-device QR code.

2. Open Agents → Add and choose a surface. Add your agents, then open one to send a task. Return sends; Shift–Return adds a line.

3. Connect an MCP client using the endpoint in Settings → MCP, or configure Settings → ChatGPT Tunnel.

Adding a WhatsApp or A2A agent currently sends a profile-image request, visible in Activity. iMessage uses a local Contacts photo or business logo. See setup and behavior for details and connector limitations.

Repository structure

libraries/
  kernel/                 Shared models, surface contract, registry, router,
                          storage, MCP and public A2A server
  surfaces/
    imessage/             Transport, validation, native Contacts/permissions/UI
    whatsapp/             Pairing, conversations, bot messages, QR/picker UI
    a2a/                  Discovery, protocol translation, task replies, URL UI
gateway/                  Process entry point, surface registration, tunnel host
macos/Sources/AgentSquad/  Shared SwiftUI shell and native surface registration
examples/echo-surface/    Small working surface with no external service
scripts/                  Workspace build, app packaging, signing and installation
docs/                     Architecture, extension guide, setup and development

Each TypeScript library is an npm workspace with its own package, build configuration. Surface folders also contain their macOS integration where needed. The Swift sources compile into the same signed app so permissions and helper processes retain the app's identity.

Add a surface

Start with the working echo surface, then read Adding a surface.

A messaging surface supplies three operations:

baseline(agent, signal)             // Capture a cursor before sending
send(agent, text, signal)           // Send one message
receive(agent, cursor, signal)      // Return newer replies and the next cursor

The kernel handles polling, timeouts, cancellation, duplicate replies, and completion after a quiet interval. Services with explicit remote tasks implement the task interface instead; native A2A is an example.

Register the library in gateway/src/surfaces.ts. Desktop integrations provide a descriptor in their own macos/ folder and register it in NativeSurfaces.swift. The surface contract is the reference for validation, lifecycle, private setup commands, discovery, and image hooks.

MCP and security

The default endpoint is http://127.0.0.1:9847/mcp, using Streamable HTTP and No authentication. There are no Agent Squad MCP access tokens or OAuth flow.

Access is controlled by the ChatGPT tunnel or a trusted private network such as Tailscale. Anyone with network access to an allowed endpoint can use the squad; do not expose it to the public internet. The app's private management API uses a separate internal secret and is not available to MCP clients. OpenAI's tunnel runtime key and optional downstream agent credentials are separate from MCP authentication.

The main tools are list_agents, get_agent_card, create_session, send_prompt, get_session, list_sessions, resume_session, and cancel. A2A-style send_message, get_task, and cancel_task tools are also available. See protocol and security for routing, private-network setup, and task semantics.

Development notes

• npm run check type-checks and builds every library. It does not send messages.

• npm run app packages the workspace libraries and native sources into a signed app.

• Agents, sessions, and pairing state live in ~/Library/Application Support/Agent Squad/; credentials use macOS Keychain.

• Messaging completion uses a quiet interval. Canceling stops local waiting and cannot recall a message. Interrupted tasks are never automatically resent.

See architecture, development, and verification.

License

Agent Squad's original source is MIT. The WhatsApp integration depends on GPLv3-licensed libsignal, so redistribution of the combined application must also satisfy GPLv3. See distribution licensing.