# Commands

| Command | Purpose |
|---|---|
| `loadout` | Full-screen launcher, or first-run setup |
| `loadout setup` | Configure the launcher on this machine |
| `loadout start` | Make your first project, step by step, with an agent to help plan and build it |
| `loadout <project>` | Launch the project's default agent |
| `loadout here` | Launch the agent for the current repository |
| `loadout launch <project>` | Launch an agent against a project, which is what naming one on its own does |
| `loadout doctor` | Platform, Git, workspace, secret and agent diagnostics |
| `loadout status` | Summary of workspace, projects and agents |
| `loadout project add\|list\|show\|remove\|discover\|open` | Manage project registration. A directory with no repository yet is registered, and discovered, as one still to be set up |
| `loadout project new <name>` | Create a project, optionally from an existing one as a template |
| `loadout project clone\|relocate <project>` | Get a registered project onto this machine |
| `loadout project survey [--adopt]` | Find agent state no project accounts for, and take on what it can |
| `loadout project link [project]` | Record inside a repository which project it belongs to |
| `loadout project context [key] [on\|off]` | Show or change what the project carries into every session: its open tasks, its code map |
| `loadout project onboard [project] [--skip]` | Onboard a project now in an agent session you watch, or record that it is skipped |
| `loadout project proposal [project] [--apply\|--discard]` | Show the settings change a session proposed, then apply or discard it |
| `loadout code [project]` | Open a project in the editor, under the profile its agent uses |
| `loadout config list\|get\|set\|edit` | Read and write launcher settings, and say where they live |
| `loadout workspace status\|sync\|save\|open` | Manage the central workspace clone |
| `loadout desktop` | Install the Start Menu or `.desktop` entry |
| `loadout update` | Check the release source and install a newer build |
| `loadout secret set\|test\|remove` | Manage credentials in the OS keystore |
| `loadout mcp list\|add\|remove` | Manage the MCP servers a project loads, and see what clashes |
| `loadout mcp serve` | Serve the launcher's own tools to an agent. Started by the agent, not by you |
| `loadout repo check` | Check a repository for tracked AI tooling files |
| `loadout drift [project]` | Show where projects have drifted from their recorded configuration |
| `loadout drift --fix` | Put right the drift the launcher can fix itself |
| `loadout doctor --fix` | Put right the findings the doctor can fix itself |
| `loadout doctor --bundle [path]` | Write the findings to one file to send somebody, screened first |
| `loadout docs audit [project]` | Report where the documentation has come adrift from the repository, and warn where it breaks your learned voice |
| `loadout docs find <name>` | Say where a type or member is declared, from an index kept in step with the repository |
| `loadout docs refresh <file>` | Bring the symbol index up to date for the files named, after an edit; `--hook` is the form an after-edit hook runs, `--dialect generic` for one that is not Claude's |
| `loadout docs ci` | Write a CI workflow that regenerates the documents. A starting point, not a fixture |
| `loadout docs export` | Write a reference, technical guide, user-guide scaffold or machine index |
| `loadout protect --refresh-hook [project]` | Install that hook in the project's Claude settings, or `--remove` it |
| `loadout protect` | Install a pre-commit hook, or `--global` Git excludes |
| `loadout migrate` | Move existing AI tooling files into the workspace |
| `loadout project worktrees <project>` | List a project's working trees |
| `loadout handoff <project>` | Create, show or list cross-agent handoffs |
| `loadout profile list <project>` | Show a project's context profiles |
| `loadout rules list\|budget\|audit <project>` | Inspect the instruction rules and what they cost |
| `loadout rules split <project>` | Break an oversized instruction file into scoped rules |
| `loadout memory list\|write\|audit\|reindex <project>` | Record and check durable project facts |
| `loadout memory import <project>` | Bring in memory an agent recorded outside the workspace |
| `loadout memory audit --clean <project>` | Remove empty topics, exact repeats and dead index lines |
| `loadout memory review [project]` | Walk the topics nobody has revisited, and keep or expire each |
| `loadout memory find <query>` | Find the topics that answer a question, rather than reading the index |
| `loadout memory write --separate` | Start a new topic even though existing ones cover similar ground |
| `loadout memory write --scope user|machine` | Record a fact true of your work, or of this computer only |
| `loadout memory compress <project>` | Move durable facts out of always-loaded instructions into memory. A heading whose name is already a topic merges into it, keeping that topic's description, kind and everything it held, and a fact it already holds is not written twice. `--apply` backs up the file and the topics first |
| `loadout memory delete <topic> [project]` | Delete a topic after backing it up. Topics that link to it are named and left as they are; `--dry-run` shows both |
| `loadout sessions` | List recent agent sessions across every agent, newest first |
| `loadout launches [project]` | What this machine launched, and what each launch was given |
| `loadout resume [session]` | Reopen a previous session, with a picker when none is named |
| `loadout instructions list\|show\|explain` | Read the specialists, and see which ones a task would load |
| `loadout instructions explain --against-mode\|--against-task` | Show only what changes between two ways of asking |
| `loadout instructions audit\|validate` | Check a project against what its specialists ask for, or check the library itself |
| `loadout instructions new <id>` | Draft a specialist or skill in the workspace, or in one project |
| `loadout style list\|show\|use` | See your coding styles, which are in force for a project, and choose the named one it uses |
| `loadout instructions explain --style <name>` | See what a task would load under a different named style |
| `loadout voice show\|check\|mark` | See the writing rules in your voice profile, check a doc or commit message against every guide's rules, and mark what you wrote by hand |
| `loadout voice learn [--guide] [--dry-run] [--pull-requests] [--transcripts]` | Learn writing rules from the sources a guide lists, such as your squash merges, marked writing or what you typed to Claude Code, then accept, edit or reject each one, and score them against writing held back |
| `loadout voice runs` | Past learn runs: how each ended, how its cap was set, what it cost and how its rules scored |
| `loadout voice render [--force]` | Render your voice into the style specialist your sessions load. A learn run does this itself |
| `loadout voice guide list\|show\|draft` | See the guides voices are learned against, and draft a new one with an agent, saved only once you have reviewed it |
| `loadout instructions export <specialist>` | Copy a built-in specialist into the workspace so it can be edited |
| `loadout instructions stats` | Say which specialists launches actually reached, and which none did |
| `loadout instructions probe [specialist]` | Say how often sessions did what a specialist asks for, week by week |
| `loadout usage [--days|--by|--project]` | What the agents have spent, by project, day, model or agent |
| `loadout usage --format markdown\|csv` | The same report written to send somebody, or to open in a spreadsheet |
| `loadout telemetry serve\|status` | Receive, locally, what launched agents report about their own usage |
| `loadout statusline install\|uninstall\|show` | Put the project, branch and context spent in the agent's status line |
| `loadout backup list\|restore` | Undo an operation that changed files |
| `loadout completion <shell>` | Emit a completion script |
| `loadout commands` | List everything the launcher can do, grouped by what it is for |
| `loadout list` | List registered projects |
| `loadout running` | The sessions running now, and how long each has been quiet |
| `loadout task list\|declare\|remove` | Record what is being worked on, and check it against the repository. `--global` is the list for what belongs to no project yet |
| `loadout idea add\|list\|show\|remove` | Drop an idea in, on a project or the workspace-wide list, to be fleshed out later |
| `loadout idea refine <id>` | Have an agent take an idea one round further: ask its questions, propose a plan with options for each layer, or revise it. It asks the agent and model the last round that came back used, unless you give `--agent` or `--model`, and says which before it starts. One round per idea at a time on this machine |
| `loadout idea dismiss <id>` | Clear the "last round failed" marker on an idea you have stopped refining, without paying for another round. Answers and the plan stay |
| `loadout idea answer\|choose\|keep\|drop\|improve` | Answer the agent's questions, pick an option for a layer, keep or drop a piece, or ask for one to be reworked. An answer or request that starts with a dash goes as `--answer=` or `--request=` |
| `loadout idea accept <id>` | Write the plan out and turn the idea into a task on its project, or on a new one with `--new-project` |
| `loadout idea dump add <file\|->` | Drop in notes kept elsewhere, from a file, standard input or `--text`, and have an agent split them into separate ideas and tasks, each carrying its own words from the notes |
| `loadout idea dump list\|show\|split\|apply` | See the notes dropped in, split one again, and record the pieces you want, all or `--only 1,3` |
| `loadout tools search\|show\|submit\|used` | The tools this machine shares between every team: find one before building it, send in a candidate, idea, bug or lesson, and say how a use went |
| `loadout tools audit\|verify\|promote\|deprecate\|retire` | Look after the catalogue: what happened to it, whether its files still match, and a tool's way in and out |
| `loadout tools health [name]` | How each active tool is doing beyond passing its cases: how long they took, how often recent uses failed or were worked around, how big it has grown, and whether anyone still uses it |
| `loadout tools trust <name@version> [--revoke]` | Agree that one version's script may run on this machine, as it is now |
| `loadout tools verify <draft> --agree` | Answer a held verify yourself: it shows the script and the cases it would run, asks, and runs them if you say yes. Only at a terminal, so an agent cannot say yes for you |
| `loadout team list\|show\|run` | Run a team of agents against a project: a lead that briefs workers and reports to you |
| `loadout team new\|edit\|remove` | Write a team of your own, open its file, or move it to the bin |
| `loadout team restore <team>` | Put a team back from the bin where it was, the copy removed most recently. Refused while a team of that name exists |
| `loadout team run <team> "<goal>" --done-when` | Say what the run is judged on, one per use. The lead must report a verdict and evidence for every one |
| `loadout team run <team> "<goal>" --no-project-done-when` | Hold this run to none of the project's standing done-when (`teams: done_when:` in its `project.yaml`), or leave out one with `--drop-project-done-when`. The journal records what was left out |
| `loadout team run <team> "<goal>" --usd` | What this run may spend in all, over the team's own budget: a figure, or `none` for no cap |
| `loadout team capabilities` | The machinery a team's declarations can ask for, and what each one needs |
| `loadout team runs\|status\|log` | What the runs did: where each node got to, and everything one wrote down |
| `loadout team runs remove\|prune` | Forget runs you are done with, one by one or by age, count or how they ended. They go to the bin, not away |
| `loadout team runs restore <run>` | Put a run back from the bin. Refused while a run with that identifier exists |
| `loadout team bin` | What is in the bin: each run and team, when it was removed, how many days it has left and its size |
| `loadout team bin empty [--older-than <age>]` | Delete what is in the bin for good, all of it or only what is older than the age. Asks first, and needs `--yes` where nobody can be asked |
| `loadout team outbox` | The files a run delivered, resolved from the commits its nodes reported |
| `loadout team remedies` | What a team has worked out how to fix, and whether it is trusted here |
| `loadout team remedy show\|trust\|requests` | One remedy in full, trusting or untrusting it, and the remediations waiting on you |
| `loadout dashboard` | Every run at once, live, on a page: the daemon's if one is serving, otherwise a new one here |
| `loadout dashboard sign-out` | Sign every browser out of the dashboard on this machine, including in a daemon that is already running |
| `loadout team office check <set>` | Whether an office set's kit (with its rules) or tile scene can be used, and each thing wrong with it by name. A kit may lack parts: it lists which, and those are drawn in the built-in kit's shapes meanwhile |
| `loadout team schedule add\|list\|remove` | Runs that should happen again and again on this machine |
| `loadout daemon` | Stay running: fire the scheduled runs and serve the dashboard |
| `loadout daemon stop\|restart\|pause\|resume\|continue` | Control the running daemon from any shell: stop or restart it once its runs finish (`--now` does not wait), or hold and release its schedules |
| `loadout team webhook enable\|disable\|show` | Let something outside this machine start a run, or stop letting it |
| `loadout daemon autostart enable\|disable\|show` | Start the daemon when you log in, per user |
| `loadout team gate` | Answer something a run stopped to ask |
| `loadout team message` | Say something to a run's lead, read at its next round |
| `loadout team halt` | Stop a run after its current round, hold it, or let it carry on |
| `loadout team budget` | Change what a running team may spend in all, from its next round on: a figure, or `none` for no cap |
| `loadout team resume` | Pick up a team run that has ended, where it stopped: `--usd` for more money or `none` for no cap, `--rounds` for more rounds, `--message` for the lead. Says what the lead's next turn is likely to cost first |
| `loadout team name` | Name a run's room, or clear the name to get the worked-out one back |
| `loadout team pr` | Open a pull request for what one node of a run produced |
| `loadout team say` | Say something to one node while it is still working |
| `loadout team attach set` | Set the passphrase that lets the dashboard type at a running node |
| `loadout team attach show` | Say whether one is set, never what it is |
| `loadout team attach clear` | Forget it, so nothing can type at a running node |
| `loadout team notify set\|test\|show\|clear` | Send a run's call for help to Slack, Discord, Teams, Telegram or your own endpoint |
| `loadout checkpoint create\|list\|restore\|remove` | Mark where a project stands, under a name you can return to |
| `loadout pack list\|add\|approve\|update\|remove` | Sets of specialists, roles and teams fetched from a Git remote, approved per machine |
| `loadout share candidates\|promote` | Find guidance that belongs to everybody, and move it deliberately |
| `loadout spend refresh` | See and refresh where spending stands against your thresholds |

**The dashboard and the daemon are top-level commands,** because what they serve
is no longer only about teams. They used to live under `team`, and the old names
(team dashboard, team daemon and team autostart) still work, so a scheduled task,
a login entry or a line somebody wrote down keeps running.
`loadout daemon autostart show` says when your login entry still uses the old
name, and `loadout daemon autostart enable` rewrites it.

**Every command that can change something accepts `--dry-run`,** and it always
means the same thing: show what would happen and change nothing. Several
commands have their own older spelling — `--apply` on some, `--fix` on others —
and those still work; where both are given, the more cautious wins.

For a launch, the dry run is the whole launch described: the agent and its
executable, the working directory, the compiled context and where it went, the
MCP configuration files, the environment variables by name, the full command
line, and every specialist chosen with the reason for each and what it costs.
`--json` writes the same thing as one document. Values are never printed —
a resolved secret is exactly what a variable can hold.

Every command accepts `--json`, and everything after a bare `--` is passed to
the agent untouched:

```bash
loadout starstats --agent claude --profile database -- --verbose
```

Exit codes are stable and documented in
[`ExitCode.cs`](../src/Loadout.Models/ExitCode.cs). One is worth knowing before
you script against it: `loadout` with no arguments and nowhere to draw exits
**11**, not 0. It's the documented way to open the launcher, so the arguments
were fine — what was missing was a terminal. A script that reaches that has
asked for the interactive launcher by mistake, and saying so beats succeeding
quietly.

## Editors

VS Code keeps settings, extensions and keybindings in named profiles, and
working with an agent usually wants a different set from working without one.
`loadout code` opens a project under the profile that suits it, so opening the
same repository for Claude and for Codex can put the editor in two different
states.

```yaml
# config.yaml
editor:
  command: code          # or code-insiders, codium, cursor
  profiles:
    claude: Agents
    codex: Codex
```

It uses the project's own profile if it names one, then whatever's configured
for the agent it uses, then none. So if you don't use profiles, you get the
editor you always get.

```bash
loadout code                            # this repository, its agent's profile
loadout code starstats --agent codex    # that project, as Codex would want it
loadout code --editor-profile Agents    # this profile, whatever is configured
```

`--editor-profile`, not `--profile`: that one already exists and means a context
profile — which instructions an agent loads — and has nothing to do with the
editor.

Profiles are opened, never written. Their contents live in a layout the editor
does not publish, and rewriting it would be a promise that could not be kept
across editor versions. Reading it to report on it is a different matter, so
`loadout doctor` says which editor was found and which profiles exist, and warns
when a project or an agent names one that does not. Where the profiles cannot be
read at all it says so rather than reporting them as missing — a wrong "that
does not exist" sends you looking for a problem you do not have.

## Sessions

Each agent records its own conversations in its own private layout, and neither
can say which project a session belonged to. `loadout sessions` reads both and
attributes them:

```text
1 minute ago   claude storefront-api     Fix the upload path
5 minutes ago  claude storefront-web     Redesign the settings screen
2 days ago     codex  storefront-api     Tidy the deploy script
```

`loadout resume` opens a picker, or takes a session id or `--last`. Resuming
goes through the launcher rather than straight to the agent, so the workspace
syncs and the context recompiles instead of just reopening a bare transcript.
The task, mode, profile and worktree the session launched with are read back
from the launch ledger and carried over, so it reopens with the specialists it
had. `--task` and `--mode` replace them when the work has changed shape, and
`--task-id` links the resumed session to a recorded task, as it does on
`loadout launch`. The
interactive launcher offers the same picker per project.

Neither storage format is a published contract, so both readers are best-effort
by design: a transcript nobody can make sense of costs you that one session,
never the listing.

What a session *isn't* is anything the agent spawned inside one. Claude Code
grew a folder of subagent transcripts beside each session's own, and reading
every `.jsonl` under a project folder turned all of them into resumable rows:
39 subagent files against 13 real sessions here, a picker full of research
prompts, and the real sessions pushed off the end by the limit. The listing now
reads each project folder's own files and goes no deeper, with a name guard
beside that, because the layout has already moved once and nothing inside such a
file marks it out. The limit is also applied after the read rather than before,
so it's spent on sessions rather than on whatever happened to be newest.

Nor is it anything Loadout started with nobody at a terminal. Every team node,
idea round and dump split leaves a transcript like any other, in the project it
worked in, and a few runs were enough to bury your own sessions under them. The
launch ledger now notes each one's session id the moment the agent names it, and
every list you resume from leaves those out: `session list`, `resume` and the
launcher's recent sessions. `session running` still shows a live node, marked
headless, because a team at work is worth seeing.

Claude Code's own `/resume` picker reads its projects folder directly, so the
only way out of that list is out of the folder. When a node finishes, Loadout
moves its transcript, and the folder of subagent files beside it, into
`headless/transcripts` under its state directory, and puts it back just before
anything resumes it: a team picking up its lead, or you taking a node over with
`loadout resume <session id>`. Naming the id in full is what reaches it; the
picker leaves nodes out. You don't have to dig for the id: once a run has ended,
`team status` prints the whole command under each node, and picking a node
under "What it said" on its dashboard page shows it with a button to copy it.

A moved transcript is kept as long as Claude would have kept it, its own
`cleanupPeriodDays` or thirty days, because out of Claude's folder it's out of
reach of Claude's clean-up. One the agent is still holding is left where it is
rather than fought over. Runs from before any of this are caught up on once,
from their journals, which name every node's session; idea rounds and dump
splits from then left no record of theirs, so those stay listed until they age
out.

Rows are escaped before they're drawn, too. A session is named after the first
thing said in it, and whoever said it was writing prose — a title opening with
`[SYSTEM NOTIFICATION]` was read as a style tag and took the whole picker down
with it, which looks like Resume crashing rather than like one row being
unprintable.

## Launches, which are not sessions

`loadout sessions` reads the transcripts the agents write and says what a
conversation was about. `loadout launches` reads what this launcher recorded as
it started one, and says what it was told to be — the mode, the profile, the task
and every specialist composed into it.

```console
$ loadout launches --show aa11
StarStats  aa11bb22

  Started       2026-09-04 00:31:42Z
  Agent         claude
  Mode          implement
  Outcome       ok
  Ran for       31 minutes
  Task          fix the upload path
  Instructions  2,400 estimated token(s) against a budget of 12,000

Composed  3
  foundation.change-safety
  foundation.verification
  language.csharp
```

They're separate lists on purpose, and neither turns into the other: an agent
picks its own session identifier and the launcher never learns it. This also
won't tell you what a launch spent. Token counts are aggregated by directory and
day, so pinning them on one of the three launches you made that day would be
arithmetic dressed up as fact. The tokens shown are the instruction tokens the
launcher estimated and recorded, and those really are per launch.

A launch has three outcomes rather than two. `unclosed` means no ending was
recorded — killed, terminal closed, or still going — and `never ran` means it
ended without the agent starting. Calling either a failure would invent a result
neither has.

## Documentation that still describes the code

Loadout checks its own documentation three ways, by hand: a test that every
command the docs name exists, one that the install examples name the version
that ships, one that the specialist count is the count. Each guards a way prose
rots while still reading perfectly — a table naming sub-commands that were
renamed, a total left behind by the thing it counts, a download link pointing at
a version no longer at the top of the releases page. `loadout docs audit` is
that habit offered to any repository.

```console
$ loadout docs audit
+ 20 document(s), every reference resolves.
```

It reads `docs/` and the Markdown beside the root README, and reports three
things: a link that goes nowhere, a named file that isn't in the repository, and
a page nothing links to. It reports and changes nothing — what to do about a
stale page is a judgement about a codebase.

What it deliberately stays quiet about is the more interesting half. A URL, an
anchor, a home-relative path and anything holding a `<placeholder>` are all left
alone. So is a backticked path that doesn't start at a directory the repository
actually has: pointed at this project first time round it produced seven
findings and every one was wrong — an invented Rust path inside a paragraph about
deriving globs, and a table addressing real files relative to `src/<project>`
rather than the root. A check that's wrong about seven good references and right
about none is one you turn off.

### Numbers in prose

A project can also say which of its numbers have a right answer. The policy
lives in the workspace, at `projects/<slug>/docs.yaml`, so the repository keeps
holding source and the rules about it live elsewhere:

```yaml
root: docs
counts:
  specialist: "src/Loadout.Core/Specialists/**/*.md"
counts_exclude:
  # A page whose figures are about somebody else's library rather than yours.
  - vendor-comparison.md
```

This is the drift that rots invisibly, because the sentence still reads
perfectly. A page can claim a total the library passed months ago and nothing
about it will look wrong. Keyed by the singular; the plural is
derived, because writing both out is configuration nobody keeps in step. The
number one is never read as a total — "the full text of one specialist" is a
quantity in a sentence, and prose is full of them.

`counts_exclude` is there because counting assumes a noun means the same thing
on every page, and sometimes it doesn't. A page comparing your library against
somebody else's, or quoting figures from a specification, reports as stale on
every number it contains — and every one of those numbers is right about the
thing it actually describes. A project with no policy still gets all the checks
above, which need nothing configured.

## Saving what a session produced

Agents change workspace files during a session — context notes, decisions,
handoffs. When the agent exits, the launcher applies the exit policy from
`config.yaml`:

| `sync-exit` | Behaviour |
|---|---|
| `prompt` (default) | Offers save-and-sync, save-locally, review, or leave |
| `always` | Commits and pushes without asking |
| `never` | Leaves the changes alone |

Whatever the policy, the changes are screened before anything is committed. The
workspace is a Git repository that gets pushed — under `always`, without anybody
being asked — so a credential reaching it is a credential disclosed, and an audit
finding afterwards doesn't undo that. A change that looks like it carries one
refuses the save and names the file and the pattern, never the value:

```text
The workspace was not saved. These changes look like they carry credentials,
and the workspace is a Git repository that gets pushed:
  projects/starstats/handoffs/2026-02-01.md — GitHub token
Take the value out and put it in the credential store with 'loadout secret set',
then save again.
```

Memory is screened as it's written. The same screening applies to everything
else the policy commits — handoffs, project instructions, context notes,
profiles, MCP definitions — and to anything an agent wrote into the workspace
directly, which no check at the point of writing can see. Binary files are left alone. A file that can't be read gets reported rather
than passed, because "clean" is the one thing a scan must never say about
something it never opened.

Commits follow the format in spec section 46, so a workspace history reads as a
record of which machine did what:

```text
agent-workspace: update StarStats context

Project: StarStats
Agent: claude
Machine: DEV-PC
```

A session that only read produces no commit. If a push fails, the commit has
already happened, and the message says so rather than implying your work went
nowhere. The fourth option is deliberately "leave them uncommitted" and not
"discard" — the launcher has no business deleting work somebody just did.

The prompt lives in the CLI, not in core. Core decides whether somebody needs to
be asked; it never asks, because spec section 37 forbids a menu turning up in a
pipe or a CI job. With nobody there, the changes are left in place and it
suggests `loadout workspace save --project <slug>`, for the session's own
project.

A session saves its own project and nothing else. The workspace is shared by
every session on the machine, and saving everything pending used to commit, and
under `always` push, whatever another session had half-written in another
project. Only the files under that project's directory are listed and
committed; if others are pending, you are told in one line how many files
that is, counting each file inside a new folder rather than the folder once,
and they stay where they are. Under `always` you are told even when the
session changed nothing of its own, because nobody is asked.

`loadout workspace save` on its own still saves everything, because that is
what the command is for. `--project <slug>` narrows it to one project, and
`--dry-run --json` then reports that project's count, not the whole workspace's.

## MCP servers

An agent loads MCP servers from several places at once — an account's
connectors, installed plugins, a project file, a user file — and nothing
reconciles them. Nobody sees the whole set until something behaves oddly.

`loadout mcp list` shows it, with where each server came from:

```text
serena              installed  uvx --from git+https://github.com/oraios/serena …
claude.ai Context7  installed  https://mcp.context7.com/mcp
context7            project    https://mcp.context7.com/mcp

claude.ai Context7, context7  the same service under more than one name, so every
tool it offers is loaded twice and the model sees each one twice
```

Servers the workspace declares live there rather than in the repository, and get
handed to the agent with `--mcp-config` at launch. So they're the same on every
machine that clones the workspace, instead of on whichever one happened to have
them configured.

Three things are reported:

| | |
|---|---|
| **The same service twice** | Two names reaching one endpoint. Every tool loads twice and the model sees each capability twice. |
| **A shadowed name** | One name declared in two places. One will not load, and which is not obvious. |
| **A machine-specific path** | A command or argument naming an absolute path. It cannot be right on another machine that clones the workspace. |

`loadout mcp add` runs the same check before writing and refuses a server that
clashes, unless you pass `--force`. Nothing is ever reconciled automatically:
which of two servers should win is a decision, and a launcher is the wrong place
to make it on somebody's behalf.

Only enabled plugins are counted. A plugin that is installed and switched off
contributes nothing, and warning about its servers would describe something that
is not happening.

### The launcher's own server

Every launch declares Loadout itself as an MCP server, so the handoff runs both
ways: a session can ask the launcher things rather than parse console output
written for a person.

Seventeen tools, each making the same call its command makes:

| | |
|---|---|
| `loadout_specialist` | The full text of one specialist, as `instructions show` prints it |
| `loadout_effective_instructions` | What this session was given, and what triggered each part |
| `loadout_recall` | Search what the project already knows, as `memory find` does |
| `loadout_locate` | Where a type or member is declared, as `docs find` says |
| `loadout_code_map` | The map of the code as it stands now, one line per directory |
| `loadout_remember` | Record one durable fact about the project, with a description, screened for credentials |
| `loadout_tasks` | What the project is working on, and what the repository does not back up, as `task list` says it |
| `loadout_task_declare` | Record where a task stands, attributed and dated, as `task declare` does |
| `loadout_idea_add` | Drop an idea in without leaving the work in hand, as `idea add` does |
| `loadout_ideas` | Every idea and where it stands, or one in full, as `idea list` and `idea show` say it |
| `loadout_mode` | Change the posture for the rest of the session, and get what that changes |
| `loadout_progress` | For a node of a team run: say what you are doing, in your own words |
| `loadout_teams` | What the team runs on this machine are doing, and which have stopped to ask |
| `loadout_tools_search` | The machine's shared tools matching some words, as `tools search` finds them |
| `loadout_tools_show` | One shared tool in full: its purpose, inputs, outputs, versions and why it exists |
| `loadout_tools_submit` | Send the catalogue a candidate, idea, bug or lesson, screened for credentials, as `tools submit` does |
| `loadout_tools_used` | Say how a use of a shared tool went, as `tools used` does |

`loadout_recall` exists because only the memory index reaches the context — one
line per topic — and a session deciding from that alone either opens six files
or opens none. It searches inside them. It matches words rather than meanings,
which it says when it finds nothing, so an agent doesn't conclude a fact is
unrecorded when it is recorded in other words.

Its description is written around *when* to call it rather than around what it
does — before diagnosing a failure, before an unfamiliar error, before anything
about how the project builds, tests, releases or is configured, and before
recording a fact of its own. The accurate mechanical description it used to
carry was acted on once in twelve thousand turns, and a tool nothing calls is a
tool that isn't there. The memory index in the compiled context now says the
same thing in the same words; see [Memory](memory.md#telling-a-session-when-to-look).

`loadout_locate` answers the question an agent asks most often and most
expensively — where is this thing declared — with one line each, from a symbol
index cached against the commit it was built at. It matches names rather than
meanings, in whichever of the languages the scan reads each file turns out to
be in, and says so when it finds nothing, so an agent doesn't conclude a thing
is absent when it is merely called something else.

`loadout_mode` is there because a mode is a session-wide directive and work
changes shape: a session that started out investigating a bug ends up fixing it.
The agent asks for the new posture and adopts it, rather than drifting into it
without saying so. A mode it doesn't recognise is refused with the list of real
ones instead of being treated as the default. `skill.mode-switch` tells it when
the switch is worth making.

Nothing offered pushes to a remote, changes the machine or starts an agent. A
tool an agent can call unprompted is a decision taken with nobody watching, so
what is offered is the part of the launcher where that is safe — and a test
asserts no tool is ever named for the rest.

The declaration is written into the launch's runtime directory rather than the
workspace, for the reason in the table above: it names the executable running
right now, and an absolute path in a shared file is right on the machine that
wrote it and wrong on every other one that clones the workspace. It goes when
the session does.

```bash
loadout config set agent-tools false
```

turns it off. What it offers is reading plus one screened fact, so it is on by
default — but preferring that an agent could not reach the workspace at all is a
legitimate position, and the launcher does not overrule it.

You would not normally run `loadout mcp serve` yourself: it speaks JSON-RPC on
stdin and stdout, and the agent starts it.