<div align="center"> <img src="assets/banner.jpg" alt="CodeAtlas Banner" width="100%" /> </div>

CodeAtlas

Local dependency graphs and context intelligence for AI coding agents.

CodeAtlas indexes your codebase into a local SQLite database (.atlas/atlas.db), mapping relationships between files, functions, classes, and packages. It connects to AI coding assistants (Google Antigravity, Claude Code, Cursor, Windsurf, Copilot) via the Model Context Protocol (MCP) and editor extensions, giving them the architectural context needed to edit large repositories without hallucinating imports or breaking downstream dependencies.

---

Why CodeAtlas?

AI coding models are effective at writing code within a single file, but they are context-blind to repository-wide architecture. When editing mid-to-large codebases, they frequently:

• Import modules that do not exist or bypass public boundaries.
• Introduce circular dependencies between packages.
• Miss downstream callers that break when a function signature changes.
• Waste 80–90% of prompt token budgets on irrelevant file boilerplate.

CodeAtlas builds a local directed graph of your repository so both developers and AI assistants can answer:

• What files will break if I change this function?
• Where is this endpoint or service actually consumed?
• Which modules have circular dependencies or layer violations?
• What is the minimum necessary context for this task?

All indexing runs locally. Source code never leaves your machine.

---

Example

When you modify a file in your project:

atlas diff

CodeAtlas inspects the change surface against the dependency graph:

Target: packages/storage/src/search.ts

Direct Dependents (1-hop):
  packages/retrieval/src/retrieval-engine.ts
  packages/mcp/src/mcp-server.ts

Transitive Impact (2-hop):
  apps/cli/src/commands/search.ts
  apps/vscode-extension/src/extension.ts

Risk Level: MEDIUM (4 downstream files affected)
Architecture Health: Clean (0 circular dependencies, 0 layer leaks)

AI assistants query this graph before editing, allowing them to verify downstream callers and maintain modular boundaries.

---

Quickstart

1. Install the CLI

npm install -g @codeatlas-ai/cli

2. Index Your Project

Navigate to your project root:

# Detect project stack and create local .atlas/ directory
atlas init

# Parse AST structures and build the local dependency graph
atlas index

3. Connect to Your AI Assistant

Automatically configure MCP for all detected tools (Cursor, Claude Code, Antigravity, Windsurf):

atlas mcp setup --all

---

VS Code & Cursor Extension

CodeAtlas provides an official extension for VS Code, Cursor, and Windsurf featuring an interactive 2D/3D architecture canvas, real-time blast radius monitoring, and CodeLens navigation.

• Marketplace: Search for CodeAtlas (shditz.codeatlas-official) in the Extensions tab (Ctrl+Shift+X / Cmd+Shift+X).
• Terminal:

  code --install-extension shditz.codeatlas-official
  

  (For Cursor: cursor --install-extension shditz.codeatlas-official)

---

How It Works

┌─────────────────┐        AST & Imports        ┌────────────────────────┐
│  Source Code    │ ──────────────────────────> │   CodeAtlas Engine     │
│  (Local Disk)   │                             │   (.atlas/atlas.db)    │
└─────────────────┘                             └───────────┬────────────┘
                                                            │
                            ┌───────────────────────────────┴───────────────────────────────┐
                            ▼                                                               ▼
             ┌─────────────────────────────┐                                 ┌─────────────────────────────┐
             │    VS Code / Cursor IDE     │                                 │     AI Coding Assistants    │
             │  • 2D/3D WebGL Graph Canvas │                                 │  • 22 Model Context Tools   │
             │  • Live Blast Radius Status │                                 │  • Live Architecture Rules  │
             │  • CodeLens Navigation      │                                 │  • Skeletonized AST Prompts │
             │  • Diagnostics & QuickFix   │                                 │  • Token Budget Packing     │
             └─────────────────────────────┘                                 └─────────────────────────────┘

1. AST Extraction & Secret Redaction: Parses source files using Tree-sitter grammars. Built-in filters redact API keys, JWTs, and credentials before data is stored or passed to context.
2. Semantic Resolution: Resolves relative imports, path aliases (@/*), and class/interface inheritance hierarchies (extends / implements).
3. Graph Storage & Metrics: Stores symbols and dependency edges in SQLite. Computes PageRank, modularity clusters, instability metrics, and circular dependency chains.
4. Context & MCP Delivery: Exposes 22 Model Context Protocol (MCP) tools and updates architecture rules for .cursor/rules/, CLAUDE.md, and AGENTS.md.

---

Language Support

CodeAtlas parses ASTs and resolves dependencies across common programming languages:

| Category | Languages / Frameworks | Supported File Extensions | | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | Full AST & Semantics | TypeScript, JavaScript, Python, Go, Rust, Dart, Scala, Lua, Elixir, Erlang, Zig, GraphQL, Vue, Svelte, Astro, SQL, NestJS, Prisma | .ts, .tsx, .js, .jsx, .py, .go, .rs, .dart, .scala, .lua, .ex, .zig, .graphql, .vue, .svelte, .astro, .sql, .prisma | | Structural Analysis | Java, C#, C, C++, PHP, Ruby, Kotlin, Swift | .java, .cs, .c, .cpp, .h, .hpp, .php, .rb, .kt, .swift | | Content & Search | JSON, YAML, TOML, Markdown, Dockerfile | .json, .yaml, .toml, .md, Dockerfile |

For complete parser capabilities and framework adapters, see the Language Support Guide.

---

CLI Reference

| Command | Description | | :----------------------- | :------------------------------------------------------------------------------------ | | atlas init | Initializes .atlas/ folder and project configuration. | | atlas index | Parses ASTs, computes metrics, and updates local SQLite graph. | | atlas watch | Watches for file changes and updates the graph incrementally. | | atlas diff | Calculates semantic blast radius and risk ratings from Git diffs. | | atlas analyze | Audits Domain-Driven Design (DDD) layers, circular dependencies, and dead code. | | atlas doctor | Runs integrity checks on the SQLite database and repository health. | | atlas rules generate | Generates evidence-based guidelines (AGENTS.md, CLAUDE.md, .cursor/rules/). | | atlas context | Builds token-budgeted prompt packs tailored to intent (bug, feature, refactor). | | atlas search | Performs full-text search with synonym query expansion via SQLite FTS5. | | atlas mcp setup | Configures detected AI coding assistants to connect to CodeAtlas MCP. | | atlas mcp doctor | Tests MCP stdio handshake, protocol compatibility, and tool availability. | | atlas mcp list-targets | Lists all supported AI coding assistant targets and their detection status. | | atlas mcp | Runs the Model Context Protocol (MCP) server over stdio. |

For full CLI flags and examples, see the CLI Documentation.

---

Model Context Protocol (MCP)

CodeAtlas implements 22 native MCP tools enabling AI assistants to explore codebases autonomously:

• Topology & Graph: atlas_scan, atlas_dependencies, atlas_cycles, atlas_query, atlas_architecture
• Navigation & Search: atlas_search_symbols, atlas_get_map, atlas_trace_execution_path, atlas_find_entry_points
• Context & Optimization: atlas_get_context, atlas_get_file_context, atlas_compress, atlas_search
• Impact & Change Analysis: atlas_impact, atlas_pr_diff, atlas_calculate_change_surface
• Health & Architecture: atlas_analyze, atlas_get_god_components, atlas_get_dead_code, atlas_get_bottlenecks, atlas_suggest_refactoring
• Rules & Governance: atlas_get_rules, atlas_generate_rules, atlas_doctor, atlas_index

Manual Setup

Google Antigravity & Codex (.agents/mcp_config.json)

{
  "mcpServers": {
    "codeatlas": {
      "command": "atlas",
      "args": ["mcp"]
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "codeatlas": {
      "command": "atlas",
      "args": ["mcp"]
    }
  }
}

Claude Code CLI

claude mcp add codeatlas atlas -- mcp

For detailed MCP tool definitions, see the MCP Documentation.

---

Repository Structure

codeatlas/
├── packages/
│   ├── core/           # Data models, configuration, and secret redaction
│   ├── parser/         # Tree-sitter parsers, framework adapters, TS semantic resolver
│   ├── storage/        # SQLite persistence and FTS5 search
│   ├── graph/          # Directed graph engine, PageRank, cycle detection
│   ├── analytics/      # Architecture analysis, DDD layers, multi-repo aggregation
│   ├── rules/          # Rule generator and live DAG blueprint synchronization
│   ├── retrieval/      # Multi-source retrieval engine (FTS5 + Graph)
│   ├── compression/    # AST skeletonization and prompt token compression
│   ├── ranking/        # Relevance ranking and scoring algorithms
│   ├── context/        # Context pack assembly and token budget management
│   ├── mcp/            # Model Context Protocol serve