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: route a task and follow it to an answer.
• MCP server: connect your agent host to the local runtime.
• 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.

npm install -g @openscout/scout
scout --version
scout setup
scout doctor

bun add -g @openscout/scout installs the same package. 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 --notify \
  "Read package.json and name the package manager. Do not edit files."

Scout resolves or starts a worker for this project. With --notify, the command returns when the runtime accepts the request. 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.

Continue the same worker's context with the returned ref:

scout ask --ref ref:7f3a9c21 --notify \
  "Which test commands are defined in that file? Do not run them."

The follow-up is a new tracked request in the same session, with its own receipt. A new --project ask starts fresh instead.

Without --notify, ask returns when the target acknowledges, when the work completes immediately, or after 30 seconds without acknowledgement. It does not wait for the task to finish. Use status and wait to follow the work.

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

One routing model

Use ask when you expect an answer, a judgment, or owned work. When in doubt, use ask. Use tell for an FYI or a status update; it never creates work. scout send still works for older scripts. New scripts use ask or tell.

One target is a direct message. Group coordination needs an explicit channel. scout broadcast 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 and tell reads --message-file. 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 <agent-from-scout-who> --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

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. Continue with to: "ref:<id>" and the returned binding ref, or with targetSessionId and an exact session that Scout supplied. Agent-card targets start fresh sessions. Use messages_send 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 "<invite-url>"
scout chat read
scout chat say "Hello!"
scout chat watch --once --compact --for 30s --json
scout chat reply <message-id> "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 <id> 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/                      │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘
               released packages · runtime API · CLI JSON · MCP
                ▲                            ▲                             ▲
┌─ Scout apps ──┴────────┐  ┌─ Your client ──┴─────┐  ┌─ Hosted services ──┴─┐
│  Mac, iOS, Android     │  │  Same APIs as        │  │  Accounts, relay     │
│  and web               │  │  the apps            │  │  and push            │
└────────────────────────┘  └──────────────────────┘  └──────────────────────┘

@openscout/scout installs:

• the scout command and the openscout-runtime launcher;
• the bundled runtime, harness adapters, session extraction, and the host side of phone pairing;
• JSON output and the stdio MCP server;
• on Apple-silicon macOS, the scoutd service supervisor.

The Rust TUI launched by scout tui is part of the core. Its native binary is not installed by npm install -g @openscout/scout. scout tui uses a local copy or downloads the release binary for this version on first use.

The package ships no web app. scout server and scout web serve a web client only when the separate apps supply one. Without that client, they say where the web app comes from. scout web install downloads the web app for this host; it signs in through the browser first with scout auth login. The source boundary states the ownership rules, and the repository README explains how to build your own client.

CLI at a glance

scout who lists known agents; it does not prove live work. scout search finds past harness sessions; see session search. scout mesh guests grants and revokes key-bound guest access to selected agents; see direct guest access. The legacy scout monitor console is retired; use scout tui.

scout --help is a short starting point. scout help --detail lists every command, and scout <command> --help shows its flags and examples.

scout config set name "Ada"
scout setup --source-root ~/dev --default-harness codex

Works with the tools you already use

Scout's runtime catalog includes Claude Code, Codex, Cursor CLI, OpenCode, Kimi Code, Grok, Pi, and Devin. Run scout runtimes --json to see which harnesses are ready and their current model IDs before you select an exact model. A catalog entry needs an installed harness, authentication, and provider access before it can run. Kimi Code, Cursor, and Pi take models from their own harness configuration.

Connect Scout to your agent host:

• Claude Code plugin
• Codex plugin
• Cursor MCP setup
• Pi extension
• Hermes Agent plugin
• Grok setup guide

Hermes Agent connects as an agent host through its plugin. It is not a --harness value. The integration guide maps every package and setup path.

Support

For commercial support or to learn more about our plans, contact us. Report bugs and request features in GitHub issues.

Go deeper

• Project homepage
• Quickstart
• Documentation
• Install guide
• Architecture
• Source boundary
• Source repository

License

Apache 2.0. See the license and the notice.