# Atlas Scout documentation > Complete machine-readable Markdown edition of the public Atlas Scout documentation. > Canonical HTML: . Agent installation skill: > . Everything the product does, how it behaves when things go wrong, and exactly what it will never do with your code. **Applies to Atlas Scout 1.0.0-preview.29**, published August 17, 2026 - the version named by the signed [preview release pointer](https://download.atlasscout.dev/preview/latest.json). The [Preview 29 release report](https://atlasscout.dev/releases/preview-29) explains the current release in depth; the [changelog entry](https://atlasscout.dev/changelog#preview-29) provides the shorter product-level summary. ## On this page 1. [What Atlas Scout is](#what) 2. [The reference-first model](#model) 3. [Direct or daemon-backed MCP](#daemon) 4. [MCP tool reference](#tools) 5. [A practical workflow](#workflow) 6. [Free and Pro](#editions) 7. [Licensing and offline behavior](#licensing) 8. [Language support](#languages) 9. [Editors, agents, and hosts](#hosts) 10. [Getting started](#start) 11. [Operations and recovery](#operations) 12. [Unsigned technical preview](#preview) 13. [Privacy and security](#privacy) 14. [Current limitations](#limits) 15. [FAQ](#faq) ## What Atlas Scout is Atlas Scout is a local, read-only code-navigation server for AI coding agents. It builds a compact structural map of your codebase - every symbol, relationship, and exact source range - and serves it over the Model Context Protocol (MCP), so your agent finds the right code _before_ it reads any code. The principle: an agent should never have to read a repository to answer a focused question about it. Scout answers with identifiers, relationships, provenance, and precise coordinates; the agent then reads only the ranges that matter, with its normal file tools. Those are the questions agents ask all day: _where is this implemented, what calls this function, what does this type depend on, which tests does this change touch, which few files should I read first?_ That principle also draws Scout's boundary: it navigates code that already exists. A brand-new, empty project has no structure to map and no evidence to return. Scout starts paying its way with the first files you write and pays best on codebases that have been worked on long enough to get lost in. Atlas Scout complements text search, compilers, language servers, and test runners - it does not pretend to replace them. It is proprietary software from Zaguán Labs. **Where it comes from:** Atlas Scout began life inside Zaguán Blade as its Symbols Index. The idea proved strong enough to deserve its own product, so Scout was carved out and rebuilt as standalone navigation infrastructure. The two remain separate: Scout is developed and licensed on its own, and Blade does not include it. ## The reference-first model The model rests on four commitments: a map instead of a copy, proof instead of plausibility, one shared index instead of one per tool, and bounded answers instead of dumps. ### A map, not a second copy of your repository Scout reads files locally and builds one generated SQLite index per workspace at `.atlas/scout/symbols.db`. The index is disposable and invisible to your tooling: ignored by git, excluded from discovery and watchers, and automatically kept out of your history (Scout writes a defensive `.atlas/.gitignore` and idempotently adds `.atlas/` to the root `.gitignore` on first open). Which files participate is under your control, and visible. Scout honors `.gitignore` files even outside a Git repository, matching ripgrep's `--no-require-git` behavior, and a workspace `.atlasignore` file adds Scout-only exclusions that no other ignore-aware tool sees. Exclusions are never silent: discovery records excluded paths at their shallowest roots, capped at 256 entries with an explicit truncation flag, and `symbol_schema` reports them as an optional `ignored_paths` block filtered to a requested directory scope. Editing a known ignore file forces the ignore-aware discovery pass on the next reconcile. Scout's own cache and `.git` remain hidden. What it holds is structure, not source: symbol identifiers, names, kinds, signatures and ranges; imports, calls, inheritance, implementation, containment and type-use relationships; semantic anchors like routes, configuration keys, and rationale comments; plus fingerprints and health metadata. It stores no duplicate source tree and no source-file bodies. Discovery responses are coordinate-first, and the authoritative source is always read from your files. ### Connected, and honest about it Relationship resolution is precision-first: an edge appears with proof, or it does not appear. Scout records _how_ each target was resolved and keeps genuinely ambiguous observations marked as unresolved instead of inventing certainty. That honesty is what makes call neighborhoods, shortest paths, and edit-impact estimates trustworthy enough for an agent to act on. ### One map, shared by every client The map lives in the workspace, so Codex, Claude Code, the CLI, and editor integrations all reuse the same database - even as independent processes, with concurrent initialization and writes safely coordinated. One client can build or refresh the index while another queries it. If another process owns the writer lock, health reports `index.shared_read_only` while keeping reads available. The optional `atlas-scoutd` daemon adds warmth across workspaces and memory-only unsaved-buffer overlays - an optimization, not a requirement for sharing. The Neovim and VS Code overlay clients currently live in the source repository and are not included in the public Preview 29 release archives. ### Bounded by design Scout exists to shrink the working set, not to pour a repository-sized search result into a context window. Every result is bounded. Healthy, fresh, fully supported answers stay quiet; empty, partial, stale, degraded, repaired, or truncated results carry the trust evidence an agent needs to decide whether to continue, narrow the query, or fall back. ## Direct or daemon-backed MCP Your MCP host always launches `atlas-scout mcp`. That stdio adapter uses a compatible local `atlas-scoutd` automatically when one is available and runs a direct in-process server when one is not. Starting the daemon never changes the MCP registration command, and both arrangements use the same persistent workspace index. | Arrangement | Best fit | What you gain | Costs and boundaries | | ------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Direct | One or a few clients and saved-file navigation | The simplest lifecycle, no background process, and automatic reliable fallback | Each client keeps its own in-memory session and may repeat database-open and warm-up work; unsaved editor overlays are unavailable | | Daemon-backed | Multiple clients, repeated short sessions, large workspaces, or unsaved buffers | Warm shared workspace sessions, one reconciliation owner, and memory-only editor overlays | A resident local process that must restart after upgrades; overlays disappear when it stops, and the editor clients are not yet publicly distributed | Start direct when simplicity and saved-file navigation are enough. Add the daemon with `atlas-scoutd --idle-seconds 600` when keeping workspaces warm or sharing unsaved editor state is valuable. `atlas-scout doctor` reports the resolved endpoint, protocol versions, and whether the stdio adapter fell back to direct mode. The daemon accepts only a per-user local Unix socket or Windows named pipe. It is not a remote or Streamable HTTP MCP server, and it never owns a second index. Direct and daemon-backed sessions share the same MCP transport boundary. If a client probes `server/discover` before initialization, both arrangements reject that unsupported method with `-32601` and continue on the same connection. This is a compatibility fallback - not native discovery, stateless MCP, or a new transport. If Antigravity 1.1.8 sends `notifications/roots/list_changed` before initialization, Scout ignores that premature notification until the required initialize request arrives. ## MCP tool reference Six permanent Free tools; a Pro evaluation, subscription, grace period, or eligible fallback adds eight more - fourteen in total. ### Free tools | Tool | What it does | Use it when | | ------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `symbol_schema` | Reports index health, coverage, languages, relationship resolution, failures, and ignored paths | You need to judge whether broad or empty results are trustworthy | | `symbol_search` | Finds compact symbol references with name, path, qualified-name, and kind filters | The symbol or file location is unknown | | `symbol_outline` | Inventories definitions and hierarchy in one known file | The file is known but the relevant range is not | | `symbol_resolve` | Resolves one stable ID or exact selector into precise metadata | Search or outline has identified the target | | `symbol_references` | Shows bounded one-hop relationships from an ID or an exact query scoped by path | You need direct callers, callees, uses, or imports | | `semantic_anchor_search` | Searches routes, configuration, rationale, links, and other non-symbol evidence | Symbol search is the wrong evidence class | Free tools are not rate-limited or made less accurate. They run on the same index, extraction, freshness checks, and ranking as Pro. ### Pro tools | Tool | What it does | Use it when | | --------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------- | | `fast_context` | Produces a ranked file shortlist, likely tests, bounded read ranges, and next searches | You need a fast, implementation-oriented starting point | | `symbol_graph` | Returns a bounded structural neighborhood around one symbol, with provenance | One-hop references are not enough | | `symbol_related` | Ranks explainable structural and same-file neighbors | You need nearby concepts, honestly derived | | `symbol_trace` | Traces bounded incoming or outgoing resolved call edges | You need a static call chain | | `symbol_path` | Finds one shortest resolved structural path between two symbols | You need to explain how two entities connect | | `edit_impact` | Ranks bounded incoming impact and a non-exhaustive shortlist of likely affected tests | You are planning or reviewing a change | | `symbol_query` | Applies structured symbol filters declaratively | You need a precise query without raw SQL | | `symbol_architecture` | Aggregates file-level modules and resolved cross-file edges with cancellable bounded work | You need a bounded subsystem view | ### Compact defaults and expansion Scout starts small on purpose. Omit `limit` from `symbol_search` for its five-result default, and leave connected evidence off for location-only searches. Request the small caller/callee preview when it is likely to replace another structural call. `symbol_outline` defaults to twenty top-level declarations; request nesting, depth, locals, imports, kinds, or a larger limit only when the compact inventory is insufficient. It has no offset or cursor pagination. `fast_context` likewise defaults to a compact projection, accepts at most four optional orientation queries, and uses `detail="expanded"` for its deeper evidence view. The canonical structured evidence is trimmed toward a 24 KiB target, while the complete response has a 48 KiB hard ceiling. An empty `_meta` object means the result is healthy, fresh, non-empty, fully supported, complete, and unrepaired. Trust-sensitive exceptions retain the relevant health, language, truncation, or repair details. Clients negotiating MCP 2025-06-18 or later receive the structured result without a duplicate JSON text mirror; older clients retain the compatibility mirror without being charged twice against the evidence budget. ### Selectors, coordinates, and reference trust `symbol_references` accepts either a copied `symbol_id` or an exact `query` scoped by `path`. For JSX and TSX components, incoming `usage` relationships include render-call consumers. Empty reference results still carry coverage and trust metadata; they are not proof that a symbol is unused. Relationship-kind filters belong to `symbol_references`, not `symbol_search`. MCP source ranges use one-based lines and zero-based characters. A relationship observation’s single `line` value is one-based, and its additive `byte_offset` is zero-based. Distinct calls on the same line retain distinct offsets. `symbol_references` returns at most ten complete observations per page and supplies `next_cursor` when more remain. `edit_impact` combines structurally reached tests with at most twelve convention-related indexed test paths; that second shortlist is useful evidence, not an exhaustive test plan. ## A practical workflow 1. If the exact file and range are known, read them directly. 2. If the file is known but the range is not, call `symbol_outline`. 3. If the location is unknown, call `symbol_search` with the strongest identifier or domain cue. 4. Search and outline already return stable IDs, paths, ranges, and signatures. Resolve the chosen ID with `symbol_resolve` only when omitted exact metadata matters. 5. Use `symbol_references` for direct relationships. 6. Reach for graph, trace, path, impact, or architecture tools only when the question needs deeper connected evidence. 7. Read the exact ranges with your host’s file tool before editing. 8. Fall back to text or regex search for literals, generated text, or unsupported constructs. For broad tasks, `fast_context` supplies the initial shortlist - then confirm the important relationships with the targeted tools. For ordinary symbol location, leave `include_connected_evidence` omitted; enable it when the bounded neighborhood is likely to avoid a separate references or graph call. ## Free and Pro **Free is permanent, local, and accountless** - the complete index and relationship pipeline, every supported language at its documented level, the six Free tools, CLI indexing and diagnostics, the shared daemon, editor overlays, and unlimited ordinary workspaces. No artificial quotas of any kind. Free is a genuinely useful product, not a degraded demo. The overlay protocol is available in Free; the Neovim and VS Code clients themselves are not yet publicly distributed as packaged extensions. **Pro adds connected understanding**: all eight advanced tools, multi-hop graph/trace/path analysis, edit impact, ranked fast context, and editor/unsaved-buffer signals in ranking. Pro is licensed to one named person on up to three installations - one installation covers the CLI, MCP clients, daemon, Neovim, and VS Code on that machine. Pro is available for \$39/month or \$390/year in USD; any applicable taxes and the final total are shown at checkout. See [pricing and purchase options](https://atlasscout.dev/pricing). Signed-in users can manage or cancel a subscription from their account, and the CLI’s `license activate` connects an installation to a license the account already holds. ### The 14-day evaluation Every verified user can start one 14-day Pro evaluation: no card, the complete feature set, no reduced trial variant. It begins only when you explicitly run the trial command - never at download, install, or first index. All installations on the account share one server-authoritative end time, and reinstalling or clearing local state does not restart it. When it ends, everything falls back to Free non-destructively. ### Paid time vests into a permanent license Every completed paid year becomes yours permanently: one paid annual term (once its refund window closes) grants perpetual Pro in every release issued on or before that term’s end - from your first year. Monthly subscribers earn the same guarantee after twelve consecutive paid periods, and every later renewal advances the cutoff. An active subscription keeps you on the newest releases; the earned license never expires, even if you cancel. ## Licensing and offline behavior Pro entitlements are signed, time-bounded leases verified locally - signature, product, installation, generation, release eligibility, and time bounds - before anything is enabled. The billing provider never controls feature checks inside the binary. What that means day to day: - Free never contacts a license server. - A cached Pro lease is verified locally at start; MCP startup never waits for the network. - Pro works offline for the lease window (up to 30 days); outages never remove valid cached access. - A missing renewal result gets a 24-hour settlement window; a confirmed payment failure gets a separate 14-day grace. - Cancellation keeps Pro through the paid period. - Upgrades, downgrades, expiry, and deactivation never delete or rebuild your index, and a running tool call is never interrupted. ```text atlas-scout license trial --label "My laptop" atlas-scout license activate --label "My laptop" atlas-scout license status [--json] atlas-scout license refresh atlas-scout license deactivate atlas-scout license devices ``` `--label` is required on `trial` and `activate` - it is the name the installation shows on your devices page. `license status` is network-free and fully redacted: it reports edition, state, signed boundaries, and a support code - never a credential, token, identifier, or email. Credentials are stored in the platform keychain by default (Secret Service or KWallet on Linux, Keychain on macOS, and Windows Credential Manager on Windows). On headless or minimal Linux systems without a keyring service - SSH sessions, containers, bare window managers - pass `--credential-store file --credential-directory /absolute/private/dir` to use the file backend instead; the directory should be dedicated and user-only. ## Language support **Full structural extraction** - definitions, imports, declared relationships, and semantic anchors: TypeScript, TSX, JavaScript, JSX, HTML, Python, PHP, Rust, Go. **Partial extraction** is explicit and honest: a partial language contributes exactly the capabilities its extractor lists, and unsupported or failed files stay visible in health metadata rather than silently vanishing from coverage. TypeScript, TSX, JavaScript, JSX, and Astro preserve named-import provenance, including aliases. Local relative imports plus `@/` and `~/` root-style aliases resolve when the target is unambiguous; Scout fails closed when more than one target remains plausible. HTML extraction includes document IDs, custom elements, script and stylesheet dependencies, and HTMX request targets. PHP contributes namespaces, imports, types, members, signatures, calls, type and inheritance relationships, trait use, Laravel-style routes, and surrounding template markup. Astro combines TSX frontmatter with HTML markup while preserving source offsets. Vue and Svelte templates pass through the HTML extractor, and JSX or TSX markup recognizes custom elements and HTMX request targets too. Go calls resolve semantically through exact package/import and simple static-receiver evidence. Scout understands same-package calls, aliases, local module replacements, test-package boundaries, nested modules, lexical import shadowing, and conservative build variants without downloading dependencies. Package clauses, imports, and build constraints are recorded during the extraction pass and reused during reconciliation rather than re-parsing the complete Go corpus. `go.mod` and `go.work` remain disk-authoritative configuration. A generated or oversized Go file that skips structural extraction still contributes its package identity from a bounded file head, while its symbols remain unindexed. Concrete Go method identities include the normalized receiver type. Same-named methods on different receiver types remain separate definitions with separate callers, and a typed call cannot hydrate as another receiver’s method merely because their names match. This is not compiler-complete Go analysis. Promoted or embedded methods, complete pointer/value method sets, dot imports, method expressions and values, factory inference, arbitrary receiver expressions, full build-context evaluation, and cgo remain unresolved or outside the claim. C++ coverage extracts literal includes and resolves a precision-first call subset for bare, qualified, dot-member, arrow-member, and implicit-owner observations. Only exact lexical ownership, simple proven receiver types, same-file definitions, or directly resolved include visibility can create an edge. C++ remains partial. Scout does not claim transitive include awareness, template-aware overload dispatch, complete receiver inference, function pointers, callable objects, virtual dispatch, build-variant selection, or external-library modeling. Rust qualified calls enter the `proven` evidence tier when indexed evidence establishes a `Self` owner, crate- or module-relative path, explicit import, alias or re-export, renamed workspace dependency, or exact UFCS target. Scout preserves the qualified source spelling and exact observation site. This is structural resolution, not a Rust compiler. Glob imports, missing indexed dependencies, generated or macro-expanded structure, non-literal modules, unproven trait selection, arbitrary expression types, and failed or ambiguous qualifiers remain unresolved. A failed qualified path never degrades into a global match on its terminal method name. Every resolved relationship names its evidence tier: `proven`, `receiver_typed`, `unique_name`, or `unique_method_name`. Names are compared only inside compatible language families, so a Rust call cannot bind to a same-named TypeScript or Python declaration. An unconfirmed `unique_method_name` edge is reported and counted but never extends a graph, trace, path, or multi-hop impact result. | Language / format | Current coverage | | ----------------------------------- | -------------------------------------------------------------------- | | Astro | TSX frontmatter plus markup projected through the HTML extractor | | C / C++ | Definitions, literal includes, and a precision-first C++ call subset | | Markdown | Headings and semantic anchors | | CSS, SCSS, Sass, Less | Bounded stylesheet definitions and anchors | | Vue, Svelte | Template markup projected through the HTML extractor, plus anchors | | JSON, YAML, TOML | Bounded configuration definitions and anchors | | Java, C#, Kotlin, Ruby | Bounded definition scanners and anchors | | Shell, Dockerfile, SQL, Make, CMake | Bounded definitions, resources, and anchors | ## Editors, agents, and hosts Atlas Scout speaks local MCP over stdio and has been exercised with Codex, Claude Code, Devin desktop environments, Antigravity, Cline, and OpenCode. Any compatible host that can start `atlas-scout mcp` works; cloud-only agents need Atlas Scout installed inside the environment where they run. ### Official MCP Registry Published · Four native MCPB packages Atlas Scout Preview 29 is active and latest in the official MCP Registry as four real, target-specific MCPB packages. The Registry version and native preview channel now name the same signed release. An MCP Registry client that supports MCPB packages can select the package matching its operating system and CPU architecture. Each bundle contains the exact Preview 29 executable and the proprietary product license, EULA, privacy, refund, and third-party notices. Each package’s immutable SHA-256 is recorded in the Registry metadata and the public `server.json`. | Platform | MCPB target | | --------------------- | --------------------------- | | macOS · Apple silicon | `aarch64-apple-darwin` | | Linux · ARM64 | `aarch64-unknown-linux-gnu` | | Linux · x86-64 | `x86_64-unknown-linux-gnu` | | Windows · x86-64 | `x86_64-pc-windows-msvc` | The inspectable packaging repository locks its recipe to the signed Preview 29 release manifest and publishes the corresponding MCPB release. Linux x86-64 also passed a real MCP `initialize` and `tools/list` handshake. Publication completed through the Registry’s recommended GitHub Actions OIDC flow in this successful public workflow run, proving publisher identity without requiring public organization membership. The MCPB wrappers are hash-verified but not X.509-signed. Preview macOS and Windows executables remain unsigned; do not weaken operating-system or organization security controls to run them. The MCP Registry itself is still in preview, and its published versions are currently immutable with no ordinary unpublish operation. See the official Registry FAQ for that lifecycle boundary. ### OpenAI Plugins Directory: Codex Published · Preview 29 skills-only package Atlas Scout is publicly available in [OpenAI’s universal Plugins Directory](https://chatgpt.com/plugins/plugins_6a6e427dd300819196d41d5d1f24da50), shared by ChatGPT and Codex. Preview 29 was approved and explicitly published on August 17, 2026. Its code-navigation and guarded-setup skills passed OpenAI’s scans. The directory entry is intentionally skills-only. It teaches Codex when and how to use Scout, preserves coverage and fallback boundaries, and requires approval before setup. It does not contain the proprietary runtime, an `.mcp.json` file, or a hosted MCP server. Atlas Scout remains a local `stdio` service so repository indexing stays on the workstation instead of moving to a public HTTPS endpoint. To activate the structural tools, first install the verified Atlas Scout runtime, then install the MCP-enabled plugin from the public Zaguán Labs Codex marketplace: ```text atlas-scout --version atlas-scout doctor --workspace /absolute/path/to/project codex plugin marketplace add ZaguanLabs/atlas-scout-codex-plugin codex plugin add atlas-scout@atlas-scout ``` Start a new Codex thread afterward. If Atlas Scout is already registered manually as an MCP server, either keep that registration and leave the MCP-enabled plugin uninstalled, or remove the manual registration before enabling the plugin. One Codex environment should start only one Atlas Scout server. The inspectable Apache-2.0 wrapper lives in the [public Codex plugin repository](https://github.com/ZaguanLabs/atlas-scout-codex-plugin), alongside its [signed Preview 29 release](https://github.com/ZaguanLabs/atlas-scout-codex-plugin/releases/tag/v1.0.0-preview.29). A clean ephemeral Codex session loaded that public package, called Scout once, and resolved an indexed Rust probe to its exact range. The wrapper’s Apache-2.0 license does not replace the separate Atlas Scout runtime license and EULA. ### Smithery and MCP.so Published · Universal Preview 29 MCPB [Atlas Scout on Smithery](https://smithery.ai/servers/zaguanlabs/atlas-scout) serves the exact Preview 29 universal bundle. Deployment `b9661f31-f732-495f-b175-d467d8e21b36` completed successfully, and all fourteen public tool schemas were verified after publication. The Smithery CLI reproduced its known `No values to set` failure for this MCPB. The documented authenticated API fallback published the already-built bundle unchanged; it did not rebuild or alter the release candidate. The existing [MCP.so submission](https://github.com/chatmcp/mcpso/issues/3397) has also been updated to Preview 29 and remains under free review. ### Claude Code: plugin mode The preferred Claude Code integration is the plugin included at `integrations/claude-code/atlas-scout` in every full release archive. It uses per-tool loading metadata so Claude sees the five most useful entry points immediately: `symbol_search`, `symbol_outline`, `symbol_references`, `fast_context`, and `edit_impact`. Entitlement filtering happens first, so Free exposes its three included entry points while Pro can expose all five. The remaining tools stay available on demand without occupying the initial tool catalog. The plugin version follows the Atlas Scout product version, and the integration keeps itself aligned with the runtime. `atlas-scout claude-code sync` aligns three managed surfaces independently and reports each: the managed Atlas Scout section of the user-global `~/.claude/CLAUDE.md` (created, appended, or rewritten in place, never touching content outside its begin/end markers), the managed marketplace registration, and the installed plugin - registered, installed, enabled, or updated as the inspected state requires. `atlas-scout upgrade` runs the upgraded binary's sync after promotion, so each release carries its own hooks, skill, and MCP declaration forward. `atlas-scout doctor` reports the preferred plugin's readiness and marketplace source, flags a stale installed version, identifies a competing manual MCP registration, and points at the sync command instead of describing manual steps. Advisory context is injected at `SessionStart` and `SubagentStart`, giving the main conversation and built-in or custom subagents the same navigation guidance. `SessionStart` also spawns a detached index refresh for the session's working directory, so the first structural query answers from a current index without the session waiting; directories without a `.git` or `.atlas` ancestor are left alone. A `UserPromptSubmit` hook repeats a short reminder of the structural tools on the first prompt of a session and every fifth prompt after, and never adds a second notice to a turn that already received one. A narrow `PreToolUse` hook can answer a Claude `Grep` call - or a `Bash` command running an `rg`/`grep`-family search - with Scout context when the pattern is a bare code identifier containing an underscore or capital letter. It runs at most four times per session, returns context only, and never makes a permission decision. Every notice first verifies that an index database exists at or above the hook's working directory and stays silent when it does not. Prose searches, regular expressions, and all other tool calls are ignored. The hooks never inspect conversation history, deny, retry, or modify a tool call. Claude’s normal tools remain available for direct known-range reads, literals, regexes, unsupported coverage, builds, tests, Git, runtime work, and focused fallback. Community marketplace status · Under review The Atlas Scout plugin wrapper is public and inspectable under Apache-2.0 at ZaguanLabs/atlas-scout-claude-plugin, including its signed Preview 29 release. The exact public package started its plugin MCP server, exposed all fourteen tools, and resolved an indexed Rust probe with one Scout call. Anthropic is currently reviewing its community-directory submission, so Atlas Scout does not yet claim an official marketplace listing. The wrapper configures the local MCP runtime; it does not install that proprietary runtime, run repository code, or send source code to Zaguán Labs. The installer exposes the verified plugin through a local marketplace and offers to install it persistently at Claude Code user scope. This is a real Claude Code plugin installation, not a one-session `--plugin-dir` development sideload. The plugin invokes `atlas-scout` by name, so the installer’s executable-link directory must be on the Claude process’s `PATH`. The installer checks this and prints the exact marketplace and executable paths, including when you use a custom data or link directory. When the enabled plugin coexists with a manually registered `atlas-scout` server, the installer detects the duplicate, reports its exact scope, and does not declare the Claude Code integration healthy until you remove the manual registration (`claude mcp remove atlas-scout`) and rerun it. ```text claude plugin marketplace add \ "$HOME/.local/share/atlas-scout/claude-code-marketplace" \ --scope user claude plugin install atlas-scout@atlas-scout-local --scope user ``` You only need those commands when Claude Code was unavailable during installation or you skipped the installer’s integration offer. They modify Claude Code’s user configuration. Start a new session afterward; in another active session, `/reload-plugins --force` loads an installed change without restarting. #### Public GitHub source while community review is pending If you prefer Claude Code to track the public wrapper rather than Scout’s managed local marketplace, install that source directly: ```text claude plugin marketplace add ZaguanLabs/atlas-scout-claude-plugin --scope user claude plugin install atlas-scout@atlas-scout --scope user ``` Choose one plugin source, not both, and keep the Atlas Scout runtime installed on Claude Code’s `PATH`. Do not use or recommend an official-directory install until Anthropic publishes the listing. ### Claude Code: manual MCP mode Manual user-level registration remains supported. The same entitlement-aware loading metadata applies: Free keeps `symbol_search`, `symbol_outline`, and `symbol_references` visible as routing tools; Pro also keeps `fast_context` and `edit_impact` visible. The remaining tools are deferred until Claude needs them. Manual mode does not install the plugin’s lifecycle or narrowly scoped `Grep` guidance hooks. 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 consolidating a duplicated feature, finding UI consumers, and tracing display code to a server mutation. If the server has another configured name, use that normalized name in the command. ```text claude --append-system-prompt "$(atlas-scout claude-code print-system-prompt)" claude -p "" --allowedTools 'mcp__atlas-scout__*' ``` The first command opts into stronger Scout guidance without replacing Claude Code’s default safety prompt. Non-interactive Claude must explicitly allow `mcp__atlas-scout__*`; otherwise `dontAsk` denies the calls and encourages built-in-tool fallback. ### Other local MCP hosts Codex uses `codex mcp add atlas-scout -- /absolute/path/to/atlas-scout mcp`. Devin, Antigravity, and Cline accept the common `mcpServers` shape with the binary as `command` and `["mcp"]` as `args`. OpenCode uses a local MCP entry whose command array is `["/absolute/path/to/atlas-scout", "mcp"]`. Restart or refresh the host after replacing the binary or changing configuration. Approve or auto-approve only the trusted Atlas Scout server if uninterrupted navigation is desired. Do not enable a global all-tools or YOLO permission mode merely to remove Scout prompts. **Connection compatibility:** clients such as Antigravity may probe `server/discover` before normal initialization. Current Atlas Scout releases return the standard `-32601 Method not found` response without closing the connection. Antigravity 1.1.8 may also send `notifications/roots/list_changed` too early; Scout ignores that notification until the standard initialization request arrives. Initialization can continue in both cases, with no special host configuration. In Devin, once Atlas Scout is installed and active, enable the **Disable fast context agent** toggle in settings (“Stops the fast context agent from running parallel searches as a subagent”). Devin’s fast context agent duplicates the navigation work Scout already does with indexed, structural answers - turning it off removes the competing parallel searches and lets Scout be the single navigation path. ### Editor overlays The source repository contains Neovim and VS Code clients that feed memory-only unsaved-buffer overlays to `atlas-scoutd`. They are thin local clients, not competing indexes, but the current preview does not package them or publish them through editor marketplaces. Treat them as source-tree integrations rather than immediately installable public extensions. ## Getting started Atlas Scout ships as an [unsigned technical preview](#preview) with full cryptographic verification - checksums, OpenPGP signatures, and Sigstore build provenance; organization-signed builds follow later. Releases are served from `download.atlasscout.dev`, and the pointer [preview/latest.json](https://download.atlasscout.dev/preview/latest.json) always names the current release and links its manifest, signatures, public key, and checksums. ### Linux and macOS ```text curl -fsSL https://atlasscout.dev/install.sh -o install.sh sh install.sh ``` The installer detects your OS and architecture (Linux x86-64 and ARM64, macOS Apple Silicon), downloads the matching artifact, verifies its SHA-256 checksum - plus the OpenPGP signature over `SHA256SUMS` when `gpg` is available - and installs the complete verified release. Immutable release trees live under `~/.local/share/atlas-scout/releases` by default, while `~/.local/share/atlas-scout/current` selects the active release. Stable `atlas-scout` and `atlas-scoutd` links in `~/.local/bin` follow that pointer, so the runtime and integration assets move together. Pin a release with `ATLAS_SCOUT_VERSION`. Override the managed release root with `ATLAS_SCOUT_DATA_DIR` (or `XDG_DATA_HOME`) and the executable-link directory with `ATLAS_SCOUT_BIN_DIR`. `ATLAS_SCOUT_INSTALL_DIR` remains a deprecated alias for the link directory. The installer checks whether that directory is on `PATH` and whether another command shadows the installed link. It prints a one-session fix when needed, but never edits your shell profile. When `claude` is available, an interactive install also offers persistent user-scope plugin setup. For a non-interactive install, explicitly opt in with `ATLAS_SCOUT_CLAUDE_PLUGIN=install` only after the user approves, or use `skip`. ### Windows There is no scripted installer yet. Download `atlas-scout--x86_64-pc-windows-msvc.zip` from the release directory referenced by [latest.json](https://download.atlasscout.dev/preview/latest.json), verify its SHA-256 against `SHA256SUMS` from the same directory (`Get-FileHash` in PowerShell), extract it, and add the folder to your PATH. Read the [preview notes](#preview) before running it. **For agents:** a machine-readable install-and-usage skill lives at [atlasscout.dev/atlas-scout.md](https://atlasscout.dev/atlas-scout.md) - an agent can fetch it and follow it end to end. The OS-detecting installer it references is [atlasscout.dev/install.sh](https://atlasscout.dev/install.sh) (checksum- and signature-verified, version overridable via `ATLAS_SCOUT_VERSION`). ### Index and diagnose ```text atlas-scout index /absolute/path/to/project atlas-scout doctor --workspace /absolute/path/to/project ``` Pre-warming is optional - MCP initialization never waits for a repository walk. `index` and `doctor` use concise human-readable output by default; add `--json` for strict JSON or `--machine` for the legacy key/value contract. `doctor` reports the resolved workspace, cache location, coverage, resource profile, daemon endpoint, ready-to-paste host setup, product version, daemon protocol, MCP wire schema, database schema, and upstream MCP protocol revision. These are independent compatibility contracts rather than one shared version number. ### Connect Claude Code manually ```text claude mcp add --scope user --transport stdio atlas-scout -- \ "$HOME/.local/bin/atlas-scout" mcp ``` This is the manual MCP mode. If you changed the executable-link directory, substitute the absolute path printed by the installer. For persistent eager-loaded plugin mode, follow the [Claude Code plugin instructions above](#hosts). ### Connect Codex ```text codex mcp add atlas-scout -- "$HOME/.local/bin/atlas-scout" mcp ``` Without an explicit `--workspace`, Scout resolves the active project from `ATLAS_SCOUT_WORKSPACE`, then `CLAUDE_PROJECT_DIR`, then the MCP working directory. Each workspace stores one database at `.atlas/scout/symbols.db`, shared by every local client; it is generated state - never commit it or copy it between workspaces. For read-only checkouts or CI, `--cache-dir` / `ATLAS_SCOUT_CACHE_DIR` opt into an external location (all sharing clients must use the same override). Start the shared daemon with `atlas-scoutd --idle-seconds 600`; MCP discovers it automatically and falls back to a direct process on the same workspace database. ### CLI at a glance | | | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `atlas-scout index [--json | --machine]` | Build or refresh the generated workspace index, with human or machine-readable output | | `atlas-scout search ` | Search indexed symbols from the terminal | | `atlas-scout schema` | Inspect index coverage and health | | `atlas-scout doctor [--json | --machine]` | Diagnose workspace, storage, resources, compatibility, daemon state, and host or Claude plugin configuration | | `atlas-scout mcp` | Run the local stdio MCP server | | `atlas-scout claude-code hook ` | Serve the Claude Code plugin lifecycle hooks | | `atlas-scout claude-code print-system-prompt` | Print the opt-in Claude Code system-prompt addition | | `atlas-scout claude-code sync` | Align the managed memory section, marketplace registration, and installed plugin with the current runtime | | `atlas-scout license …` | Manage evaluation, activation, status, refresh, devices, deactivation | ## Operations and recovery ### Advanced indexing and resource controls Select a resource profile with `ATLAS_SCOUT_INDEX_MODE=lean|balanced|full`; `balanced` is the default. `lean` tightens memory and per-file bounds, while `full` raises them for larger source files. `ATLAS_SCOUT_MAX_INFLIGHT_MIB` sets the bounded in-flight extraction budget. `ATLAS_SCOUT_INDEX_WORKERS` is an advanced host-tuning override. Benchmark a pinned corpus before keeping it: once extraction outruns the single database writer, more workers can consume more memory and make a complete index slower. `doctor` reports the active settings, and settings that change index content participate in freshness identity. ### Reliability and failure behavior - Normal opens restore the last atomic healthy count snapshot and keep initialization bounded while background reconciliation updates the live state. - Unsupported, failed, stale, indexing, and fresh-empty states remain distinguishable. - The explicit `atlas-scout index` maintenance path performs synchronous physical database verification; detected corrupt generated databases are quarantined and rebuilt. - A valid workspace-local cache carried to a new canonical root is preserved and replaced with a fresh index automatically. - A disconnected or incompatible daemon falls back to a direct local MCP process rather than serving an incompatible schema. - SQLite transactions, coordinated writers, and bounded parsing keep partial writes or one pathological file from stalling the complete index indefinitely. - Any license failure preserves Free indexing and navigation; expiry and downgrade change tool admission without deleting repository or index data. ### Architecture-query containment `symbol_architecture` pre-aggregates symbol and resolved-edge counts by file before joining the bounded module view. Its SQLite work runs on the blocking pool, observes cooperative MCP cancellation, and stops after a five-second internal work budget when an abandoned client never sends cancellation. ### Moving or copying a workspace If a move or copy carries `.atlas` to a different canonical root, Scout does not rewrite or reuse the possibly live SQLite and WAL state from the old location. It preserves the complete valid cache as `.atlas/scout.relocated-`, creates a fresh `.atlas/scout/`, and continues initialization. Workspace setup is serialized through `.atlas/setup.lock`, so concurrent clients agree on the recovery. `atlas-scout doctor` lists preserved relocation archives. They remain ignored local generated data until you choose to remove them. Malformed identity metadata, symlinks, rename failures, and explicit external-cache collisions remain hard errors; Scout leaves that state in place instead of guessing. ### Large repositories and timeouts Normal MCP initialization is bounded even for a large existing index. Cold indexing or background reconciliation may still leave the first query waiting for the evidence it needs. 1. Pre-warm the workspace with `atlas-scout index /absolute/path/to/project`. 2. Raise the host’s tool timeout when the repository justifies it. 3. Confirm the current state with `atlas-scout doctor`; a host-side timeout is not proof that Scout failed. Upgrades may advance the disposable database schema (currently `7`), an extractor version, the MCP result wire schema, or the daemon protocol. The rules are the same in every release: schema migrations run atomically without a forced `VACUUM`; files whose extractor advanced re-extract once during the first reconciliation, which can take longer than an ordinary warm open; and after any upgrade you should restart `atlas-scoutd` and start new MCP host sessions so no client keeps an older protocol or advertised catalog. To roll back, stop Scout, remove the disposable `.atlas/scout/` cache, and rebuild with the older binary rather than opening a newer schema with it. Each release’s notes in the [changelog](https://atlasscout.dev/changelog) state exactly which versions moved. ### Update and restart Atlas Scout checks for updates only when you explicitly ask. A read-only check verifies the signed release channel without downloading an archive or changing your installation: ```text atlas-scout upgrade --check atlas-scout upgrade --check --json ``` Install an available update interactively with: ```text atlas-scout upgrade ``` For an already authorized non-interactive workflow, use `atlas-scout upgrade --accept-unsigned-preview --json`. An agent should first run the read-only JSON check, report the exact current and available versions, and ask before installing. A failed native trust check is an error, not permission to bypass it with the bootstrap installer. 1. Use the native upgrade command when it is available. For an older binary that does not recognize `upgrade`, rerun the verified bootstrap installer once to enter the managed layout. 2. Restart `atlas-scoutd` and start new MCP host sessions. Replacing a binary does not kill running processes; they continue using the old executable until restarted. 3. Run `atlas-scout doctor` after the update. Append-only database migrations run automatically, and ordinary updates leave the workspace index intact. 4. Rebuild only when diagnostics report a compatibility or corruption problem, rather than deleting the index after every update. ### Uninstall Stop Scout processes, remove the host registration (for example, `claude mcp remove atlas-scout` or `codex mcp remove atlas-scout`). For plugin mode, run `claude plugin uninstall atlas-scout@atlas-scout-local --scope user` and then `claude plugin marketplace remove atlas-scout-local --scope user`. Remove only the managed `atlas-scout` and `atlas-scoutd` links from the executable-link directory printed by the installer, then remove the exact managed data root (by default `~/.local/share/atlas-scout`). Resolve and inspect custom paths before deleting them. Workspace indexes contain no user-authored state; after every Scout process has stopped, you may optionally remove each workspace’s `.atlas/` directory and its `.atlas/` entry in `.gitignore`. If you used an external cache override, `doctor` identifies the namespaced directory to remove. ## Atlas Scout is an unsigned technical preview The macOS and Windows binaries do not yet carry Apple or Microsoft publisher signatures. Cryptographic checks prove the downloaded bytes and their build provenance, but they do not provide native publisher trust or an operating-system malware review. If you would rather not run unsigned software, that is a reasonable choice - you can safely wait for the future organization-signed stable release. **Verify before you run.** Before executing a downloaded artifact - and before approving any per-file security exception for it - verify the complete artifact: check it against `SHA256SUMS`, verify the OpenPGP signatures, and verify the artifact’s Sigstore provenance bundle. The [release public key](https://download.atlasscout.dev/keys/atlas-scout-release-public-key.asc) (fingerprint `CA35 C410 D8C7 FE04 8504 6A66 704C 70AA 814F 6D2E`), the signed release manifest, and the checksums ship alongside every release on `download.atlasscout.dev`, all reachable from [preview/latest.json](https://download.atlasscout.dev/preview/latest.json). ### macOS The supported install path is curl-and-tar (our installer). Apple documents that `curl` does not quarantine downloaded files and `tar` does not propagate quarantine while extracting, so the scripted install normally runs without a first-launch Gatekeeper prompt. “Normally” is the honest word: Apple also states that Gatekeeper can run at other times and that the exact circumstances are not documented and can change, so we do not promise a warning-free install. Either way, the binary remains unsigned and unnotarized. Downloading manually with Safari or another quarantine-aware downloader can attach `com.apple.quarantine`, and Finder or another user-level unarchiver can propagate it to the extracted files - Gatekeeper will then say the developer cannot be verified or that Apple cannot check the software for malicious content. If that happens for an artifact you have _verified_, dismiss the warning for only that executable, then use System Settings → Privacy & Security → Open Anyway for that one item, and confirm Open only if the displayed item is the one you just verified. **Two hard rules.** Never override an alert that says the software will damage your computer, contains malware, is damaged, or has been modified - that is not the unsigned-developer warning, and the answer is to delete the file. And our installer never removes quarantine attributes: if a guide or a coding agent suggests `xattr -d com.apple.quarantine`, decline. ### Windows Microsoft Defender SmartScreen may show “Windows protected your PC.” If it offers More info → Run anyway for a _verified_ Atlas Scout executable, that choice applies to that item only; likewise, apply the file Properties Unblock checkbox only per verified executable. Smart App Control in enforcement mode may block the unsigned executable without offering a per-file exception - do not disable that protection. Use an unmanaged supported device or wait for the signed stable release. ### Linux Linux does not use the Apple or Microsoft publisher-signing systems, but the same rule stands: verify the complete artifact - checksums, OpenPGP, Sigstore - before making anything executable, and do not run a file whose checksum differs. ### Managed devices and global protections Managed or strictly configured devices may block unsigned software. Atlas Scout does not ask you to bypass an administrator or organization policy - ever. And never globally disable Gatekeeper, Microsoft Defender SmartScreen, Smart App Control, antivirus, endpoint security, or organization policy on Atlas Scout’s account: every accommodation above is strictly per verified file. ## Privacy and security **Atlas Scout never sends your repository anywhere.** Indexing, graph resolution, ranking, and every MCP query run locally. Licensing requests never contain source code, docstrings, paths, filenames, symbol names, queries, tool calls, editor state, git remotes, or index metrics - only the minimal account, installation, release, and rotating-credential data needed to issue a signed lease. A never-activated Free installation makes no network requests at all; an installation that was activated in the past may keep attempting asynchronous license refreshes after falling back to Free. **The one boundary that is not ours:** Scout hands navigation results - paths, symbol names, bounded code ranges - to the coding agent you connect it to. If that agent is cloud-hosted, its provider receives those requests and results under your agreement with that provider. That traffic belongs to the agent, not to Atlas Scout. **Read-only toward your source files, and non-executing.** Every tool is read-only, idempotent, and closed-world. Scout never executes repository code, package scripts, builds, tests, or git hooks, and never edits your source files - it writes its own index and, for a default local index, appends `.atlas/` to the workspace `.gitignore` once. Reads are constrained to the workspace root, and symlinks pointing outside it are not followed by default. The index lives under the ignored `.atlas/scout/` directory by default (relocatable with `--cache-dir` / `ATLAS_SCOUT_CACHE_DIR`) with user-only permissions, holds structural records and coordinates rather than source bodies, and can be deleted and rebuilt at any time. There is no mandatory telemetry of any kind. ## Current limitations - Local stdio MCP only - no remote or streamable HTTP transport yet. - Disk is authoritative unless a supported editor overlay supplies a newer unsaved buffer. - Relationships are static, flow-insensitive, and precision-first - Scout is not a compiler, type checker, or runtime tracer, and ambiguous targets stay unresolved. - Stored confidence values are evidence-class clusters, not calibrated probabilities. Use the named evidence tier instead of treating a numeric threshold as certainty. - An unconfirmed `unique_method_name` edge is visible but never structural: it cannot extend a graph or trace, form a path hop, or carry edit impact past the first hop. Names never resolve across language families. - Qualified Rust calls require proven Cargo and module context. Glob-derived, macro-expanded, generated, missing-dependency, and unproven trait or type cases remain unresolved rather than guessed. - Go package topology comes from the last indexed package, import, and build-constraint facts. `go.mod` and `go.work` remain disk-authoritative, and Atlas Scout does not perform compiler-complete method-set or build-context analysis. - Semantic anchors are heuristic evidence, not graph edges. - C++ relationships cover a conservative call subset, not compiler-complete semantics; partial-scanner languages do not match the full extractors’ coverage. - Cross-repository navigation is not yet a public workflow. - Bounded results can require pagination or narrower follow-ups; exact literals may still need text search. - Gap pagination in `symbol_schema` requires exactly one directory `path`, and a returned cursor is valid only for that same directory and healthy index generation. - Modern clients receive structured-only tool output. Live Claude Code, Codex, OpenCode, and Antigravity checks prove functional compatibility, not that every host avoids reserializing that data internally. - Scout selects and describes ranges - reading, editing, and validating remain yours (or your agent’s). ## Frequently asked questions Does Atlas Scout upload my repository? No. Indexing and navigation happen locally. License requests never include repository content, identity, paths, symbols, queries, or usage data. Does it modify my source code? No. Every MCP tool is read-only and Scout never executes project code or hooks. On first open it creates the ignored .atlas/ directory and idempotently adds .atlas/ to your .gitignore - it does not touch source files. Is it an AI model? No. Atlas Scout is deterministic local navigation infrastructure for AI agents. The connected agent decides how to use the evidence Scout returns. Does it replace text search? No - it replaces text search only where text search is the wrong tool. Structural questions (definitions, callers, paths, impact) go to Scout; exact literals, regexes, and unsupported constructs still belong to grep. Is it a language server or compiler? No. It is a persistent multi-language structural map optimized for bounded agent queries. It does not build, type-check, or claim compiler-level completeness. Does Free use a worse index? No. Free and Pro share the same extraction, indexing, relationship resolution, freshness, and ranking. Pro unlocks deeper connected-analysis tools, never index quality. Do I need an account for Free? No. Free is permanent and accountless. A verified account is needed only for the Pro evaluation or a paid subscription. What happens when my trial or subscription ends? Atlas Scout falls back non-destructively to Free (or to an earned perpetual fallback). Index, settings, and integrations are kept; a later purchase unlocks Pro again with no reindex. Can it work offline? Yes. Free never needs a network. Pro runs from a locally verified cached lease for up to 30 days; refresh is asynchronous and never blocks startup. Why ranges instead of whole files? Coordinates, stable IDs, and relationships cost far fewer tokens than embedded source. The agent reads exactly the ranges that matter - that is the point. Can several agents share one index? Yes - automatically. All local agents, CLI processes, and editors on the same workspace share .atlas/scout/symbols.db, even as independent processes. The optional atlas-scoutd daemon adds warmth and editor overlays; it does not own a separate index. A Pro license covers one named person on up to three installations. How do I reset the index? Confirm the database path with atlas-scout doctor, stop Atlas Scout processes, remove .atlas/scout/, and index again. The index holds no user-authored state - but never remove the directory while a client or daemon is writing to it. ## Product principles Return evidence, not guesses. Prefer coordinates over bulk source. Keep results bounded and explain truncation. Report the unsupported and unresolved honestly. Keep repository data local, never execute it. Keep Free useful and permanent - gate advanced tools, never index quality or user data. And preserve Free access and local data through every license failure or downgrade.