Atlas

Local-first semantic knowledge graph engine for LLM agents.

Atlas parses source code with tree-sitter, stores deterministic code facts in a local SQLite database, and exposes those facts through an interactive TUI, a CLI, and an MCP server. It is built for agents and developers that need reliable codebase context: symbol search, callers/callees, dependency edges, impact analysis, point inspection, bounded variable and caller tracing, forward call-chain queries, and C/C++ function-pointer dispatch annotations.

source code ──parse/extract──▶ .atlas/atlas.db ──query──▶ TUI / CLI / MCP
            tree-sitter facts     SQLite source of truth      agent & developer context

Table of contents

• Features
• Install
• Quick start
• CLI
• MCP server
• Architecture
• Supported languages
• Documentation
• Development
• Known limitations
• License

Features

• Local-first: writes all index data to <project>/.atlas/atlas.db; no cloud service required.
• Deterministic extraction: tree-sitter AST queries and stable blake3-based IDs instead of model guesses.
• Incremental sync: content-hash based dirty-file detection with Git-aware file discovery.
• Interactive TUI: keyboard-driven Ratatui workbench with symbol search, detail tabs, caller trace, typed parameter forms backed by the same analysis handlers as MCP, and human-oriented result views. Code facts, source, paths, and rules are presented directly; capability, confidence, coverage, and refinement state live in an adaptive HUD. Raw JSON remains available with r for auditing. Context and resumable query IDs are injected automatically. Bare atlas bootstraps the default structural index when needed.
• Agent-native MCP: stdio MCP server exposing 15 bounded tools for open-first scoped search, graph, dependencies, trace, semantic analysis, background work visibility, and project management.
• Symbol-scoped cold start: focus expansion follows relevant call/type symbols rather than every peer in a source file. Import/include neighbors stay at the lightweight resolution-symbol layer until a verified relationship requires structural facts; background success and failure both converge to an explicit terminal response.
• Graph + trace queries: callers, callees, shortest path, impact, source-position lookup, variable origin tracing, and caller-path tracing.
• Explicit capability boundaries: language capability metadata and trace diagnostics report partial results instead of silently overclaiming precision.

Install

Requirements

• Rust 1.85+ (Rust edition 2024)
• Git, recommended for file discovery (atlas falls back to filesystem traversal when needed)

Build from source

git clone https://github.com/LordCasser/atlas.git
cd atlas
cargo build --release -p atlas-cli --features mcp

The binary is generated at target/release/atlas.

You can also install the local binary into Cargo's bin directory:

cargo install --path crates/atlas-cli --features mcp

Quick start

# Run from your project root

# Auto-initialize the SQLite schema and build the index
atlas index

# Check project health
atlas status
atlas doctor

# Launch the interactive TUI (search, detail, trace, MCP-backed analysis palette)
atlas

All subcommands accept --project <path> when running from outside the project directory (supports both relative and absolute paths). Bare atlas uses the current directory and does not accept --project; run it from the project root. The MCP server uses the client's current working directory.

CLI

MCP server

The MCP server is open-first: call project(action="open") to activate a project, then use scoped tools to trigger focus-driven extraction for the code needed by the current investigation. Explicit project-wide indexing is CLI-only:

# From your project root:
atlas mcp
# optional, outside MCP, when you want a project-wide cache:
atlas index --analysis full

MCP opens project/.atlas/atlas.db and reuses compatible facts when available. Without a full CLI-built index, scoped queries expose bounded refinement through analysis.retry_after_ms, query_id, tasks, and resume_query; terminal limitations are returned as structured gaps.

Client configuration

Atlas MCP uses the client's current working directory. Configure the MCP server without a project path, and start the client from the repository you want Atlas to inspect. You can also switch projects at runtime with the project MCP tool using action: "open".

Config files by client:

Claude/Cursor-style clients use mcpServers with command and args. OpenCode uses its own mcp object: each server is type: "local" and command is a single array containing the executable and arguments.

MCP server config

Use the same no-project configuration for every repository.

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "atlas": {
      "command": "/path/to/atlas",
      "args": ["mcp"]
    }
  }
}

OpenCode (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlas": {
      "type": "local",
      "command": ["/path/to/atlas", "mcp"],
      "enabled": true
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.atlas]
command = "/path/to/atlas"
args = ["mcp"]
enabled = true

Tool groups

project(action="open") supports switching the active project at runtime. It opens the persistent project/.atlas/atlas.db; project activates a project but never scans or indexes the whole tree.

Trace tools return the TraceQueryResponse<T> envelope documented in docs/trace-contract.md: ok, kind, capability, partial_result, diagnostics, and result.

Architecture

Atlas is a Rust workspace with 16 Cargo packages. The public entry points are atlas-cli (CLI + TUI), atlas-mcp, and the atlas-engine facade. Engine internals are split by responsibility so extraction, persistence, graph construction, search, context, dossier assembly, focus scheduling, and trace can evolve independently. The current storage contract is Schema V2: one persistent SQLite database plus bounded focus extraction, not a second application-level cache store.

For a cold scoped query, Focus keeps two distinct boundaries: relevant files receive structural extraction, while import/include dependencies normally receive only resolution_symbols. Scoped resolution is rerun as that boundary grows, and call/type expansion proceeds from relevant symbol IDs to a bounded fixed point. Files are counted as covered only after facts are built or reused successfully.

Lazy cache reuse also checks structural invariants that a content hash cannot express. In particular, stale multiline type ranges produced by older extractor semantics are rebuilt on demand across supported brace-based languages, including struct/class/union/interface/trait/enum scopes, so an existing partial index does not permanently preserve a one-line type definition.

Native TUI search is store-backed and available immediately, even before the in-memory graph snapshot is ready. The first graph-backed detail view loads that snapshot through the existing background job system, keeping the terminal event loop responsive.

Graph queries synchronously materialize only their exact seed and return bounded facts; requested multi-hop closure expansion is tracked as resumable background work. Function- local semantic queries stay local: lifecycle composes CFG and dataflow effects at query time and can track both fields and local C/C++ resources, including common Linux kernel allocators and deallocators.

atlas/
├── crates/
│   ├── atlas-cli                 # CLI binary + TUI (ratatui) + command dispatch
│   ├── atlas-mcp                 # stdio MCP server powered by rmcp + Atlas tool router
│   └── atlas-engine              # public facade crate re-exporting core APIs
│       └── crates/
│           ├── types             # IDs, IR records, language/capability metadata
│           ├── workspace         # project root and source-path abstractions
│           ├── db                # SQLite schema, Store, readers/writers
│           ├── extraction        # tree-sitter frontends, SCM queries, scopes, bindings, dataflow, CFG
│           ├── resolution        # reference/import/include/path-alias resolution
│           ├── graph             # symbol edge builder, graph snapshot, graph traversal engine
│           ├── analysis          # trace engine, variable slicing, caller-path analysis
│           ├── domain_rules      # domain-specific semantic rules and rule learning
│           ├── search            # FTS5 + LIKE + fuzzy search and query parsing
│           ├── context           # agent-facing Markdown context builder
│           ├── filesync          # file discovery, content hashing, incremental sync, locks
│           └── lazy              # on-demand dataflow job planning and loading
├── docs/                          # architectural and release documentation
├── skills/atlas/                 # Agent Skill for using Atlas
├── Cargo.toml                    # workspace manifest
└── README.md

Data pipeline

1. Discover files
   └─ Git-aware discovery + include/exclude filters
2. Parse and extract
   └─ tree-sitter frontends produce FileFacts: symbols, scopes, refs, imports, callsites, bindings, dataflow, CFG
3. Persist facts
   └─ SQLite tables under .atlas/atlas.db are the source of truth
4. Resolve references
   └─ scope/container/import/include/project-name matching; unresolved facts keep diagnostics instead of failing indexing
5. Build graph
   └─ resolved refs and callsites become symbol_edges; GraphSnapshot accelerates read-only traversal
6. Serve queries
   └─ TUI, CLI commands, and MCP tools call SearchEngine, GraphEngine, ContextBuilder, and TraceEngine

Dependency direction

atlas-cli ──▶ atlas-engine, atlas-mcp
atlas-mcp ──▶ atlas-engine

atlas-engine facade ──▶ types, workspace, db, extraction, resolution,
                        graph, analysis, domain_rules, search, context,
                        filesync, lazy

engine internals stay acyclic:
types/workspace/db ─▶ extraction/resolution/graph/analysis/domain_rules/search/context/filesync/lazy ─▶ facade/API

Storage model

Atlas stores index data in .atlas/atlas.db (schema version 2). Core tables include:

files                    symbols            scopes               references
imports                  symbol_edges       callsites            bindings
binding_uses             data_nodes         dataflow_edges       cfg_nodes
cfg_edges                function_summaries summary_param_reaches summary_return_sources
summary_call_arg_sources extraction_state   extraction_jobs      project_metadata
symbols_fts              function_pointer_annotations

SQLite is the durable source of truth. In-memory graph snapshots are query accelerators and can be rebuilt from the database.

Supported languages

All 14 languages are compiled by default: