Atlas Context Router Rs

Atlas Context Router

[](https://github.com/ffimnsr/atlas-context-router-rs/actions/workflows/ci.yml) [](https://github.com/ffimnsr/atlas-context-router-rs/releases) [](LICENSE)

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

  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](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](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](CONTRIBUTING.md)
• [SECURITY.md](SECURITY.md)
• [SUPPORT.md](SUPPORT.md)
• [CODEOFCONDUCT.md](CODEOFCONDUCT.md)
• [CHANGELOG.md](CHANGELOG.md)
• [docs/errorcodes.md](docs/errorcodes.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 it falls back to 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//:

• 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](docs/contracts/output-stability.md)
• [TOON contract](docs/contracts/atlas_toon.v1.md)
• 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 | | 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, an

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ffimnsr
• Source: ffimnsr/atlas-context-router-rs
• License: MIT
• Homepage: https://github.com/ffimnsr/atlas-context-router-rs/wiki

Install and usage instructions live in the source repository linked above.