Scout

Work happens in a thread

One Slack thread is one piece of work. Scout keeps a single message up to date while it works, and replaces it with the answer. The reaction on the request follows along: 🧠 thinking, 📖 reading, 🧪 testing, ending ✅, ⚠️ or 🙋. Anyone in the thread can add context or change course while it runs.

• The team can steer While Scout works, every message from someone who may ask it for work steers it; anyone else's is context. A stop sign, or “@Scout stop”, stops it.
• Nothing is lost A thread survives restarts and deploys, and messages sent while Scout restarts run when it's back.
• Quiet when people talk When idle, it answers a mention, or a reply from the person it was answering. Anything else is kept as context.
• Five ways in Slack threads, the code host, review requests, schedules, and npm run job for one-off work.

How it fits together

One Node process, SQLite and Slack's Socket Mode: no public address, no Postgres, no job queue. Pi Durable runs the agent, checkpointing every model call and tool call, so a crash or a deploy carries on mid-run, and a second person can steer work already in progress.

In short: requests arrive from Slack, the code host, alerts, schedules and one-off jobs. Scout, a single process on the host, checks who may ask, runs the agent on Pi Durable, and answers in Slack. Its tools reach a sandbox per thread, a model provider or gateway, the code host and Litestream's backup, and only Scout holds credentials.

Every file operation and command goes through a pi-env daemon in the sandbox, and git crosses as bundles: a host-owned mirror fetches the thread's commits and pushes them. The host never runs git inside a thread's clone.

Scout learns, and people decide what

Scout learns from its own work. As it goes, it keeps notes on what it found out; each night it reflects on the day's threads and proposes what it should know from now on, as a pull request against its own profile. People review that like any other change, and once it's merged, Scout knows it in every thread.

River showed why this matters: its merge rate rose because people noticed where it got stuck or could do more and told it. Scout remembers the lesson so it can improve.

1. Notes as it works

   Scout remembers what it learns in a thread and can forget it again. Unreviewed notes are on the dashboard, and they retire once a merged proposal covers them.

2. A nightly reflection

   Every night it reads each thread with new activity: who asked what, what it did, which steps failed and how it ended, plus its notes and what reviewers said about its last proposals.

3. A pull request on its profile

   It edits a clone of its profile repository, with file tools only, and opens a pull request that explains each change with the thread it came from.

4. Merge it, and every thread has it

   Scout keeps its profile pulled, so the next request in every thread gets the change. Each Monday it reports its merge rate and each channel's week.

The profile is files in git: a system prompt, skills, and each channel's instructions, repositories and zones. One team's skill can be reused by every other.

What you get

• Multiplayer, durable threads

  Each thread is a durable conversation on Pi Durable: it survives restarts, and the people who may ask for work can redirect it. 🔁 on an answer tries again, and editing a request steers the run. A change made through a tool that needs approval waits for one of its approvers' “approve” or 👍, or the Approve button, and the approval covers that one change. “Ask Scout about this” on any message, or 🔍, starts a thread there, and /scout and the Home tab show what Scout is doing and what's waiting on you. Each channel gets a canvas of what's open, and a Slack List tracks all of Scout's work.

• A sandbox per thread

  Its own clone in its own Docker container or spoond microVM, with nothing worth stealing in it. Network is off by default, or a per-repository allowlist where spoond enforces one. A sandbox that can't reach a host asks, and one of the named egress approvers allows or declines it from Slack.

• Reviewed before you review it

  Before any pull request, Scout reviews its own diff in a separate conversation that can only read. It refuses changes over a size limit, scans the diff for credentials, and asks the code's owners to review.

• A tidy colleague

  It watches CI on its pull requests and fixes red builds, keeps them mergeable as the base moves, asks about quiet ones before closing them, deletes merged branches, and never pushes over a teammate's commits.

• Pull request reviews

  Ask Scout for a review on the code host as you would a person. It reviews like a colleague, with line comments, again on each new push, and says so in the repository's channel. Its reviews are comments, never approvals, so a person still approves the merge.

• From the code host

  On Forgejo or GitHub, assign Scout an issue or mention @scout in an issue, pull request or comment. It works in a thread in the repository's channel and answers there too.

• Ask it things

  Not every request is a change. Ask how the code works, where something is documented, or how a service has been running in production, and Scout answers in the thread, with a pull request only when there's a change to make. It reads the repositories and their docs and its earlier threads, and, through read-only MCP servers on the host, Grafana (metrics, logs, dashboards, alerts), CI logs and Gatus checks. A tool that changes things waits for an approval first.

• The alert responder

  Scout watches Gatus and Grafana and looks into each new alert in a public thread in the channel that owns it, mentioning whoever is on call. It says when the alert clears, and a flapping alert stays in its thread.

• A step in Workflow Builder

  On Slack plans with custom steps, Workflow Builder gets an Ask Scout step. Give it a public channel, who's asking, a request and any context, such as a form's answers or an alert, and it starts a Scout thread there and hands the thread's link on to the next step. The request is checked like anyone's, and the thread says it came through a workflow.

• Schedules

  “Every Monday at 9, check for dependency updates.” Each run is a new thread in the channel, and anyone there can list, change, pause or remove the channel's schedules by asking.

• All your code, and beyond it

  Any thread can search and read every repository Scout works in, and its earlier threads. MCP servers for the data warehouse, traces and CI run on the host, read-only by default.

• Roles and approvals

  Requests can be limited to people who can change the repository, found through your identity provider and the code host. Groups decide who approves changes made through tools, one approval per change, and every request, tool call and approval goes to an append-only audit trail.

• Spend limits

  Weekly budgets per channel, in dollars, and per-run limits on tool calls and cost. Each answer says what it cost against the week's budget, and requests over the concurrency limits queue, with Scout saying where they are in line and roughly how long.

• As proactive as you want

  One setting decides how much Scout does without being asked, and Scout says which when it starts. Requests from people are never affected.

  • askedonly what people ask for
  • ownalso looks after its own work
  • teamalso alerts, reminders and summaries

• Evaluate different approaches Experimental

  Ask Scout to try a few ways and it works on them side by side, then lets you pick one from a comparison in the thread.

Running it

Scout is meant to be installed and run by people who didn't build it, on a small machine: two cores and 4 GB is plenty, since the work happens in sandboxes.

• Deploys any time

  npm run deploy refuses a commit CI hasn't passed, then drains Scout: running steps finish, no new ones start, and after the restart each run carries on from the step it stopped at.

• Fallback models

  When a model's provider goes down, its calls go to the first fallback that's answering, and threads carry on instead of failing. Scout tries the model again after a while, and says in the thread which model answered.

• Backups that say so

  Litestream copies both databases off the machine. If a change goes uncopied for 15 minutes, the doctor fails, the dashboard shows a red line and Scout says so in its home channel.

• Telemetry

  Each run is an OTLP trace, with a span per tool call and Pi Durable's own spans for every model call, plus Prometheus metrics at /metrics and /healthz for uptime monitors.

• The doctor

  npm run doctor, or /scout doctor, checks Slack, the code host, every repository, the model, backups and the running Scout, one line each, and says how to fix what isn't right.

• Secrets

  Any secret can come from a file, a systemd credential or 1Password, and kill -HUP reads them again. Sandboxes never get one.

Watching it work

A read-only dashboard, after spoond's, live over a stream: what Scout is working on now, its merge rate this week and the week before, which model is answering and what it falls back to, runs and sandboxes against their limits, recent threads, the learning loop, spend by model and by channel against its budget, the notes nobody has reviewed yet, reviews in progress and the schedules.

Get started

Node 24, Docker and git with access to your repositories. Give Scout its own code host account, token and SSH key, so its work is its own. The setup guide goes from nothing to Scout answering in a channel.

$ git clone https://github.com/jrimmer/scout.git && cd scout
$ npm ci
$ docker build -t scout-sandbox:latest sandbox    # your repos' toolchains go in sandbox/Dockerfile
$ cp .env.example .env                            # create the Slack app from slack-manifest.yaml
$ npm run doctor                                  # checks everything, says how to fix it
$ npm start

Tell it who may ask for work (step 8 of the guide), then invite Scout to a public channel and mention it. For the learning loop, put profile/ in a repository of its own.

Read more

• Setup Slack app, code host, repositories, sandboxes, model
• Operations Deploys, sandboxes, alerts, backups, budgets, capacity
• Security What each part can reach, prompt injection, data
• Design What Scout takes from River, and what it left out
• Evals Testing Scout's changes
• Releasing How a release is made
• Changelog What changed, and what to do about it
• Pi Durable The durable agent runtime under every thread