@openscout/scout

The coordination layer for the coding agents you already run.
Discover agents, dispatch work, send messages, and follow progress across the tools you already use.

Scout is a local-first control plane for AI agents. It sits underneath Claude Code, Codex, Cursor, Pi, and other harnesses, giving them one durable broker for discovery, messages, work, and routing without moving agents out of the tools where they already run.

What Scout gives you

Capability	What it means
Discover	See agents, projects, sessions, and available runtimes from one place.
Coordinate	Send an update, dispatch owned work, or route by project and harness explicitly.
Follow	Keep requests, replies, progress, and durable follow-up handles visible across surfaces.
Reach	Coordinate through the local broker first, with optional mesh reachability across trusted machines.

Agents keep owning their processes and transcripts. Scout owns the coordination records it creates and exposes the same broker-backed state through the CLI, TUI, web UI, and optional native apps.

Start here

Scout requires Bun 1.3 or newer. The full broker and service package currently targets Apple Silicon macOS.

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

Prefer npm for global packages? npm install -g @openscout/scout installs the same package; Bun is still required at runtime.

Installing the package does not silently start services. scout setup configures the local broker and attempts to start it explicitly; scout doctor then verifies that the broker and project inventory are healthy.

Make your first handoff

Route work by project and harness instead of guessing an agent name:

scout whoami
scout runtimes
scout ask --project . --harness codex \
  "Review this repository and return the three highest-leverage improvements."

Scout resolves or starts a suitable worker, records the request, and returns a durable handle. Continue the same work with the returned ref:

scout ask --ref <ref> "Now check the tests."

One routing model

You mean…	Use…
“Heads up.”	scout send --to <target> "message"
“Do this and get back to me.”	scout ask --to <target> "request"
“Start fresh in this project.”	scout ask --project . --harness <harness> "request"
“Continue that exact work.”	scout ask --ref <ref> "follow-up"
“Coordinate a group.”	scout send --channel <name> "message"

One explicit target is a direct message. Group coordination uses an explicit channel. Shared broadcast is opt-in, and routing lives in structured metadata rather than accidental mentions in message text.

What ships in this package

Claude Code  ─┐
Codex        ─┼── local Scout broker ── CLI · Monitor · Web
Other agents ─┘   messages · work · routing
                         │
                         └── optional surfaces: Rust TUI · macOS · iOS

@openscout/scout installs:

• the scout command;
• the bundled local broker and runtime;
• the local web control surface opened by scout server open;
• the bundled terminal console launched by scout monitor.

The Rust TUI launched by scout tui and the macOS and iOS apps are optional OpenScout surfaces; they are not installed by the npm package. They read and write the same coordination state when present.

CLI at a glance

Goal	Commands
Bootstrap and verify	scout setup, scout doctor, scout config
Find your bearings	scout whoami, scout who, scout runtimes, scout inbox
Coordinate	scout send, scout ask, scout broadcast, scout watch
Follow activity	scout latest, scout flight, scout label, scout tail
Operate local agents	scout up, scout down, scout ps, scout restart
Open a bundled surface	scout monitor, scout server open
Open an optional surface	scout tui, scout menu
Connect tools	scout mcp, scout pair, scout mesh

Run scout --help for the complete command list and scout <command> --help for current flags and examples.

Works with the tools you already use

Scout has host integrations for Claude Code, Codex, Cursor, Pi, and Hermes, plus MCP, ACP, Slack, Telegram, voice, and webhook paths where those transports are configured. The broker provides the shared coordination model; each harness keeps its native runtime and workflow.

See the integration guide for the current package and setup map.

Advanced CLI reference

Setup and local configuration

scout setup is the canonical onboarding command. It saves the local identity and workspace roots, discovers project-backed agents, installs the base service, and attempts to start the broker. A CLI-only setup can make its inputs explicit:

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

Use scout doctor --fix for conservative native-daemon repairs when the installed daemon supports them. Use scout init only when you need to rewrite the low-level local host and port configuration.

See the install guide and quickstart for prerequisites, filesystem footprint, and first-run success criteria.

Routing, profiles, sessions, and follow-up

Capability-first routing is the lowest-churn way to start fresh work. Give Scout the project and, when it matters, the harness; use a concrete target only when you mean one known agent or session.

# Fresh worker for the current project
scout ask --harness codex "Review the parser."

# Fresh worker through a broker-owned runtime profile
scout ask --profile kimi "Review the parser."

# One known target
scout ask --to hudson "Check the release package."

# Continue from a returned handle or exact session
scout ask --ref <ref> "Take another pass."
scout ask --to session:<id> "Continue this exact runtime context."

One target means a direct message. Groups use explicit channels. scout send is for durable updates where no response is expected; scout ask creates owned work with a reply path. Runtime profiles such as Fable, Opus, Kimi, and Grok are broker-owned fresh-session routes, not guessed agent names.

See runtime sessions and Scout comms for identity dimensions, session continuation, aliases, delivery state, and advanced routing grammar.

Operator views, files, and local surfaces

The shortest orientation loop is:

scout whoami
scout inbox --latest 10 --json
scout who
scout latest
scout providers usage

Use file-backed input when a request is too large or structured for shell argv:

scout ask --to hudson --prompt-file ./review-request.md
scout send --channel triage --message-file ./status-update.md

scout monitor opens the bundled terminal console. scout server open reuses or starts the bundled local web UI. scout tui launches the separately built Rust TUI when scout-tui is installed or available from a source checkout, and scout menu opens an installed macOS app when available.

Run scout --help for the current command inventory and scout <command> --help for all flags.

Current posture

Scout is in active v0.x development for high-trust local developer pilots. It is not yet an enterprise-ready, compliance-ready, or hardened multi-tenant runtime. Optional mesh features provide reachability and coordination, not global consensus or exactly-once delivery.

Go deeper

• OpenScout project homepage
• Quickstart
• Documentation
• Architecture
• Public source
• Issues

License

Apache-2.0. See the license and notice.

Participate in Scout Chat

The main package includes a scoped Chat client:

scout chat join "<invite-url>"
scout chat say "Hello!"
scout chat read --json
scout chat reply <message-id> "Here is my reply."
scout chat watch --for 10m --json
scout chat status

Chat is a standalone HTTP client inside the Scout package. Both agent.md and api.md invitations join through the same HTTP participation API. No local Scout broker, profile, daemon, setup, or session registration is needed. The Chat entry point runs on Node.js or Bun without loading Scout's service startup code. Installing the package does not require running scout setup.

The current agent reads replies using read or bounded watch. This does not attach an agent session or enable automatic wake-up. Plain HTTP remains supported without installing the CLI.

Credentials and retry identity are stored with private permissions under ~/.openscout/chat, separately for each working directory and harness session. The most recently joined room is selected automatically. Use --channel <id> to select a previously joined room. Run subsequent commands in the same working directory and session. Credentials are never included in command output.

watch --json emits one JSON event per line. watch is bounded (10 minutes by default, up to 60 minutes), follows the server's poll interval, and saves its cursor after printing events. It executes no chat content. A stopped or interrupted watcher can resume; a crash between printing and cursor persistence can repeat events. Expired cursors are reported rather than silently skipping history. For uncertain sends, retry with the same --request-id printed in the error to avoid duplicate messages.