Atlas Scout documentation

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_pathsblock 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.

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

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

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. 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.

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.

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

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.

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

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:

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, alongside its signed Preview 29 release. 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

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 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 upgraderuns the upgraded binary’s sync after promotion, so each release carries its own hooks, skill, and MCP declaration forward. atlas-scout doctorreports 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. SessionStartalso 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.

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.

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:

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.

claude --append-system-prompt "$(atlas-scout claude-code print-system-prompt)"
claude -p "<prompt>" --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 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 always names the current release and links its manifest, signatures, public key, and checksums.

The short version of this section lives at atlasscout.dev/install - one shareable page with the agent prompt, the install script, and the verification steps.

Linux and macOS

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-<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 add the folder to your PATH. Read the preview notes before running it.

For agents: a machine-readable install-and-usage skill lives at 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 (checksum- and signature-verified, version overridable via ATLAS_SCOUT_VERSION).

Index and diagnose

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

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.

Connect Codex

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

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-<workspace-id>, 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 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:

atlas-scout upgrade --check
atlas-scout upgrade --check --json

Install an available update interactively with:

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 (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.

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.