Scout — coordinate Claude Code, Codex, and other AI agents

Scout connects coding agents through a local broker for agent-to-agent communication, multi-agent coding workflows, and tracked code reviews. Ask Claude Code to review a Codex change, route a task to another project, and return to the same request when you need a follow-up.

Keep using your existing agent tools and provider accounts. Scout supplies the CLI, runtime, Model Context Protocol (MCP) server, and web control surface that connect their work. Optional mesh features extend coordination across trusted machines you own.

Current posture: Scout is for high-trust local developer pilots. It is not yet a hardened multi-tenant or compliance-ready control plane.

Quickstart · Workflows · Integrations · MCP setup · Common questions · Architecture · Documentation

What can you do with Scout?

Start with Claude Code and Codex code review, then explore multi-agent coding and AI agent orchestration.

Related MCP server: Beep Boop MCP

Get started

Local coordination uses Bun 1.3 or newer and at least one installed, authenticated coding-agent tool. Start on Apple Silicon macOS:

bun add -g @openscout/scout
scout setup
scout doctor
scout runtimes

Installing the package does not start services silently. scout setup configures the local broker; scout doctor checks its readiness. On Linux, run the broker as a foreground process under your process manager; follow the quickstart for that lifecycle.

Have Claude Code review a Codex change

From the project containing the change, pause edits while the reviewer reads it. Claude Code must be installed and authenticated on the reviewing machine.

scout ask --project . --harness claude --notify \
  "Review the uncommitted diff for correctness. Return findings with file and line references, or say no findings. Do not edit files or run tests."

Scout resolves or starts a suitable worker, records the request, and prints a receipt with a flight id and, when the broker binds one, a ref: handle. --notify returns after that receipt instead of holding your terminal. Replace ref:RETURNED below with the handle from your receipt:

scout wait ref:RETURNED --timeout 600
scout ask --ref ref:RETURNED \
  "Explain the most important finding and the input that triggers it. Do not edit files."

scout wait also accepts the flight or invocation id. A wait timeout means the result is not available yet; it is not proof of failure, so run the same wait again. A receipt means the broker accepted the request, not that the review finished. To have Codex review Claude Code's work, use --harness codex in the first request.

Choose your agent tool

A harness runs the coding agent. An integration connects a tool to Scout; some integrations expose MCP tools or terminal state without being execution harnesses. Use the setup link for the tool you already work in.

Run scout runtimes --json for the runtime and model combinations Scout knows about. A catalog entry is not proof that a route works on your machine: the harness must be installed and authenticated, and the provider must grant access to the selected model. scout doctor reports local readiness. See the integration catalog for additional tool-specific guides and their current setup requirements.

Collaboration across Claude Code, Codex, Grok, and OpenCode

Scout connects coding agents as collaborating peers. No tool has a fixed role or authority over another. A task can start in any connected agent, and its recipient can return findings or request a follow-up.

Scout routes work between coding-agent harnesses in either direction: Codex ↔ Claude Code, Claude Code ↔ Grok, Grok ↔ Codex, Codex ↔ OpenCode, and other catalog routes such as Kimi Code and pi. A direction works when two things are true:

• the destination harness is installed and authenticated where it runs;

• the calling session can reach Scout, by running the scout CLI or through Scout's MCP tools.

# Ask Grok CLI for a read-only investigation of the current project
scout ask --project . --harness grok-acp --notify \
  "Investigate why the retry test is flaky. Cite files and lines. Do not edit files."

Change --harness to claude, codex, opencode, or kimi to pick a different destination. Sessions do not share context: pass the goal, the exact revision, and earlier findings in each request, or use --prompt-file for a longer brief. The roles below are examples, not claims that one model is best at a particular job.

Start with one request and its reply before building a longer chain. The coding-agent collaboration guide (web version) covers handoff templates, connection mechanisms, native subagents versus separate harnesses, and coordination across machines.

How do the connections work?

Codex app-server, OpenCode's detached service, Claude Code's structured CLI, ACP, and tmux expose different ways to exchange work. Separate the interface, runtime, transport, session, and artifacts before choosing one. Scout's selected adapter may use a different surface from a tool's native server: for example, broker-created OpenCode tasks default to ACP while its product-V2 service has an explicit adapter path. The guide explains the moving parts and their lifecycle, including session identity, process ownership, permissions, and completion.

Coding-agent workflows explained

Claude Code vs Codex: can I use both together?

Yes. Give one agent implementation ownership and the other a focused review of an exact revision, with the project path and intended behavior. Each keeps its own session, so the reviewer only knows what the request tells it. Reverse the roles for a different task. The Claude Code–Codex review workflow walks through the request, result, and follow-up.

The Claude Code plugin, Codex plugin, and MCP server expose Scout's coordination tools inside those clients. They do not turn a Claude session into a Codex session or transfer conversation history between providers.

Multi-agent coding, subagents, and Git worktrees

Claude Code subagents, Claude Code's experimental agent teams, and Codex subagents already handle parallel work inside one tool. Scout is for work that crosses harnesses, projects, or machines.

Either way, parallel agents help when tasks can proceed independently. Agree on shared interfaces first, give each task one owner, and give concurrent writers separate Git worktrees. Worktrees isolate working files, not shared ports, databases, secrets, or external services. Ask each worker for a revision, checks performed, and unresolved issues, and have one integrator review the combined result. Read the multi-agent coding guide.

AI agent orchestration, task delegation, and handoffs

Here, orchestration means assigning work to existing coding agents, tracking its state, and continuing the right conversation. A useful handoff names the goal, destination checkout, stable inputs, constraints, and expected result. Use scout ask when you need a reply, scout wait to collect it, and scout ask --ref to follow up on the same work. Use scout send for an update that needs no reply.

The local broker owns Scout's coordination records. Each agent keeps its own provider, permissions, and execution environment. See AI agent orchestration for the ownership decisions behind this model.

Agent-to-agent communication: is this like Slack for agents?

The analogy fits direct messages and named group channels. Coding work also needs a result: who accepted the task, whether it finished, and where to follow up. Scout records those requests and replies through its broker. Group coordination uses a named channel; broadcast is opt-in.

A literal Slack connection is a separate integration with its own requirements. Read about agent-to-agent communication for the local broker model.

Claude Code history, Codex sessions, and finding earlier decisions

Use Scout's session search to find text in observed harness sessions after explicitly indexing the relevant history:

scout search status
scout search index --source sessions --harness claude --days 3
scout search query "review decision" --harness claude --days 3

Search covers only the sources and time ranges you indexed. Finding a transcript helps recover context; it does not resume that session or import its history into another agent.

MCP vs A2A vs ACP: where does Scout fit?

• MCP (Model Context Protocol) connects an AI client to tools. It is Scout's agent-facing interface: scout mcp exposes tools such as ask, messages_send, and invocations_wait.

• ACP (Agent Client Protocol) connects an editor or client to a coding agent. Scout acts as an ACP client to drive some harnesses, such as the grok-acp route; it is not an ACP agent server. BeeAI's Agent Communication Protocol shares the acronym, and Scout does not implement it.

• A2A (Agent2Agent) is an interoperability protocol between agents. The broker exposes a subset (agent cards and JSON-RPC task methods projected from Scout flights). This is not full conformance: streaming, push notifications, authenticated extended cards, and production security controls remain open.

See Scout concepts for the exact mapping and the ACP, A2A, and MCP comparison for background.

Remote coding agents and coordination across machines

Scout's optional mesh extends reachability between trusted machines. A remote handoff still needs a reachable destination, an installed agent runtime, and the intended checkout on that machine. Mesh does not synchronize repositories, replicate external transcripts, or guarantee exactly-once delivery.

Claude Code's own Remote Control and cross-session messaging connect Claude Code sessions to each other and to claude.ai; they do not route work to other harnesses. See the documentation for Scout's mesh and pairing requirements. A local broker does not make model inference local: your agent provider still receives the task data it needs.

MCP server

OpenScout includes an MCP server implemented with the official TypeScript @modelcontextprotocol/sdk, using McpServer and StdioServerTransport. The scout mcp command starts it over stdin/stdout. MCP clients call tools that connect to Scout's local broker; the internal Scout protocol describes broker records and is separate from the MCP interface exposed to clients.

Install and connect

Requires Bun 1.3 or newer on macOS or Linux. Initialize the local broker before using coordination tools:

bun add -g @openscout/scout
scout setup
scout doctor

Add this entry to an MCP client's command-based stdio configuration:

{
  "mcpServers": {
    "openscout": {
      "command": "bunx",
      "args": ["@openscout/scout", "mcp"]
    }
  }
}

The client must be able to find bunx on its PATH. The client launches the server and communicates over stdio; this command does not start a public HTTP MCP endpoint. Only connect trusted clients: coordination tools can launch local coding agents, send messages, and update broker-owned work.

MCP tools

Representative tools exposed by the server:

Use MCP tools/list to inspect the current tool names and input schemas. ask creates owned work; messages_send is for updates that need no reply. The broker remains the canonical writer of coordination records.

Implementation and verification

• MCP server implementation: SDK imports, tool registrations, and stdio transport.

• CLI entry point: the scout mcp command.

• MCP tests: client/server connection, tools/list, and tool behavior.

• Package registry metadata: io.github.oscout/scout, npm package, and stdio launch arguments.

• MCP API guide and CLI setup guide.

The small model

One target is a DM. Group coordination uses a named channel. Broadcast is opt-in. Routing lives in structured metadata—not in accidental @mentions inside the message body.

One broker, many surfaces

                                                    ╔══════════════════════╗
                     ╔══════════════════════╗       ║ ◆ Local broker       ║
                     ║ ◆ Scout surfaces     ║       ║ canonical writer     ║
┌────────────────┐   ║ CLI + local web      ║   ┌──▶║ route + run          ║
│ ◆ Operator     │ ┌▶║ one control plane    ║───┘   ║                      ║
│ or agent       │─┘ ║                      ║       ╚══════════════════════╝
└────────────────┘   ╚══════════════════════╝                   │
                                                                │
                                                                │
                                              ┌─────────────────┴─────────┐
                                              │                           │
                                              ▼                           │
                                  ╔═══════════════════════╗               ▼
                                  ║ ◆ Harnesses + mesh    ║      ┌────────────────┐
                                  ║ Codex · Claude · ACP  ║      │ ◆ Records      │
                                  ║ reachable peers       ║      │ durable        │
                                  ║                       ║      │                │
                                  ╚═══════════════════════╝      └────────────────┘

The broker is the canonical writer for Scout-owned coordination records. Harness transcripts remain observed source material; Scout does not bulk-import them as first-party conversation history. “Mesh” means reachability and coordination—not global consensus or exactly-once delivery.

What ships here

Public core, private product

This is the destination for Scout's strong public primitives and a complete baseline web control plane. A public installation should support the ordinary local workflow—setup and health, agents and sessions, conversations and requests, work and activity, runtimes, projects, mesh, and settings—without private-only placeholders.

The product split is an active migration, not a claim that the repositories and release pipeline have already been cut over. The target is one-way: the private OpenScout product consumes exact released public packages and adds native apps, hosted services, advanced operations, and product-specific UI through trusted build-time web composition. It must not carry copied public source or a mirrored packages/web, and public Scout must never depend on private code.

See the public-source boundary for current migration status, target ownership, and release invariants.

Work on Scout

git clone https://github.com/oscout/scout.git
cd scout
bun install

bun run --cwd packages/cli build
./packages/cli/bin/scout --version

Run bun run sync-exec:fence before submitting changes that add or modify shell execution. Use the package-local checks for the area you changed; the complete suite is available through bun run check and bun run test:unit.

Go deeper

• Install and verify — supported installation paths and clear success criteria

• CLI guide — setup, routing, profiles, sessions, and operator commands

• Runtime guide — broker and runtime internals

• Protocol guide — integration contracts and shared types

• Agent sessions — harness observation and session models

• Concepts — Scout's vocabulary and how it maps to A2A, ACP, and MCP

• Coding-agent collaboration guide — handoffs across Codex, Claude Code, Grok, and OpenCode

• Public-source boundary — what ships here and how package/source parity stays verifiable

• Release guide — reviewed-source, package, tag, and registry invariants

• OpenScout for macOS — public downloads, updater trust, and verification

• Architecture diagram source — editable Arc model behind the README diagram

• Brand assets — canonical mark, hero, avatar, and social preview sources

• OpenScout — product context and project home

License

Apache-2.0. See LICENSE.