Using Scout01 / 09~3 min

01 · Hello Scout

Goal

Bring up the local control plane and learn who Scout thinks you are.

You need

The scout CLI installed (../install.md↗). Nothing else — no agents, no projects, no account.

Welcome. This one is deliberately small: five steps, none of which spawn an agent or send a message. What you get at the end is the floor everything later stands on — a running broker, a name, and an identity Scout resolves on its own.

The idea

Everything Scout does flows through a local broker: a durable store and router on your machine that holds messages, work requests, and agent records. It runs as a service, it survives restarts, and nothing leaves the box unless you send it somewhere.

Two facts have to be true before any coordination means anything — the broker is healthy, and Scout can work out who is speaking from the directory you happen to be standing in.

Walk it

Name yourself

scout config set name "Ada"

This is the display name other agents see when you act through Scout. Bare scout config reads back what is currently set.

Bring up the broker

scout setup

scout doctor

setup writes local settings and starts the broker service. doctor is the health check: it discovers projects, then reports on the native daemon.

Output

Native daemon:
  Loaded: yes
  Broker reachable: yes
  Health transport: unix_socket

If your repos live under one directory, tell Scout while you are here — it scans that root for projects, and --default-harness sets what a project falls back to when it does not name one:

scout setup --source-root ~/dev --default-harness claude

Anything reporting unhealthy: scout doctor --fix --yes, then check again.

See what can do the work

scout runtimes

The harness catalog — Claude Code, Codex, Grok, and others — with readiness for each:

Output

Known runtimes: 9
  - Claude Code (claude)
    State: ready
    Binary: /Users/ada/.local/bin/claude
    Login: claude login

A harness is ready when its CLI is installed and authenticated here. You need one ready runtime for what follows; if you have none, install and sign in to one, then re-run scout runtimes.

See who you are

scout whoami

Default Sender: ada.myrepo.adas-mini
Current Directory: /Users/ada/dev/myrepo
Project Root: /Users/ada/dev/myrepo
Project Instructions: /Users/ada/dev/myrepo/AGENTS.md
Broker: http://127.0.0.1:43110

Scout derives a sender identity from where you are — typically a project agent qualified by the checkout and the machine. Every send, ask, and broadcast speaks as this identity unless you override it with --as.

See who else is out there

scout who

ada.myrepo.adas-mini · active · 0 messages · last seen 20:32:44
session-mu1ce894-22qgz0 · active · 1 message · last seen 20:18:15

Agents the broker knows, with last activity. On a fresh install this is nearly empty, and that is the correct answer — the next few create the entries this list is missing.

How to tell it worked

scout doctor reports Broker reachable: yes and no diagnostics you cannot account for.
scout whoami prints a Default Sender: line rather than an error.
scout runtimes shows at least one harness at State: ready.

All three reading that way means the control plane is yours. 02 puts work on it.

Push further

scout whoami --json gives the structured identity, including the nearest project instruction file Scout found.
scout env shows the executable and agent identity context — the command to reach for when a shell inside an agent session resolves to an identity you did not expect.
scout machines lists the computers Scout can already see. On one machine that is just you; it starts mattering in 09.

02 — Your first ask: put one tracked unit of work on the wire.