Code Atlas

A code intelligence graph that gives AI coding agents deep, token-efficient understanding of your codebase — structure, docs, and dependencies in one searchable graph.

Map your codebase. Search it three ways. Feed it to agents.

The Problem

Every time an AI agent touches your codebase, it burns tokens just figuring out where things are. Grep for a function name. Read five files to understand the call chain. Search docs for context. Repeat — across every task, every session. On a large project, agents can spend 30–50% of their context window on orientation before they write a single line of code.

Many tools solve one piece of this: semantic search, or graph traversal, or keyword lookup. But a developer doesn't understand a codebase through one lens — they build a mental model that connects structure, meaning, and names simultaneously. Agents need the same thing.

Code Atlas is that mental model, externalized as a graph.

What Is This?

Code Atlas builds a graph database of your entire codebase — code structure, documentation, and dependencies — and exposes it via MCP tools that AI coding agents can use to understand, navigate, and reason about your code.

Three search types, one system:

• Graph traversal — follow relationships: who calls this function? What does this class inherit from? What services depend on this library?
• Semantic search — find code by meaning: "authentication middleware" finds relevant code even if it's named verify_token_chain
• BM25 keyword search — exact matches: find that specific error message, config key, or function name

All powered by Memgraph as a single backend.

Key Features

• Monorepo-native — auto-detects sub-projects, tracks cross-project dependencies, scoped queries
• Documentation as first-class — indexes markdown docs, ADRs, and READMEs with links to the code they describe
• AST-level incremental indexing — only re-indexes the entities that actually changed, not entire files
• Pattern detection — pluggable detectors for decorator routing, event handlers, DI, test→code mappings, and more
• Library awareness — lightweight stubs for external dependencies, full indexing for internal libraries
• Self-hosted — runs locally with Docker. No data leaves your machine
• No additional API costs — agent-first design means all intelligence runs through your existing subscription; local embeddings via TEI, no extra API keys
• Token-efficient — budget-aware context assembly that prioritizes what matters most
• Pluggable AI — TEI for embeddings, LiteLLM for LLM calls, or bring your own
• MCP server — works with Claude Code, Cursor, Windsurf, or any MCP-compatible client

How Does This Compare?

Several excellent tools exist in this space — graph-based analyzers, semantic search engines, wiki generators, and IDE-integrated indexers. Code Atlas builds on their ideas while addressing a gap: no single tool combines graph traversal, semantic search, and BM25 keyword search with documentation intelligence and MCP exposure.

For a detailed comparison covering DeepWiki, Cursor, Sourcegraph Cody, Kit, code-graph-rag, codegraph-rust, and more, see wiki/landscape.md.

MCP Tools

15 tools exposed via the Model Context Protocol, designed to minimize context window overhead.

Token counts measured from MCP JSON tool definitions (tiktoken cl100k_base). Search = name + description (~966 total); Full = name + description + parameter schema with field descriptions, enums, and constraints (~2,945 total). All parameters are self-documented — agents can one-shot any tool without calling get_usage_guide first. Latency measured with local TEI embeddings on the code-atlas repo (~1,400 entities), 5 iterations, warm embedding cache. See scripts/profile_query.py.

Quick Start

Prerequisites

• Docker and Docker Compose
• uv (Python package manager)

1. Start infrastructure

Download the compose file and start Memgraph + Valkey:

curl -O https://raw.githubusercontent.com/SerPeter/code-atlas/main/docker-compose.yml
docker compose up -d

docker-compose.yml runs the MAGE-enabled memgraph/memgraph-mage image (needed for find_communities/community detection). Existing deployments on an older compose file: docker compose pull && docker compose up -d to switch over.

Optional — add local embeddings (no API keys needed):

docker compose --profile tei up -d

2. Index your project

uvx --from code-atlas-mcp atlas index /path/to/your/project
uvx --from code-atlas-mcp atlas status

3. Connect to your AI agent

Claude Code:

claude mcp add code-atlas -- uvx --from code-atlas-mcp atlas mcp

Cursor / other MCP clients — add to your MCP config:

{
  "mcpServers": {
    "code-atlas": {
      "command": "uvx",
      "args": ["--from", "code-atlas-mcp", "atlas", "mcp"]
    }
  }
}

See CLI usage guide for more commands and options.

Development

If you want to contribute or run from source:

git clone https://github.com/SerPeter/code-atlas.git
cd code-atlas
uv sync --group dev
uv run pre-commit install

Performance

Full index includes parsing, graph upserts, and embedding via local TEI (8 concurrent workers). Parse-only is raw tree-sitter CPU time without I/O. Query latencies are averages from scripts/profile_query.py. Full benchmark tables: wiki/benchmarks.md

Documentation

• Architecture — system design, pipelines, deployment model
• Landscape — code intelligence tools comparison and design rationale
• Configuration — atlas.toml, .atlasignore, environment variables
• CLI Usage — indexing, searching, daemon mode
• Benchmarks — parsing, query latency, concurrency
• Repository Guidelines — structure your code for better indexing

Supporting Code Atlas

I built Code Atlas because my AI agents kept burning half their context just figuring out where things are in larger codebases. Nothing combined the search types I needed in one place, so I built it and open-sourced it so you can benefit as well.

If Code Atlas saves you time, tokens, or makes your agents noticeably better — consider sponsoring the project.

License

Apache License 2.0