Atlas Context Router

     _  _____ _      _   ___
    / \|_   _| |    / \ / __|
   / _ \ | | | |__ / _ \\__ \
  /_/ \_\|_| |____/_/ \_\___/

  graph-aware code context for CLI and MCP workflows

Atlas scans repository code, builds graph structure, stores it in SQLite, and serves graph-aware context to both CLI workflows and MCP-based coding agents.

Area	What Atlas gives you
Graph build	tracked-file scan, parse, persist into .atlas/worldtree.db
Incremental update	rebuild only from git or working-tree changes
Search and impact	symbol lookup, call/risk traversal, review context
Agent tooling	MCP broker/daemon server, install helpers, repo hooks, editor integration

Supported languages in current build:

• Rust
• Go
• Python
• JavaScript
• TypeScript

Install

Latest release

Download installer from latest GitHub release assets:

curl -fsSLO https://github.com/ffimnsr/atlas-context-router-rs/releases/latest/download/install.sh
curl -fsSLO https://github.com/ffimnsr/atlas-context-router-rs/releases/latest/download/install.sh.sha256

sha256sum -c install.sh.sha256 2>/dev/null || shasum -a 256 -c install.sh.sha256
sh install.sh

Release notes:

• install.sh.sha256 is not stored in repo root; release workflow generates it and publishes it as a release asset
• install.sh.sha256 ships with each release
• install.sh verifies downloaded Atlas archive checksums before install
• release archives are published for Linux musl, macOS x86_64, and macOS arm64

If latest-release URLs are not available yet, use one of these fallback paths:

cargo install --path packages/atlas-cli

Maintainer-only raw installer fallback:

curl -fsSLO https://raw.githubusercontent.com/ffimnsr/atlas-context-router-rs/main/install.sh
sh install.sh

Raw main installer is not release-pinned. Prefer release assets once first tagged release exists.

Build from source

cargo install --path packages/atlas-cli

Run from workspace

cargo run -p atlas-cli -- --help

Build container image

Build the multi-stage container image from the repository root:

podman build -f Containerfile -t atlas .

Docker works as well:

docker build -f Containerfile -t atlas .

The default builder and runtime images in Containerfile are pinned to immutable Chainguard digests. Override them explicitly if you need newer base images during maintenance:

podman build \
  --build-arg RUST_IMAGE=cgr.dev/chainguard/rust:latest-dev \
  --build-arg GIT_RUNTIME_IMAGE=cgr.dev/chainguard/git:latest-glibc \
  -f Containerfile \
  -t atlas .

Refresh the pinned digests in Containerfile to the latest upstream tags:

scripts/update-containerfile-images.sh

Preview the resolved references without editing files:

scripts/update-containerfile-images.sh --dry-run

Run Atlas against the current repository by mounting the workspace into the container:

podman run --rm -it \
  -v "$PWD":/work \
  -w /work \
  atlas status

Atlas shells out to git, so the runtime stage uses a minimal Git-capable base image instead of a shell-free static runtime.

Quick Start

Inside any git repository:

atlas init --profile standard
atlas build
atlas status
atlas debug-config
atlas query "symbol_name"

Repair local Atlas state without rebuilding graph data:

atlas migrate
atlas config show
atlas selfupdate

Review recent work against mainline:

atlas update --base origin/main
atlas detect-changes --base origin/main
atlas impact --base origin/main
atlas review-context --base origin/main
atlas review-context --base origin/main --format markdown

Benchmarks

Local smoke benchmark on this repository, using target/release/atlas with a prebuilt .atlas/worldtree.db graph. Host: Linux 6.19, AMD Ryzen 5 5600X, 12 logical CPUs. Numbers are best read as order-of-magnitude guidance, not a portable guarantee.

Symbol lookup for WatchRunner, 30 warm runs:

Tool	Command shape	Avg wall time	Output size
grep	grep -RIn --include='*.rs' WatchRunner . with build dirs excluded	6.8 ms	1.3 KiB
rg	rg -n WatchRunner --glob '*.rs'	6.8 ms	1.3 KiB
atlas query	atlas --json query WatchRunner --limit 20	9.1 ms	20.4 KiB

Context gathering for WatchRunner, comparing raw nearby text against bounded graph context:

Tool	Command shape	Avg wall time	Context payload	Compression vs raw text
grep	related-symbol regex with -C 8 over known watch files	3.3 ms	47.8 KiB	baseline
rg	related-symbol regex with -C 8 over known watch files	5.6 ms	47.8 KiB	baseline
atlas context	atlas --json context WatchRunner --max-nodes 20 --max-edges 20 --max-files 10	35.5 ms	3.1 KiB	93.5% smaller

Use grep or rg for raw text search. Use Atlas when caller/callee links, impact, review context, or MCP token budget matter more than the fastest line scan.

Project Policy and Maintenance

Repository workflow and support docs live at the root:

• CONTRIBUTING.md
• SECURITY.md
• SUPPORT.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md
• docs/error_codes.md

GitHub triage defaults also live in .github/:

• .github/CODEOWNERS
• .github/PULL_REQUEST_TEMPLATE.md
• .github/ISSUE_TEMPLATE/

LLM Agent Setup

Atlas can install MCP configuration for popular AI coding tools and add repo hooks so agents start with graph-aware context.

atlas serve remains a stdio MCP entrypoint for editors and agents. Repo-scoped installs now pin only --repo, while user/global installs stay portable with type = "stdio", command = "atlas", args = ["serve"]. When no repo is pinned, Atlas resolves repo root from MCP client roots/list and derives DB path as REPO_ROOT/.atlas/worldtree.db; if roots are unavailable, Atlas falls back to repo root discovered from launch cwd.

If an editor MCP client is incompatible with broker/daemon indirection, use atlas serve --direct-stdio to run MCP directly in launched process with no relay layer.

GitHub Copilot

atlas install --platform copilot
atlas build

Writes MCP config under .vscode/mcp.json.

Claude Code

atlas install --platform claude
atlas build

Writes MCP config under .mcp.json.

Codex

atlas install --platform codex
atlas build

Writes Codex MCP entry into .codex/config.toml.

Auto-detect installed tools

atlas install

Preview without writing files

atlas install --dry-run

atlas install will:

• write MCP server config for GitHub Copilot, Claude Code, or Codex
• install git hooks for pre-commit, post-checkout, post-merge, and post-rewrite
• inject graph-first instructions into platform-relevant agent files (AGENTS.md for Copilot/Codex, CLAUDE.md for Claude)

Hook behavior:

• pre-commit prints full change summary
• post-checkout, post-merge, and post-rewrite use brief output

After install, restart your editor or coding tool, then run:

atlas build

Repo-local MCP coordination state lives under .atlas/mcp/<instance-id>/:

• mcp.instance.lock
• mcp.instance.json
• mcp.sock on Unix

instance-id is derived from canonical repo root plus canonical DB path, so same repo with different DBs can run separate daemons while same repo plus same DB reuses one backend.

Canonical Path Migration

Atlas treats repo-relative paths as canonical identity for persisted graph rows, content source IDs, chunk seeds, and session file references.

Shared path normalization now happens in atlas-repo: separators become /, Unicode folds to NFC, Windows identities fold case, and CLI/watch boundary absolute paths prefer filesystem-canonical spelling so case-insensitive filesystems do not drift. Repo scan skips symlinks and dedupes canonical submodule roots to guard loop topologies.

Audit coverage:

• graph store persistence and lookup keys go through canonical files.path / nodes.file_path identity before reuse or persistence
• file-hash reuse in full and incremental build paths uses the same canonical graph file keys
• content source_id and chunk_id seeds require canonical repo-path identity for file-backed artifacts
• session payload normalization and resume snapshot file references canonicalize repo-file paths before persistence
• MCP explicit files inputs canonicalize repo-relative paths before change-source resolution
• future sidecar/cache/index keys, including parser tree-cache entries, must reuse the same canonical repo-path spelling

If atlas doctor or atlas db-check reports noncanonical_path_rows, rebuild from clean canonical inputs instead of trying to rewrite stale rows in place:

atlas purge-noncanonical
atlas build

atlas purge-noncanonical removes repo-local context.db and session.db state, keeps worldtree.db, and leaves rebuild plus session bootstrap explicit.

Shell Completion

Generate completion script to stdout:

atlas completions bash
atlas completions zsh
atlas completions fish
atlas completions powershell

Example for Bash:

atlas completions bash > ~/.local/share/bash-completion/completions/atlas

Example for Zsh:

mkdir -p ~/.zfunc
atlas completions zsh > ~/.zfunc/_atlas

Typical Workflows

Bootstrap graph for a repo

atlas init
atlas build
atlas status

Review branch against main

atlas update --base origin/main
atlas detect-changes --base origin/main
atlas impact --base origin/main
atlas review-context --base origin/main

Install editor and hook integration

atlas install --platform copilot
atlas build

Common Commands

Initialize repository state:

atlas init

Full rebuild:

atlas build

Incremental update from working tree or git base:

atlas update
atlas update --base origin/main
atlas update --staged

Show graph status:

atlas status
atlas status --base origin/main

Search graph nodes:

atlas query "AuthService"
atlas query "login" --kind function --language rust
atlas query "router" --subpath packages/atlas-cli --expand --expand-hops 2

# regex filter: text is the pattern, matched against name/qualified_name via SQL UDF
atlas query "^handle_[a-z]+" --regex
atlas query "(body|node)" --regex --kind function

Inspect changed files:

atlas detect-changes
atlas detect-changes --base origin/main
atlas detect-changes --staged

Compute blast radius:

atlas impact --base origin/main
atlas impact --files packages/atlas-cli/src/commands.rs

Assemble review context:

atlas review-context --base origin/main
atlas review-context --base origin/main --format markdown
atlas review-context --files packages/atlas-cli/src/install.rs

Explain changed code with impact and risk summary:

atlas explain-change --base origin/main
atlas explain-change --files packages/atlas-cli/src/commands.rs

Dead-code scan and deterministic rename preview:

atlas analyze dead-code --subpath packages/atlas-cli
atlas refactor rename --symbol src/lib.rs::fn::helper --to helper_renamed --dry-run

Run MCP server over stdio:

atlas serve

Health and integrity checks:

atlas doctor
atlas db-check

Context Engine (atlas context)

atlas context builds bounded, machine-readable context around a symbol, file, or change-set.

Common forms:

atlas context "AuthService"
atlas context "who calls handle_request"
atlas context --file src/auth.rs
atlas context --files src/auth.rs src/session.rs --intent impact
atlas --json context --files src/auth.rs src/session.rs

Key knobs:

• --intent: symbol, file, review, impact, usage_lookup, refactor_safety, dead_code_check, rename_preview, dependency_removal
• limits: --max-nodes, --max-edges, --max-files, --depth
• extra detail: --code-spans, --tests, --imports, --neighbors

Default limits: 100 nodes, 100 edges, 20 files, depth 2.

JSON output uses atlas_cli.v1 and returns request metadata, selected nodes and edges, file spans, truncation info, and optional ambiguity candidates. If target is ambiguous, ambiguity is populated instead of direct node results. atlas review-context remains available as focused shortcut for review-heavy workflows.

Contract references:

• Output stability policy
• TOON contract
• schemas/atlas_cli.v1/*.schema.json

Output Modes

Most user-facing commands support machine-readable output:

atlas --json status
atlas --json detect-changes --base origin/main
atlas --json install --platform claude

Files Atlas Writes

• .atlas/config.toml
• .atlas/worldtree.db
• .mcp.json for Claude Code installs
• .vscode/mcp.json for GitHub Copilot installs
• .codex/config.toml entry for Codex installs
• .git/hooks/* for installed git hooks

Insights

Atlas also exposes deterministic insight reports through CLI:

atlas insights architecture
atlas insights metrics --limit 20
atlas insights risk src/service.rs::fn::compute
atlas insights patterns --limit 20
atlas insights large-functions --threshold 80 --mode large-or-complex
atlas insights complex-functions --complexity-threshold 15
atlas --json insights metrics

Thresholds and layer rules live under .atlas/config.toml:

[insights]
large_function_loc = 80
high_fan_in = 20
high_fan_out = 10
high_coupling = 15
deep_chain_length = 6
repeated_call_chain_min_length = 3
risk_medium_threshold = 35.0
risk_high_threshold = 70.0

[[insights.layer_rules]]
name = "api"
path_prefixes = ["src/api"]
module_prefixes = []

[[insights.layer_rules]]
name = "domain"
path_prefixes = ["src/domain"]
module_prefixes = []

MCP Tools

The MCP server (atlas serve) exposes these tools to agents:

Tool	Description
list_graph_stats	Node/edge counts and language breakdown
man	Runtime manual for one visible exported MCP tool
query_graph	Keyword search with optional regex SQL-UDF filter; returns compact symbol list
batch_query_graph	Run up to 20 query_graph searches in a single round-trip
search_files	File-path discovery for config, templates, SQL, Markdown, and other non-code assets
search_content	Literal or regex content search outside graph-symbol lookup
read_file_excerpt	Repo-scoped file excerpt reads by line range or line-with-context
get_docs_section	Markdown section lookup by heading path/slug or line number
read_file_around_match	Grouped snippets around literal or regex matches in one file
search_templates	Discover HTML, Jinja, Handlebars, Tera, and related template files
search_text_assets	Discover SQL, config, env, and prompt files
broker_status	Lightweight broker liveness probe: PID, uptime, version
status	Compact graph health summary with machine-readable failure state
doctor	Full repo health checks: git, config, DB, build, and retrieval index
db_check	SQLite integrity plus orphan-node and dangling-edge scan
debug_graph	Graph internals: node/edge kinds, top files, and anomalies
explain_query	Explain how query_graph will tokenize and execute a request
resolve_symbol	Resolve a symbol or QN alias to canonical qualified_name
analyze_architecture	Deterministic architecture report with cycles, layers, and coupling hotspots
analyze_metrics	Deterministic metrics report with outliers and complexity hotspots
assess_risk	Deterministic risk assessment for one symbol with factor evidence
analyze_patterns	Deterministic pattern detection for repeated chains and isolated structures
analyze_safety	Refactor-safety analysis with callers, fan-out, and test adjacency
analyze_remove	Removal-impact analysis with bounded evidence
analyze_dead_code	Dead-code candidate detection with certainty tiers and blockers
analyze_dependency	Dependency-removal validation for a symbol
find_large_functions	Deterministic large/complex function discovery with thresholds and ranked evidence
find_complex_functions	Deterministic complex-function discovery with complexity thresholds
get_impact_radius	Graph traversal from changed files
get_review_context	Review bundle: symbols, neighbors, risk summary
get_context	General context engine: symbol, file, review, impact
detect_changes	Git diff → changed-file list with node counts
build_or_update_graph	Full scan or incremental graph update
postprocess_graph	Refresh derived graph analytics after build/update without reparsing
traverse_graph	Bi-directional graph traversal from a qualified name
get_minimal_context	Auto-detect changes and return compact impact bundle
explain_change	Advanced impact: risk, change kinds, boundary/test gaps
get_session_status	Current session identity, event count, and resume state
compact_session	Compact session event ledger: merge, decay, dedup, promote
resume_session	Retrieve and consume current session snapshot
search_saved_context	Search saved artifacts from prior tool outputs
search_decisions	Search persisted decision memory for prior conclusions
read_saved_context	Retrieve full artifact content by source_id with optional paging
save_context_artifact	Store large context payloads for later retrieval
get_context_stats	Session/content-store stats and DB paths
purge_saved_context	Delete saved artifacts by session or age
cross_session_search	CM11: search saved context across all sessions for this repo
get_global_memory	CM11: frequent symbols/files/workflows and related past sessions
symbol_neighbors	Immediate callers, callees, tests, and nearby graph nodes
cross_file_links	Files semantically linked to a file by shared symbol references
concept_clusters	Related file groups around seed files by coupling density

Graph tools answer code structure questions; content tools answer non-code context-adjacent questions (docs, config, templates, SQL, prompts). Use both as companion surfaces, not as a fallback chain.

Manual surface:

• atlas man mcp <mcp_tool_name> prints runtime docs derived from live MCP registry metadata
• MCP man returns same manual payload without executing target tool

Search tool selection rules:

1. query_graph: use for symbol names, definitions, and graph-native relationships.
2. search_files: companion lookup for config, template, SQL, Markdown, and other non-code assets not indexed as graph symbols.
3. search_content: companion lookup for text matches; use alongside graph results when changed files include embedded constants, config keys, SQL fragments, or error strings.
4. read_file_excerpt: use when file path is already known and you need precise line ranges or one line with bounded surrounding context.
5. get_docs_section: use for Markdown docs when section identity matters more than raw line ranges.
6. read_file_around_match: use when file path is known and you need grouped context around matched lines.
7. search_templates: companion lookup for HTML, Jinja, Handlebars, and related template files when changed files include templates.
8. search_text_assets: companion lookup for SQL, config, .env, and prompt files when changed files or graph evidence points to non-code assets. Pass results to get_context via files= to merge under bounded selection policy.

MCP Prompts

The MCP server also exposes prompt templates for external LLM clients that support prompts/list and prompts/get:

Prompt	Purpose
review_change	Guide review flow through detect_changes, get_minimal_context, get_review_context, explain_change, and get_impact_radius
inspect_symbol	Guide symbol lookup through query_graph, symbol_neighbors, get_context, and traverse_graph
plan_refactor	Guide refactor planning through context, impact, coupling, and safety checks
resume_prior_session	Guide continuity recovery through session status, resume snapshot, and saved-context retrieval

These prompts are guidance only. Atlas still keeps graph, context, impact, and continuity logic in tools rather than hard-coding behavior into prompt text.

Output defaults:

• get_context, get_review_context, get_impact_radius, and explain_change default to toon
• all other tools default to json
• explicit output_format=json overrides TOON-first behavior

get_context accepts free-text query, file, or changed-file list plus intent and limit controls. Response is compact PackagedContextResult with counts, selected nodes and edges, files, truncation fields, and optional ambiguity candidates.

Recommended agent workflow:

1. detect_changes
2. get_minimal_context or get_review_context
3. get_impact_radius or explain_change
4. query_graph or get_context
5. when changed files include docs, config, templates, SQL, or prompts: call search_text_assets or search_templates as companion lookup, then pass results into get_context via files= to merge under bounded selection policy
6. do not use content search before graph tools for symbol questions

Contributing

Contributions welcome.

Current repo expectations:

• keep diffs focused and avoid unrelated refactors
• prefer small safe changes over broad churn
• add or update tests for behavior changes
• run cargo test and cargo clippy -- -D warnings before sending changes
• check ISSUES.md for existing tracked work before starting

Useful commands:

cargo test
cargo clippy --workspace -- -D warnings

License

See LICENSE and LICENSE-APACHE for repository license texts.