# What you get

The [README](../README.md) is the short version. This is each part of it, with
the commands.

## Instructions picked for the job

There are 104 specialists built into the binary: foundations, modes, languages,
frameworks, databases, platforms, clouds, functional areas, skills and the roles
a team run gives its nodes. Instead
of one enormous prompt that's mostly irrelevant, Loadout works out which ones
your task needs from the repo you're in and the words you used, then tells you
why it picked each one.

```console
$ loadout instructions explain "why is this postgres query so slow" --mode investigate

language
  + C#                     language.csharp        300 .cs files
framework
  + .NET                   framework.dotnet       Microsoft.Extensions. dependency declared
database
  + PostgreSQL             database.postgresql    task mentions "postgres"
function
  + Debugging              function.debugging     task mentions "why is"
  + Performance            function.performance   task mentions "slow"

Context
  Estimated instruction tokens: 2,403
  Budget: 12,000
  Usage: 20%

Where guidance overlaps
  C#: follow framework.dotnet over language.csharp (narrower scope composes last)
```

You can see the whole set, what it'll cost you in tokens, and where their
guidance overlaps, before anything launches. Add an `--against-`
option and it shows only what changes:

```console
$ loadout instructions explain "why is this postgres query so slow" \
    --mode investigate --against-task "add a retry to the upload step"

- database.postgresql                   297  task mentions "postgres"
- function.database                     223  task mentions "query"
- function.performance                  217  task mentions "slow"
- function.debugging                    183  task mentions "why is"
+ function.distributed-systems          172  task mentions "retry"

  Unchanged  7
  Estimated  2,403 to 1,655 (-748)
```

Lines both sides share get counted rather than listed, since they aren't the
question, and the costliest change comes first, because anyone comparing
configurations is usually trying to get under a budget. If it picks something
daft, rule it out with `--without`.

## Memory that doesn't grow forever

`loadout memory` keeps the durable facts about a project: decisions and why you
made them, constraints, the traps that keep catching people. The useful bit is
`memory compress`, which pulls facts out of always-loaded instruction files and
into the memory store. What every session pays for gets smaller; what it can
look up stays the same. `memory audit` goes looking for secrets, duplicates and
stale entries — and a fact pinned to the day it was written, or already past its
own date, is a warning rather than an aside, because those are the two kinds
that turn from true into misleading with nothing in the store to catch them.

Only the index reaches a session, so the question is which topic to open.
`loadout memory find "why did the release not publish to winget"` answers it
with the same ranking the agent's own `loadout_recall` uses. Two rules keep it
honest: repetition saturates against how much a topic says, so the longest topic
can't accumulate its way to the top of every question; and a term in a curated
name or description outweighs the same term buried in prose, because mentioning
a subject is not being about it.

`memory import` compares topics on what they say rather than on their bytes, so
two stores that keep the same names and disagree get told apart. A copy that
differs is named and left exactly where it is — which of two accounts is right
is a judgement, not a merge.

## Where the tokens went

```sh
loadout usage --days 7 --by day
```

No setup, no opt-in. It reads the transcripts your agents already write, so
there's history from the day you install it, including sessions from before.
Break it down by project, day, model or agent.

Cache reads are counted at their real rate rather than as fresh input, which
matters more than it sounds: on a long session the difference is most of the
number. If a total is incomplete it says so instead of quietly showing you a
smaller one.

There's also `loadout telemetry serve`, a local OTLP receiver for agents that
emit OpenTelemetry. Optional, and local means local: no service, no account,
nothing sent anywhere, counts only.

## Repos that stay clean

`loadout protect` sets up the Git protections. Because hooks live in
`.git/hooks` and never travel, a fresh clone is unprotected until somebody
notices — so a launch says so on the way in, while it can still be acted on. It
warns and never blocks: an unprotected repository is still one you may have good
reason to work in. A working tree keeps its hooks in the repository it was made
from, and there the launcher says nothing rather than reporting a problem you do
not have. `loadout migrate` moves whatever
is already scattered around into the workspace, showing you the changes first
and taking a snapshot you can restore. `loadout drift` tells you when a project
has wandered from what you configured.

## A launcher as well as a command line

![The launcher](images/launcher.svg)

Run `loadout` on its own. Every row tells you whether you can work on that
project, and the panel on the right shows what a session would start with, so
you know before you spend one.

Enter opens the launch sheet: which agent, what the task is, how to work, and
which profile or worktree, all filled in with the defaults so Enter again
starts the session. Underneath, the sheet shows which specialists that task
would load and what they cost, re-resolved as you change it, by asking the same
resolver the launch asks. What it shows is what the session gets.

The task line — the field that decides most of what a session gets — is filled
in from what the project has already declared with `loadout task declare`. It
was typed twice in 122 launches here, because a blank line asking for a sentence
gets answered by starting work instead. Correcting a line somebody already wrote
is a much lower bar than composing one, so what's on record goes in the field as
editable text and anything else is named beneath it. Only when the field is
empty: a task you typed first is never overwritten.

The corner says which build you're running, and whether there's a newer one —
`v1.2.0 · 1.3.0 available`. The launcher on your PATH can quietly fall three
releases behind the one you think you're running, which is an afternoon lost to
a feature that isn't in the binary yet. The check happens once a day in the
background, never delays the screen opening, and never puts a failed lookup on
screen.

`Ctrl+P` opens a palette over every command the CLI has, and it finds them by
what they're for. Search `undo` and you get `backup restore`. Search `broken`
and you get `doctor`. Nobody looking to undo a mistake searches for the words
"backup restore".

The launcher doesn't implement any command itself. Whatever you pick runs
through the same parser you'd have typed at, and a test checks that.

## The agent can ask back

The session you launch is told `loadout` is on PATH, and gets the same few
operations as MCP tools: read a specialist in full, ask what it was given and
why, search what the project already knows before working it out again, write
down one fact worth having next time, and change its own mode when the work
changes shape.

Being able to look something up and choosing to are different things. The memory
index sat in every compiled context for months and was acted on once in twelve
thousand turns, because "read the ones that bear on the task" leaves a session
to notice mid-work that one of twenty-four titles might have applied. So the
context now names the occasions: before diagnosing a failure, before an
unfamiliar error, before anything about how this project builds, tests, releases
or is configured, and before writing down a fact of its own, so an existing
topic gets extended rather than contradicted by a second one beside it.

The other way round was tried first — a hook that searched memory on every
prompt and put the matches in front of the session unasked. Measured against 322
real prompts it spoke on 56% of them when 18% had anything relevant to say, and
it was removed. A fact arriving unasked reads as though the launcher vouched for
it, so being wrong a third of the time costs more than saying nothing.

It isn't offered anything that changes your machine or pushes to a remote, and
the context says so rather than leaving it to be worked out. Ask an agent to
review a repository and it has a procedure to follow — `skill.repository-review`
— and somewhere to put what it finds.

It can also read and update what the project is working on. `loadout task`
keeps that record — open, doing, done, blocked or dropped, each with who said
so and when — and checks it against the repository, which is how "called done,
and nothing has been committed since" gets said out loud. A project that sets
`tasks: true` under `context` puts the open entries in front of every session,
so the answer to "where were we" comes from the record rather than from
whatever is still in the conversation. They are observations, never verdicts:
corroboration can say a claim is unsupported and can never say one is wrong.

## Code that isn't a repository yet

`loadout project add` takes a directory with no Git repository in it. It
registers as one still to be set up, with a task saying so, and the launch says
so too — the first session gets told on the way in instead of finding out by
running something and reading an error. Initialising it, the first commit and
the remote are the work. `loadout protect` comes after, and isn't suggested
before there's anything to protect. A path that doesn't exist is still refused,
because that's a typo rather than a plan.

`loadout project discover` and the launcher's Add Project list offer these too,
marked as not repositories, because a list of things you can register that
leaves out a kind you can register isn't a list you can trust. They're never
swept up by a bulk registration: a scratch folder doesn't become a project
because somebody asked to register everything they'd cloned. Build output —
`__pycache__`, `dist`, a screenshots folder — stays out of the offer, though
it's still walked through in case a repository is buried in one.

## A first project from nothing

`loadout start` is for somebody who has never had a project: new to
programming and to agents both. It checks Git, a name in Git, an agent and
Loadout's own setup, and for whichever is missing prints the line to type for
this operating system and offers to look again. It never runs an installer.
Somebody new to this learns more from typing the line than from a launcher
that changes their machine, and Loadout doesn't install the agents it starts
anywhere else either.

Then it makes the project from a starter (a web page, a checklist, or an empty
folder for your own idea), every one of which needs only a browser, because a
missing runtime would make the first project fail for a reason that has
nothing to do with it. Git, registering and `loadout protect` come with it.

The planning and the building are handed to an agent, in two sessions: advise
first, ending in a `PLAN.md`, then implement. Each is previewed and asked about
separately, because each spends from your plan, and `--yes` covers the machine
steps only. Run it again and it carries on from the first step not done.
[Your first project](plain/your-first-project.md) walks through it.

## Undo

Every command that changes a file takes `--dry-run` and shows you the change
first. Anything that did change is in a snapshot you can put back:

```sh
loadout backup list
loadout backup restore 20260901-204044-fd3512
```

## Several agents on one goal

```sh
loadout team run bug-hunt "the config loader throws on a missing file"
loadout team status
```

A lead splits your goal into requests, workers do the work in their own
sessions, and the lead reads what came back and decides what to ask for next.

Each node is an ordinary Loadout launch — same project, same compiled
instructions, same screening — so what a team adds is who asks whom and what a
run may spend before it stops. Workers that may run together do, each in its own
git worktree, and a branch that conflicts goes back to whoever wrote it.

A run can be started by hand, on a schedule, or when the repository moves. Watch
one with `team status`, in the launcher, or on a page `loadout dashboard` serves on
this machine. The page runs and writes teams as well as watching them, and every
control on it types the command you would have typed.

Eight teams ship. A team is a YAML file, so you can write your own, and copying
one that already works is the way to start:

```sh
loadout team list
loadout team new docs-crew-mine --from docs-crew
loadout team edit docs-crew-mine
```

The copy keeps the original's comments and ordering rather than being
regenerated from it, and `team show` checks the result — a team naming a role
that does not exist is a finding there rather than a failure half way through a
run. `team remove` moves one you wrote to the bin, and `team restore` brings it
back; the ones that ship and the ones from a pack are refused, because the next
`pack update` would overwrite anything you changed in them.

Every run keeps what it wrote down, and you can clear out the ones you are done
with:

```sh
loadout team runs prune --keep 20 --older-than 30d
loadout team runs prune --failed
```

You can pick by how a run ended as well as by age: `--failed`, or `--outcome`
with any of `done`, `failed`, `stopped`, `limited`, `blocked`, `needs-decision`
and `unrecorded`. An ending nothing recognises is never taken by one of those —
asking for the failed ones means the ones known to have failed, not everything
that could not be ruled out.

It will not take a run that is still going — a gate is answered by a file
appearing in the run's directory, so deleting one under a live run leaves
processes waiting on answers that can no longer arrive — and it will not
silently take a run that left a branch nothing merged. `--dry-run` lists what it
would take and why it is keeping the rest.

What it takes goes to the bin rather than away: `loadout team bin` lists it,
`loadout team runs restore <run>` puts one back, and it is deleted for good after
30 days, or whatever `team-bin-days` says.

## A dashboard for the runs

```sh
loadout dashboard --open
loadout dashboard --watch-only
```

`loadout dashboard` serves a page on this machine, at a loopback address behind a
token that changes every start. Runs are grouped by what they want from you —
*Needs you* first, then *Running*, then *Finished* — because the run waiting on
you is the one most easily missed further down a list. There are five screens:
List, Office, Graph, Timeline and Terminal; what hasn't become a run yet waits
in the office's lobby. The controls are in the detail pane and in the office's
rooms, and each one runs the command you would have typed.

It fetches nothing: no webfont, no stylesheet, no image. A dashboard that pulled
a typeface from the internet would not work on a machine with no network, which
is often the one it is most wanted on. `--watch-only` is for a screen in a
corner: the server refuses anything that would change a run, and the page puts
its controls away.

Which page you get follows your accessibility profile — plain under
`screen-reader`, `low-vision` or no colour, rich otherwise — and `--view plain`
or `--view rich` chooses for one start. The guide is
[using the dashboard](guides/dashboard.md); the detail is in [Teams](teams.md).

## Told once how you read

```sh
loadout config set accessibility-preset dyslexia
```

One setting changes how the agent writes to you, what it draws, and what
Loadout prints. It is never detected: you turn it on, and the first line of
output names the profile so you can see it took. There are six presets, named
for what they reduce rather than for a condition, and every setting in them can
be changed on its own.

The dashboard was built to WCAG 2.2 AA from its first commit, and axe-core
4.10.2 finds no violations in any of fifteen states across both pages. No
screen reader has been used with any of it, and no keyboard-only pass by a
person has been recorded. Speech is built, and has been heard only through the
Windows system voice, never through a screen reader, which is why it stays off
until you set `show-speech`.

The guide is [setting up accessibility](guides/accessibility.md); the full
statement is [Accessibility](accessibility.md).

## Also in the box

A session that ran for a while and left no handoff is told so on the way out,
with the command to write one. Said rather than done: a handoff written
automatically would be a document with nothing in it, and the next session would
be handed something that says nothing and believe it had been handed over to.

Session listing and resume across agents, cross-agent handoff documents, MCP
servers managed per project, secrets in the OS credential store, context
profiles, project templates, editor integration, and a status line with project,
branch and context usage. `loadout doctor` checks the lot.


## See also

- [Recipes](recipes.md) — worked answers to the common jobs
- [The launcher](launcher.md) — the terminal UI in detail
- [Specialists and skills](specialists.md) — how an instruction set is composed
- [Teams](teams.md) — several agents on one goal, and writing your own team
- [Accessibility](accessibility.md) — how you are written to and asked, and what was verified
- [Guides](README.md#guides) — the same ground, one job at a time