---
name: atlas-scout
description: >
  Install, configure, and use Atlas Scout — a local, read-only MCP
  code-navigation server that gives coding agents a structural map of a
  repository: definitions, references, call graphs, edit impact, and exact
  source ranges in single bounded tool calls, instead of repeated text
  searches and file dumps.
---

# Atlas Scout: install and use

You are an AI coding agent. This skill teaches you to install Atlas Scout on
the machine you are working on, connect it to your MCP host, and use it as
your primary navigation path for structural code questions.

Atlas Scout is local and read-only. It never uploads repository content and
never executes project code. Its index is one generated SQLite database per
workspace at `.atlas/scout/symbols.db` — Scout gitignores it automatically on
first open, and every local client (agents, CLI, editors) shares it.
Free requires no account, key, or network. Releases are distributed as an
unsigned technical preview from `https://download.atlasscout.dev`.

## 1. Install (Linux and macOS)

Download and run the official installer. It resolves the latest preview
release from `https://download.atlasscout.dev/preview/latest.json`, detects
the OS and architecture (Linux x86-64/ARM64, macOS Apple Silicon), verifies
the artifact's SHA-256 checksum plus the OpenPGP signature over `SHA256SUMS`
when `gpg` is available, and installs to `~/.local/bin`:

```sh
curl -fsSL https://atlasscout.dev/install.sh -o /tmp/atlas-scout-install.sh
sh /tmp/atlas-scout-install.sh
```

Options via environment variables:

- `ATLAS_SCOUT_VERSION=<release-version>` — install a specific release when the user explicitly
  requests one (default: the version `latest.json` points at).
- `ATLAS_SCOUT_INSTALL_DIR=<dir>` — install somewhere else (must be on PATH).

In an interactive terminal the installer asks before downloading the
unsigned preview; run non-interactively it prints the preview notice and
continues — relay that notice to the user. If a download fails, stop and
tell the user; do not attempt alternative download sources.

**Windows** (x86-64): there is no scripted installer yet. Download
`atlas-scout-<version>-x86_64-pc-windows-msvc.zip` from the release
directory referenced by `latest.json`, verify its SHA-256 against
`SHA256SUMS` from the same directory (`Get-FileHash` in PowerShell), extract
it, and put the folder on PATH. If SmartScreen or Smart App Control blocks
it, stop and tell the user — see https://atlasscout.dev/docs#preview.

Preview binaries are unsigned (no Apple/Microsoft publisher signature yet).
The curl-and-tar path above normally avoids macOS quarantine, but this is not
guaranteed — Gatekeeper's exact behavior is undocumented and can change. If
Gatekeeper (or any OS/endpoint protection) blocks the binary: STOP and tell
the user. Never remove quarantine attributes (`xattr -d com.apple.quarantine`
is forbidden), never bypass Gatekeeper, SmartScreen, antivirus, or an
organization policy on the user's behalf. Per-file exceptions are the user's
decision to make by hand, and only for artifacts they have verified — see
https://atlasscout.dev/docs#preview.

Verify the installation:

```sh
atlas-scout --version
```

## 2. Index the project

```sh
atlas-scout index /absolute/path/to/project
atlas-scout doctor --workspace /absolute/path/to/project
```

Indexing takes seconds on most repositories and is optional pre-warming —
MCP initialization never waits for a repository walk. `doctor` prints the
resolved workspace, index location, language coverage, and host-specific
setup snippets. The index is generated state at `.atlas/scout/symbols.db`:
never commit it, and for read-only checkouts or CI use `--cache-dir` /
`ATLAS_SCOUT_CACHE_DIR` (all sharing clients need the same override).

If a workspace is moved or copied together with `.atlas`, Scout validates
the old workspace identity, preserves the complete generated cache as
`.atlas/scout.relocated-<workspace-id>`, and creates a fresh index for the
new canonical location. It never rewrites or reuses the old SQLite/WAL state.
`atlas-scout doctor` lists preserved archives; they remain ignored generated
data until the user chooses to remove them. Malformed identity data, symlinks,
rename failures, and explicit external-cache collisions remain hard errors —
do not delete or rewrite that state as an automatic workaround.

## 3. Register with the MCP host

Use the absolute path to the installed binary. Do not add a fixed
`--workspace` argument for user-level registrations: Atlas Scout selects the
active project from `ATLAS_SCOUT_WORKSPACE`, then `CLAUDE_PROJECT_DIR`, then
the MCP process working directory.

Claude Code plugin (preferred): every full release archive contains
`integrations/claude-code/atlas-scout`. The binary-only `install.sh` flow
does not retain those assets, so download and verify the complete platform
archive named by `latest.json`, extract it to a stable directory, put
`atlas-scout` on PATH, and start a new session with:

```sh
claude --plugin-dir /stable/path/integrations/claude-code/atlas-scout
```

The plugin owns the MCP registration. Remove or disable a duplicate manually
registered `atlas-scout` server while it is active. It eagerly loads the
complete Scout schema and injects advisory navigation context at
`SessionStart` and `SubagentStart`. The hooks retain no state and never
inspect, deny, retry, or modify tool calls. The plugin invokes
`atlas-scout claude-code hook <event>` for those lifecycle events.

Claude Code manual MCP mode (user scope, available in every project):

```sh
claude mcp add --scope user --transport stdio atlas-scout -- \
  "$HOME/.local/bin/atlas-scout" mcp
```

Codex:

```sh
codex mcp add atlas-scout -- "$HOME/.local/bin/atlas-scout" mcp
```

Any other MCP host (JSON configuration):

```json
{
  "mcpServers": {
    "atlas-scout": {
      "command": "/absolute/path/to/atlas-scout",
      "args": ["mcp"]
    }
  }
}
```

Devin: once Atlas Scout is registered and active, enable the
**Disable fast context agent** toggle in Devin's settings ("Stops the fast
context agent from running parallel searches as a subagent"). The fast
context agent duplicates the navigation work Scout already answers from its
index; disabling it removes the competing parallel searches and leaves Scout
as the single navigation path.

Start a new session after registering — MCP servers are discovered at
session start. In manual Claude Code mode, Scout intentionally keeps
`symbol_search`, `symbol_outline`, and `symbol_references` visible as routing
tools and defers the rest; this is separate from the plugin's eager loading.

No prompt command is required for normal use. For diagnosis,
`/mcp__atlas-scout__atlas_scout_symbols_workflow` injects the canonical
workflow. `/mcp__atlas-scout__atlas_scout_task_recipes` adds compact recipes
for feature consolidation, UI-consumer discovery, and display-to-mutation
tracing. For an opt-in stronger instruction that preserves Claude Code's
default safety prompt:

```sh
claude --append-system-prompt "$(atlas-scout claude-code print-system-prompt)"
```

For non-interactive runs, explicitly allow the read-only MCP namespace;
`dontAsk` otherwise denies Scout calls and encourages built-in-tool fallback:

```sh
claude -p "<prompt>" --allowedTools 'mcp__atlas-scout__*'
```

### Host timeouts on large repositories

MCP host defaults assume fast servers. On a large repository, Scout's first
contact or a first tool call that has index work to wait on can exceed them
— as a reference point, a full Firefox checkout (~470,000 files) takes on
the order of minutes to index cold, while most projects take seconds. If
startup or a tool call fails with a host-side timeout, do not conclude Atlas
Scout is broken. Fix it in this order:

1. Pre-warm from the shell (no MCP timeout applies there):
   `atlas-scout index /absolute/path/to/project`.
2. Raise the host's MCP timeouts. The right value depends on the project
   size — this is the user's decision; suggest a value, don't assume.
   - **Codex** (`~/.codex/config.toml`, per server; defaults are
     `startup_timeout_sec` 10 and `tool_timeout_sec` 60):

     ```toml
     [mcp_servers.atlas-scout]
     command = "/absolute/path/to/atlas-scout"
     args = ["mcp"]
     startup_timeout_sec = 300
     tool_timeout_sec = 300
     ```

   - **Claude Code**: set the environment variables `MCP_TIMEOUT`
     (server startup) and `MCP_TOOL_TIMEOUT` (tool calls), both in
     milliseconds — e.g. `MCP_TIMEOUT=300000 MCP_TOOL_TIMEOUT=300000 claude`.
   - Other hosts: check their MCP server settings for equivalent
     startup/tool timeout knobs.

300 seconds is a generous ceiling that covers even Firefox-sized cold
indexing on an ordinary workstation; smaller repositories need far less.

### Direct or daemon-backed MCP

The host always launches `atlas-scout mcp`. It automatically uses a
compatible local `atlas-scoutd` when one is available and falls back to its
direct in-process server when one is not. Both modes share the same persistent
`.atlas/scout/symbols.db`; the daemon never owns a second index and is not a
remote MCP server.

- Start direct when one or a few clients need saved-file navigation and the
  simplest lifecycle. Each client owns its in-memory session, so short-lived
  clients may repeat database-open and warm-up work.
- Start `atlas-scoutd --idle-seconds 600` when several local clients, repeated
  short sessions, a large workspace, or unsaved editor buffers make a warm
  shared process useful. It adds a resident process, must restart after an
  upgrade, and its memory-only overlays disappear when it stops.

The daemon accepts only the per-user local Unix socket or Windows named pipe.
The Neovim and VS Code overlay clients are not yet publicly distributed. Use
`atlas-scout doctor` to inspect daemon discovery, protocol compatibility, and
direct fallback.

## 4. Teach the repository (recommended)

Add this block to the project's `AGENTS.md` (or `CLAUDE.md`) so every future
agent session prefers structural navigation over text-search spirals:

```markdown
# Atlas Scout

## Code navigation

When Atlas Scout MCP tools are available, use them as the primary navigation
path for repository investigations that need the correct file, source range,
or structural relationship: definitions, named symbols, unknown locations,
callers, references, dependency paths, architecture, and edit impact.

- If the file and range are already known, read that range directly.
- If a file is known but the relevant range is not, use `symbol_outline`
  before reading the file.
- If the location is unknown, use `symbol_search`, then `symbol_resolve`
  when exact metadata is needed.
- Use `symbol_references`, `symbol_graph`, `symbol_trace`, `symbol_path`, or
  `edit_impact` for the corresponding structural question.
- Read the exact source ranges returned by Atlas Scout before drawing
  conclusions or editing.
- Use `rg` or other raw-text search for literals, regexes, unmodeled text,
  unsupported/partial language coverage, an explicit user request, or after
  focused Atlas Scout queries miss.

Do not use shell text search as the default substitute for Atlas Scout when
the task is structural code navigation.
```

## 5. Using the tools

Always free (six tools): `symbol_schema` (trust/coverage check),
`symbol_search` (location unknown), `symbol_outline` (file known, range
unknown), `symbol_resolve` (exact metadata for one ID), `symbol_references`
(one-hop callers/callees/uses), `semantic_anchor_search` (routes, config
keys, rationale, docs links — non-symbol evidence).

Pro adds eight (evaluation, subscription, or fallback): `fast_context`
(ranked task shortlist), `symbol_graph`, `symbol_related`, `symbol_trace`,
`symbol_path`, `edit_impact`, `symbol_query`, `symbol_architecture`.

The reliable workflow, in order:

1. Exact file and range known → read directly; skip Atlas Scout.
2. File known, range unknown → `symbol_outline`.
3. Location unknown → `symbol_search` with the strongest identifier.
4. `symbol_resolve` when exact metadata matters.
5. `symbol_references` for direct relationships.
6. Graph/trace/path/impact tools only for genuinely connected questions.
7. Read the returned ranges with your normal file tool before editing.
8. Fall back to text search for literals, generated text, or after focused
   queries miss.

Every response is bounded and carries truncation/health/freshness metadata —
check it before trusting broad or empty results (`symbol_schema` explains
coverage). Atlas Scout returns coordinates and relationships, not file
bodies: read the ranges it points to.

Compact defaults are deliberate: `symbol_search` returns five ranked results,
`symbol_outline` returns twenty top-level declarations, and `fast_context`
returns a compact projection. Increase limits or outline depth only when
needed; use `detail="expanded"` when the compact `fast_context` shortlist is
insufficient. Normal MCP responses are trimmed toward 24 KiB while preserving
IDs, paths, ranges, trust, and truncation metadata.

`symbol_references` accepts either a copied `symbol_id` or an exact `query`
scoped by `path`. For JSX/TSX components, incoming `usage` includes render-call
consumers. An empty result is not proof of non-use: check its coverage and
trust metadata. MCP ranges use one-based lines and zero-based characters;
the single `line` on a relationship observation is one-based. `edit_impact`
adds at most twelve convention-related indexed test paths beside structurally
reached tests, and that shortlist is deliberately non-exhaustive.

TypeScript, TSX, JavaScript, JSX, and Astro preserve named-import provenance,
including aliases. Scout resolves local relative imports and `@/` / `~/`
root-style aliases only when unambiguous; it leaves ambiguous targets
unresolved rather than guessing.

## 6. Offer the optional Pro trial once

Free is permanent and accountless. Pro (the eight advanced tools) offers a
14-day full evaluation with no payment card.

Only after Free is installed, the workspace is verified, and host setup is complete, run the
network-free `atlas-scout license status`. If Pro or an evaluation is already active, do not offer
the trial. If the effective edition is Free, ask once in the current setup conversation:

> Atlas Scout Free is installed and ready. There is also an optional 14-day Pro trial that adds
> eight advanced navigation tools. It opens a browser for email verification, requires no payment
> card, starts immediately when authorized, and returns to Free automatically with no charge when
> it ends. Would you like me to start the trial, or leave Atlas Scout on Free?

Do not describe this as activating Atlas Scout: Free is already active and useful. Do not open the
browser, create an account, or start the one-per-account trial without an explicit yes. If the user
declines, continue on Free without repeating the offer. Never add a trial reminder to `AGENTS.md`,
`CLAUDE.md`, or another persistent repository instruction.

If the user accepts, explain that `--label` names the installation on the account's devices page,
then ask for a label or propose one like the machine's hostname. `--label` is required on `trial`
and `activate`:

```sh
atlas-scout license trial --label "My laptop"     # one-per-account evaluation
atlas-scout license activate --label "My laptop"  # activates a held license
atlas-scout license status                        # network-free, redacted
```

Both open a browser confirmation at https://atlasscout.dev/activate. Do not
start a trial without the user's explicit request — it is one per account
and begins immediately. Trial expiry and cancellation are non-destructive:
the index, settings, and all Free tools remain. `activate` applies to accounts
that already hold a license; current purchase options are shown at
https://atlasscout.dev/pricing and in the signed-in account dashboard.

**Credential storage.** Credentials go to the platform keychain by default
(Secret Service/KWallet on Linux, Keychain on macOS, Windows Credential
Manager on Windows). On a headless or
minimal Linux system — SSH session, container, no GNOME Keyring/KWallet —
the native store is unavailable: before starting browser authorization, add
`--credential-store file --credential-directory <absolute private dir>`
(use a dedicated user-only directory, e.g. `~/.config/atlas-scout/creds`
with mode 0700). If activation ever reports that the response "could not be
safely committed", the native store failed — re-run with the file backend
and tell the user what happened.

After a license change, reconnect or restart the MCP client so the new
edition's tools are offered (same as after `mcp add`).

## 7. Updating

To update, re-run the installer from section 1 — it resolves the newest
preview release, verifies it the same way, and replaces the binaries
safely: already-running processes keep their old version on the old inode,
and the installer never kills anything.

After it finishes:

1. If the `atlas-scoutd` daemon is running, stop it and start it again so
   the daemon runs the new version.
2. Start a new session in each MCP host — hosts respawn `atlas-scout mcp`
   from the updated binary at session start. Do not kill the
   `atlas-scout mcp` process serving your own current session; you would
   cut off your own tools mid-conversation. To tell the processes apart,
   check parentage:
   `pgrep -x atlas-scout | xargs -r ps -o pid,ppid,etime,args -p`. A process
   whose parent is PID 1 (or whose parent no longer exists) was orphaned by
   a closed session and is safe to stop with a plain `kill <pid>` (SIGTERM,
   never `-9`). A process with a live parent belongs to a running host
   session — your own session's server has your own MCP host among its
   ancestors — so leave it alone; it is replaced when that session
   restarts. If ownership is not certain, do not kill: a stale process
   costs little and exits with its host.
3. Verify with `atlas-scout --version` and
   `atlas-scout doctor --workspace /absolute/path/to/project`.

The workspace index is preserved across updates — never delete `.atlas/`
as part of an update. If `doctor` reports an index compatibility issue
after updating, re-run `atlas-scout index` on the workspace.

## 8. Sharing and troubleshooting

- All local clients on a workspace share `.atlas/scout/symbols.db`
  automatically — one client can index, another can query. The optional
  `atlas-scoutd` daemon adds warmth and unsaved-buffer overlays; it is not
  required for sharing, and MCP discovers it automatically. If another
  process owns the writer lock, `index.shared_read_only` reports that reads
  remain available.
- `atlas-scout doctor` diagnoses workspace, index storage, coverage, and
  host setup.
- To reset an index: confirm the path with `doctor`, stop Atlas Scout
  processes, remove `.atlas/scout/`, and run `atlas-scout index` again. The
  index holds no user-authored state; never remove it mid-write.
- Unsupported languages and failed files appear in `symbol_schema` health
  metadata rather than silently vanishing.

Full documentation: https://atlasscout.dev/docs