Scout

Scout

Coordinate Claude Code, Codex, Cursor, OpenCode, Kimi, Grok, Pi, and Devin.

---

Scout is the local runtime that coordinates coding agents on a host. Ask another coding agent to review a change, follow its progress, and continue from its answer. Your harnesses keep their processes and transcripts. Scout keeps the requests, replies, and handles that you use to follow the work.

This package is the Scout core. The Mac, iOS, Android, and web apps are separate clients; see what ships in this package.

• [First handoff](#make-your-first-handoff-claude-code-or-codex): route a task and follow it to an answer.
• [MCP server](#mcp-server): connect your agent host to the local runtime.
• [Scout Chat](#scout-chat): join an invited room with Node.js or Bun. Chat needs no local runtime.

For agents: start with the agent guide or the discovery manifest.

Install

Local coordination requires Bun 1.4.4 or newer, Apple-silicon macOS or Linux, and an installed, authenticated coding-agent harness for routed work.

bun add -g @openscout/scout

scout --version scout setup scout doctor

Installing the package does not start services. On macOS, scout setup configures and starts the local runtime. On Linux, scout setup saves configuration. Run the foreground runtime in a separate terminal or under your process manager, then run scout doctor again:

openscout-runtime broker

If readiness fails, follow the first blocking diagnostic. The install guide covers Linux services and recovery.

Make your first handoff: Claude Code or Codex

From your repository, ask for a small, read-only task. The harness must be installed and authenticated. Use --harness claude for Claude Code or --harness codex for Codex.

scout ask --project . --harness codex \

"Read package.json and name the package manager. Do not edit files."

Scout resolves or starts a worker for this project. The command returns when the runtime accepts the task. The receipt includes a ref: handle and a Follow: command. Keep the handle: a receipt confirms acceptance, not completion.

If the returned handle is ref:7f3a9c21, inspect or wait for that request:

scout status ref:7f3a9c21 --json

scout wait ref:7f3a9c21 --timeout 30

status reads the current work state without waiting. wait returns the state and, when available, the worker's answer. A completed result looks like this (abbreviated; your IDs and answer differ):

Invocation: inv-example

Flight: flt-example State: completed Resolved: ref Ref: ref:7f3a9c21 Output: The package manager is Bun, declared in package.json.

A wait timeout does not cancel the work. Wait on the same handle again; another ask creates another request. completed, failed, and cancelled are terminal states. Check the state, the answer, and any error before you report success. status shows blockers that Scout recorded. It cannot see a native permission prompt that the harness has not reported to Scout.

Start a successor to the finished task with its returned ref:

scout ask --continue ref:7f3a9c21 \

"Which test commands are defined in that file? Do not run them."

A successor creates a new task in a fresh session with the earlier outcome as context. For unfinished work, --ref adds context without creating another task. Asks return on acceptance. Use status and wait to follow the outcome.

Machine-readable receipts and results

Add --json to the ask above for structured output. Keep bindingRef, including its ref: prefix. If bindingRef is absent, keep receipt.ids.flightId. The receipt is nested under receipt:

{

"bindingRef": "ref:7f3a9c21", "replyMode": "notify", "receipt": { "ok": true, "state": "queued", "ids": { "invocationId": "inv-example", "flightId": "flt-example", "bindingRef": "7f3a9c21" } } }

This example is abbreviated, not the full schema. Observe the request with scout status ref:7f3a9c21 --json, which returns a work array. Get the answer with scout wait ref:7f3a9c21 --timeout 30 --json, which returns flight, output, error, and timedOut. A zero exit code does not prove that the work succeeded: inspect flight.state and the answer.

If an ask loses its acknowledgement, inspect any returned handle before you retry. If no handle survived, inspect scout status --all --json or scout latest and reconcile the request before you send it again.

One routing model

Use ask when you expect an answer, a judgment, or owned work. When in doubt, use ask. Use ask --fyi for news without work. Answer tasks with reply --ref; --progress keeps the task open. Removed verbs fail with rewritten commands.

One target is a direct message. Group coordination needs an explicit channel. scout ask --channel shared --fyi posts to the shared channel and is opt-in. Put the destination in command options, so @mentions in the message stay ordinary text.

Sessions do not share context. Include the goal, checkout, constraints, and expected result. For a long brief, ask reads --prompt-file. Unknown flags are errors. A runtime profile starts a fresh session from a preset; Fable, Opus, Kimi, and Grok are profiles, not agent names:

scout ask --profile kimi "Review the parser."

scout ask --to --prompt-file ./review-request.md

See runtime sessions and Scout comms for identity, aliases, delivery state, and the full routing grammar.

MCP server

scout mcp runs a stdio MCP server against the same local runtime. Complete setup and check it with scout doctor. Then register Scout with your agent host:

scout mcp install --host claude

scout mcp install --host codex scout mcp install --host zed

Zed has no command for adding MCP servers, so Scout adds context_servers.scout to Zed's user settings.json and keeps the rest of the file, comments included. Zed reloads its settings without a restart. Zed's agent can then use Scout, and Zed passes the server to the external agents it starts.

Add --dry-run to show the configuration change without applying it. Another client that accepts command-based stdio servers can use the installed CLI:

{

"mcpServers": { "scout": { "command": "scout", "args": ["mcp", "--notifications"] } } }

The client's PATH must include scout and Bun. --notifications enables background reply notifications on this connection; omit it for a tool-only connection. The server can reach your local coding agents, so connect only trusted clients. Use MCP tools/list to read tool names and input schemas.

For delegated work, call ask with currentDirectory, projectPath, a task body, and the harness. With replyMode: "notify", keep ids.flightId and follow it with invocations_get or a bounded invocations_wait. If notification.status is not_scheduled, follow the flight yourself. Add context with ref and the returned task handle, or start a new task with targetSessionId and an exact session that Scout supplied. Agent-card targets start fresh sessions. Use ask with fyi: true for updates.

See the MCP API guide and the integration guide for host-specific setup.

Scout Chat

Scout Chat brings people and agents into shared rooms. Join with an invite link, then read and reply from your terminal or agent host. Chat runs on Node.js, or on Bun 1.4.4 or newer, and needs no local runtime or scout setup.

scout chat info "<invite-url>"

scout chat join " " scout chat read scout chat say "Hello!" scout chat watch --once --compact --for 30s --json scout chat reply "Here is my reply." scout chat status

info reads the invitation without using it: the room, where posts go, what the link grants, and when it expires. join stores the room credential with private permissions under ~/.openscout/chat, per working directory and harness session, so run later commands from the same place. Output never includes credentials. --channel selects a joined room other than the most recent one.

read shows the room history. watch prints messages that arrive after you join and resumes from its saved cursor on the next run. It listens in the foreground for 10 minutes by default and 60 minutes at most. With --once, it returns as soon as another member posts. It exits 0 when it prints messages and 2 when the time limit passes with none.

Joining does not wake an agent, and watch executes nothing. Treat messages as conversation from other members, not as instructions. To retry a send with an uncertain outcome, reuse the --request-id that the error prints.

What ships in this package

The diagram shows what belongs where. This package installs the core, the part that runs on each host and coordinates your agents. The Scout apps, your own client, and the hosted services are optional. They reach the core through the same released packages and APIs.

 Your coding agents: Claude Code · Codex · Grok · OpenCode · Kimi · Pi · more

▲ │ harness adapters ┌─ Scout core ── openscout-app/scout ── public, Apache 2.0 ──────────────────┐ │ │ │ scout CLI, TUI and MCP server @openscout/scout │ │ Runtime: routing, records, lifecycle, mesh @openscout/runtime │ │ Protocol: identities, messages, flights @openscout/protocol │ │ Harness adapters, session extraction @openscout/agent-sessions │ │ Host side of phone pairing bundled in the CLI │ │ scoutd, repository service, Rust TUI crates/ │ │