Coordinate local coding agents and track handoffs. For high-trust developer pilots.
io.github.oscout/scout (MCP) Server
The MCP server “io.github.oscout/scout” coordinates local coding agents and tracks handoffs. Its description positions the server as support for high-trust developer pilots, focusing on agent coordination and transfer tracking between participants.
🛠️ Key Features
Coordinate local coding agents
Track handoffs
🚀 Use Cases
Local coding agent collaboration
High-trust developer pilots requiring handoff tracking
⚡ Developer Benefits
Clear visibility into handoff events between agents
⚠️ Limitations
Limited details provided beyond coordination and handoff tracking
Framed for “high-trust developer pilots” per the available description
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.
Local coordination requires Bun 1.4.4 or newer, Apple-silicon
macOS or Linux, and an installed, authenticated coding-agent harness for routed
work.
bash
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:
bash
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.
bash
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:
bash
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):
text
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:
bash
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:
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.
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:
bash
scout ask --profile kimi "Review the parser."
scout ask --to <agent-from-scout-who> --prompt-file ./review-request.md
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:
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:
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.
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.
sh
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.
text
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 bun add -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.
scout menu, scout server open, scout web, scout auth
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.
Setup and readiness
scout setup saves the local identity and workspace roots and discovers
project-backed agents. Install describes what it starts on each
platform. In an interactive terminal it prompts for a workspace root. A
scripted setup can supply its inputs:
bash
scout config set name "Ada"
scout setup --source-root ~/dev --default-harness codex
--source-root is repeatable. Setup and doctor check the core, not app health.
scout doctor reports readiness and the next useful command. FAIL means an
observed impairment; ? means the check was inconclusive. Use --detail for
the full inventory and --json for an NDJSON stream. scout doctor --fix
asks the native daemon for conservative repairs when it supports them. Use
scout init only to rewrite the low-level host and port configuration.
--help on setup, up, app, install, and doctor prints help without
checking, starting, or changing anything. The
core readiness contract defines the JSON output.
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.
Model families in the runtime catalog
Runtime
Model families
Claude Code
Claude Opus, Fable, Sonnet, and Haiku
Codex
GPT, including Astra, Sol, Terra, and Luna variants
Grok
Grok
OpenCode
GLM, Kimi, Qwen, MiniMax, DeepSeek, Grok, Nemotron, and Laguna