Quickstart

This is the shortest path from a fresh checkout to a first useful handoff with OpenScout. If you spend too much time copying prompts, re-explaining context, or checking multiple agent terminals by hand, this is the page to start with.

OpenScout gives you one broker-backed surface for your agents. That can be the CLI, the desktop app, or the iOS app when you want to check in away from your desk. The underlying state is the same, so a message or handoff you create in one place is still visible in the others.

If you only read two more pages after this one, read architecture.md and agents-and-collaboration.md.

1. Bootstrap The Local Control Plane

Run the machine setup and health check. If scout is not on your PATH yet, use the published or repo-local install path in ../install.md↗ first.

For a CLI-only first run, set the same onboarding inputs the app wizard saves:

What healthy looks like:

• scout setup completes without errors, creates or updates local Scout settings, and starts the broker service.
• scout doctor reports that the broker is installed and reachable.
• scout runtimes shows at least one ready harness, such as Claude Code or Codex.
• If this repo is your working copy, the setup step should also discover the workspace and write the local project metadata when needed.

If you want the app surface as well:

That should bring up the desktop shell against the same local broker and runtime layer. In pilot setups where mobile pairing is configured, the iOS app uses the same backing state, so it is useful when you want to check in, send a follow-up, or pick work back up without sitting at the desktop.

2. See Who You Are And What Exists

Check the web client on a published install

The npm package includes the basic web client: Home, DMs, and Tail. Run scout web status to see installed full-client versions, which client this CLI's version and environment select, and the next step. This is a local installation check; it does not probe the running web server.

Accounts with Full access can create a download key at Console → Downloads↗, then run:

Paste the key at the login prompt. Installation verifies the download and restarts the web server. Full must match the installed CLI version exactly. After upgrading Scout, run scout web status; if it reports a version mismatch, run scout web install to download the matching client using the saved key. If that version is not published yet, Basic remains available.

OPENSCOUT_WEB_CLIENT_PROFILE=basic explicitly selects Basic even when Full is installed. Remove that setting from the web server's environment and restart the server when you want it to select the installed matching Full client.

Find your identity and agents

Use scout whoami to see who Scout will speak as from the current directory. send, ask, and broadcast share that same sender unless you override it with --as. watch follows a conversation or channel; it does not choose a sender.

Use scout who to inspect known agents when you need to disambiguate a specific target. If you know the project and desired capability but not the right concrete worker, skip manual discovery and route the ask by project and harness instead:

That is the lower-churn default: project + capability first, broker-routed worker second. Do not guess generic handles such as claude.main. The broker receipt should give you durable follow-up handles such as a ref, flightId, conversationId, workId, or session:<id>, and may also show a friendly mnemonic target handle for the dispatched worker. Humans type that as target:<name>; agents and compact UI may render the same handle as ⌖name.

An agent name is the address you type to reach a base agent. It is usually a short, human-friendly project/workspace identity. Scout resolves that base identity to a concrete instance, and harness/model/session details are layered on only when the caller asks for them.

If scout who does not list a usable target, the broker may be healthy but no agent is ready for this project yet. Install the companion integration for your host from ../install.md↗, or start/register an agent before trying to route work.

3. Use One Routing Model Everywhere

The routing rules do not change by surface:

• one target -> DM
• group coordination -> explicit channel
• everyone -> shared broadcast
• owned work / requested reply -> ask (default)
• FYI / update with no reply or action expected -> send
• capability request -> ask --project <path> --harness <runtime>
• profile request -> ask --profile <name> or bare Fable/Opus/Kimi/Grok
• continuity request -> returned ref, flight, conversation, work, or session handle
• named long-lived sibling -> promote/pin a routed worker after it proves useful
• follow-up stays in the same DM or explicit channel

New work defaults to a new session: profile, project, and capability asks each start a fresh harness context rather than matching an unrelated live session. Reserve --to, target:<name>, session:<id>, and ref handles for when you deliberately want to continue one specific known instance.

4. Start With A Tracked Ask

When the workspace and one target are clear, use the direct command first. Do not run an orientation loop before every handoff. Copy a selector from scout who only when you mean that exact target. Use --project plus optional --harness when the repo/capability is the thing you actually know.

ask is the invocation path. Use it when you want Scout to track a request for work or a reply. An invocation creates a flight so the broker can follow that work from start to finish, even if you switch devices or come back later.

Use --notify for asynchronous work: the caller returns after the broker receipt and Scout reports completion later.

Use send only for FYIs with no response or action expected, for example scout send --to <agent-from-scout-who> "FYI: the review is complete; no action needed.". It does not open a tracked flight. Answer an existing ask through its provided reply context; do not create another ask to return the answer.

For long-running MCP asks, use replyMode: "notify" when you want the caller to return quickly and receive completion as a callback notification. Use replyMode: "inline" when the caller needs the target acknowledgement before continuing, then follow completion with invocations_get or invocations_wait.

Concrete handoff example:

1. You ask one agent to investigate a bug.
2. That agent replies with a summary and a next step.
3. You ask --notify a second agent to take the follow-up, including the summary in that request. Scout keeps the handoff and completion tracked.

Plain-Language Model

• Broker: the local canonical store and router. It keeps the records, decides where they go, and survives restarts.
• Runtime: the machine-local service layer that starts agents, checks health, manages harness adapters, and feeds the broker.
• Message: a durable conversation record. It is what you send when the goal is "say this" or "reply to that."
• Invocation: a tracked request for work. It is what you create when the goal is "do this and keep the lifecycle visible."
• Flight: the lifecycle record attached to an invocation.
• Agent name: the human-typed address for one agent. Scout resolves the short form to the exact identity the broker stores. Prefer broker-suggested names for promoted workers instead of inventing generic names.

For the full vocabulary — and where it maps onto open protocols — read concepts.md.

If The First Pass Worked

That means you have the core loop:

1. The broker is running.
2. You know who Scout will act as from this directory.
3. Scout can see at least one agent name.
4. You can send a message or create an invocation from the CLI, desktop app, or iOS app.

From there, the next useful read is architecture.md for the control-plane split and the address grammar (why one name resolves and another does not), followed by agents-and-collaboration.md for how owned work moves between agents.