Skip to content
BranchesTags

Repository files navigation

CodeAtlas Banner

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.

VS Code Marketplace CI npm version License: MIT TypeScript Node.js

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 server (22 tools) & configurator
│   ├── git/            # Git service for commit churn and diff analysis
│   ├── llm/            # LLM provider abstractions
│   ├── shared/         # Common utilities, logger, and error types
│   ├── github-action/  # CI/CD architecture quality gate action
│   └── benchmark/      # Recall and token reduction benchmark suite
├── apps/
│   ├── cli/            # Standalone `atlas` command-line executable
│   ├── vscode-extension/# Official VS Code / Cursor extension
│   ├── webview/        # WebGL force-directed graph canvas
│   ├── docs/           # VitePress documentation portal
│   └── mcp-server/     # Standalone MCP binary runner

Benchmarks

Evaluated against open-source repositories to measure context accuracy, recall, and token reduction:

Dataset: expressjs/express (96 files, 71k raw tokens)

Task Scenario Target Ground Truth Recall Context Tokens Token Savings Latency
Routing & Dispatching lib/application.js, lib/express.js 100% 6,364 91% 26ms
Server Bootstrap (app.listen) lib/application.js, lib/express.js 50% 4,555 94% 32ms
JSON Response Serialization lib/response.js 100% 5,124 93% 56ms
Request Cookie & Header Parsing lib/request.js 100% 6,285 91% 17ms
View Engine Resolution lib/view.js, lib/application.js, lib/response.js 67% 6,344 91% 59ms
Overall Average — 83% — 92% 38ms

Benchmark run on Intel Core i5-8350U @ 3.60GHz, 16GB RAM, Node.js v22. Results reflect fixed scenario queries evaluated against golden file sets.

Documentation

Comprehensive guides and API references are available in the documentation portal:

To run the documentation portal locally:

pnpm --filter @codeatlas-ai/docs docs:dev

Local Development

# Clone repository
git clone https://github.com/shditz/codeatlas.git
cd codeatlas

# Install dependencies
pnpm install

# Build all packages and applications
pnpm build

# Run test suite
pnpm test

# Typecheck and lint
pnpm typecheck
pnpm lint

License

MIT © 2026-present CodeAtlas Contributors.

About

Local dependency graphs and context intelligence for AI coding agents.

Topics

ai-agentsclaude-codecode-intelligencecodebase-indexercontext-enginedeveloper-toolsmcp-serversqlite-fts5tree-sittertypescript

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages