Skip to main content
Glama

Your agent just opened a 216,000-line monorepo. It needs one function, its callers and the test that covers it. It should not read 30,000 tokens of files to find them.

CodeAtlas indexes a repository with tree-sitter into a symbol graph (functions, classes, references, imports, env keys, SQL tables, patterns) and exposes it over MCP as compact, path:line-anchored answers. An agent asks task_context("fix expired refresh tokens") and gets the five symbols that matter, their callers, the test that exercises them and the config they read, in ~3k tokens instead of ~30k. The index updates itself within a second of every save, and a localhost React dashboard shows the map, the SNIPE board and agent activity live.

backend/src/services/auth.ts  [typescript, 764 lines, 25 symbols]
f async function signup(db, input)                     :49-119  ←2f {async_await,closures,error_handling}
f async function login(db, input)                      :121-146 ←3f {async_await,error_handling}
f async function rotateRefreshToken(db, token, ...)    :216-254 ←2f {async_await,error_handling}
imports (repo): services/errors.ts[unauthorized], security/tokens.ts[sha256, randomToken]
imported by (6): routes/auth.ts, routes/appleWeb.ts, tests/auth-lifecycle.test.ts, ...

Install

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/5hihan/codeatlas/main/install.ps1 | iex

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/5hihan/codeatlas/main/install.sh | sh

That installs uv if needed, the codeatlas command, and registers CodeAtlas with every coding agent it finds on the machine (codeatlas init --global). Pass a platform to pick one: ... | sh -s -- codex, or install.ps1 codex. Re-run with --update / -Update to upgrade.

Then, in any repository (new or existing, empty is fine):

codeatlas init        # writes agents + guidance, idempotent; the index builds itself when your agent starts here

Platform

How

Then

Claude Code

plugin codeatlas@codeatlas installed at user scope by the installer (or claude plugin marketplace add 5hihan/codeatlas + claude plugin install codeatlas@codeatlas)

/codeatlas:find <question>, /codeatlas:snipe, /codeatlas:review-changes, or let Claude delegate to the codeatlas-navigator, codeatlas-sniper, codeatlas-reviewer agents. A PreToolUse hook makes Claude actually use the index: in an indexed repo, built-in Grep/Glob and grep/rg/find in Bash are denied with the CodeAtlas tool to call instead (CODEATLAS_GUARD=off disables, =strict also redirects whole-file Read)

Codex

mcp_servers.codeatlas in ~/.codex/config.toml + skill in ~/.agents/skills/codeatlas

type $codeatlas (Codex uses $, not /); the MCP tools are available in every project

Cursor

codeatlas init cursor writes .cursor/mcp.json in the repo

the MCP tools appear in the agent

Anything else (MCP)

codeatlas serve --repo <path> over stdio

36 tools, see below

Manual install from a checkout: uv tool install . (or pipx install .), then codeatlas doctor.

Related MCP server: codegraph-mcp

Measured: the same agent, with and without CodeAtlas

Claude Code (claude -p, Sonnet) answering the same research questions on a 785-file, 216k-line TypeScript + Kotlin + Swift monorepo, once with only Read/Grep/Glob and once with the CodeAtlas MCP server added. Numbers are Claude's own usage report, summed over every turn, averaged over two runs each.

Question

Tool calls

Files read

New tokens into context

API time

Cost

where is the refresh token rotated on resume, which test covers it

without

17.5

3.0

65,678

61 s

$0.187

with CodeAtlas

5.0

0.5

27,566

26 s

$0.125

what breaks if a session-revocation function changes signature; callers + tests

without

26.0

7.5

90,835

90 s

$0.267

with CodeAtlas

15.0

4.5

91,632

70 s

$0.220

which env vars the relay/media-budget code reads, and where they are declared

without

8.5

3.5

64,672

51 s

$0.174

with CodeAtlas

7.5

0.0

57,334

24 s

$0.177

Answers were checked against the source; both arms reached the right functions and lines. With CodeAtlas the agent made 2-3× fewer tool calls, opened almost no whole files, and answered roughly twice as fast; new context dropped by 58% on the first task and was flat on the impact task, where the agent still opened the four files it wanted to quote. Three further questions on a 101k-line web app were grep-shaped ("list every place X is called"); there the agent answered with Grep alone in both arms and nothing changed. CodeAtlas pays off when a question needs relationships (callers, impact, config, "what triggers what"), not when a single grep suffices.

Context cost per task, estimated over six codebases

Six projects, one representative task each. "Without" is the tokens of the whole files an agent would open to answer it; "with" is the task_context answer (symbols, source of the strongest ones, callers, tests, config).

Codebase

Files

Lines

Symbols

Full index

Save → index

Task

Without

With CodeAtlas

Saved

TS + Kotlin + Swift monorepo

785

216,013

8,520

13.8 s

23 ms

fix refresh-token rotation

28,508

2,899

9.8×

TS/TSX web app + API

432

101,146

3,049

5.7 s

22 ms

fix async error handling in checkout

55,377

2,955

18.7×

Python + TS client library

52

13,972

889

0.7 s

18 ms

how the client fetches and caches

26,197

2,915

9.0×

TSX admin app

119

16,643

697

0.8 s

12 ms

where orders are created

5,953

2,882

2.1×

JavaScript service

94

8,261

256

0.4 s

17 ms

how cards render, GET route

6,241

3,579

1.7×

Python library

29

3,138

115

0.3 s

17 ms

how the mesh is built

3,379

2,275

1.5×

The saving grows with the codebase: small projects fit in context anyway, large ones do not. Query latency is below 40 ms at p95 for symbol, references and impact, and a no-op freshness check costs under 10 ms on the small codebases and ~100 ms on the 216k-line monorepo. Measured on a Windows 11 desktop (Intel Core Ultra 7, 32 GB RAM, SSD).

Accuracy checks that shaped the resolver: this.x() callers stay inside their class in 97% of synthetic cases, callers never cross language or package boundaries, and generic member names (.size, .push) are never attributed to an unrelated repository symbol.

What it does

Navigation without reading files

Tool

Gives the agent

task_context

start here: the symbols relevant to a task (BM25 + PageRank + graph proximity + pattern hints), source for the strongest ones, tests, config/docs, inside an adaptive token budget; each item says why it is there and how to expand it

repo_overview, repo_map

languages, packages, hubs, entry points; the complete symbol map, files ordered by PageRank (pass token_budget to get only the top-ranked part)

file_outline, find_symbols, symbol, symbol_source

outlines with reference counts and pattern tags; signature, doc, callers, callees; just the lines of one symbol

references, impact, triggers, dependencies, module_graph

who uses it, what breaks, what makes it run, import graphs

relationships

code ↔ config ↔ schema: env keys read and declared, SQL tables declared and used, literal config paths

programming_patterns

12 patterns (generics, closures, decorators, async, generators, error handling, ...) at real locations with evidence

change_context

git blast radius: changed symbols, consumers to re-check, config/schema touched, tests to run, risk

hotspots, unreferenced, findings, grep

complexity, dead code, comment tags, regex search

Precise editing. replace_symbol, insert_code, rename_symbol work on syntax-tree spans: neighbours on the same line survive, the new file is parsed before it is written, a content hash guards against concurrent edits, and rename touches identifiers only, never strings or comments.

Resolution you can trust. Every graph tool shares one resolver: import aliases are followed, this.x() binds to the enclosing class, Foo.x() to Foo, then same file → imported files → unique definition in the same package and language. Edges carry a confidence; ambiguous ones are reported, not guessed. Results say when they were truncated and which index version they came from.

SNIPE: the fix loop

No sprints, no tickets, no audits. Every save and every reported failure becomes a tiny scored issue; the agent takes the highest-confidence, lowest-context one and fixes it with the smallest patch that can be verified.

next_snipe  →  claim_snipe(id)  →  get_snipe_context(id, level)  →  patch  →  verify_snipe(id)  →  next
  • Scan is event-driven: removed-but-still-referenced symbols, broken imports, syntax errors and new FIXMEs become issues on the next save; snipe_report turns test/typecheck/lint output (node, jest, vitest, pytest, go, cargo) into issues; static findings stay dormant as opportunities.

  • Narrow reduces an issue to a few symbols: seeds from stack traces, named symbols and the failing test, callee chains, their intersection, bounded to the evidence's package and language.

  • Infer ranks candidates with confidence, evidence and counter-evidence.

  • Patch is the agent's job, on the smallest surface. Context is lazy: level 1 names, 2 signatures, 3 bodies, 4 callers, 5 file, 6 subsystem.

  • Evaluate is a cone: parse + dead-reference check + targeted tests, then the callers' tests, the full suite only when the risk justifies it. Over 6 symbols or 3 files changed → the snipe is aborted and promoted to INVESTIGATE. Test commands are auto-detected per package.

SNIPE.md in the repo mirrors the board; the dashboard shows READY TO SNIPE, INVESTIGATING and CURRENT (per agent) live. Score = √(confidence × impact × reproducibility × isolation) ÷ √(context cost × blast radius).

Dashboard

codeatlas serve (what agents run) also starts a React dashboard on http://127.0.0.1:8765 (codeatlas open): overview, repo map with budget slider, symbol explorer, file outlines, hotspots, module graph, relationships, patterns, findings, the SNIPE board and a live feed of every tool call and index update, pushed over Server-Sent Events. One dashboard per repo is shared by concurrent agent sessions.

Languages

Python, JavaScript, TypeScript, TSX, Go, Rust, Java, Kotlin, Swift, C, C++, C#, Ruby, PHP, Scala, Lua, Bash. Grammars ship with tree-sitter-language-pack; nothing to compile. Config and schema files: .env, JSON, YAML, TOML, INI, SQL, Prisma, GraphQL, protobuf.

CLI

codeatlas init [claude|codex|cursor|all|auto] [--global]   set up a repo, or the whole machine once
codeatlas serve [--repo PATH] [--profile nav|edit|snipe|all]  MCP server + watcher + dashboard
codeatlas context "<task>" | changes [--base REF] | map | overview | outline PATH | symbol NAME | impact NAME
codeatlas snipe [board|scan [--run tests]|next|report FILE]  the loop from the shell
codeatlas plugin export DIR | dashboard --open | open | doctor
codeatlas hook pretool [--prefix P] [--mode default|search|off]   Claude Code PreToolUse guard (shipped in the plugin)

The guard: advice becomes a rule

Telling the model to "use CodeAtlas" in CLAUDE.md is not enough: the built-in Grep, Glob, Read and Edit schemas are always loaded while MCP tools are deferred, so the model reaches for them by default. The plugin ships a PreToolUse hook that, in a repository with a .codeatlas/index.db and only for files the index knows, denies the built-in call and names the CodeAtlas call to make instead, so the model recovers in the same turn:

Built-in call

Redirected to

Grep, Glob, grep/rg/find in any Bash statement

grep, find_symbols, references, list_files

whole-file Read, cat through Bash

file_outline, then symbol_source for the declarations needed

Edit whose old_string lies inside a declaration (up to 150 lines)

replace_symbol("<the enclosing symbol>", ...), insert_code

Write over an existing source file, sed -i, >, tee, inline scripts that write

replace_symbol / insert_code (Write is for new files)

any command that sets CODEATLAS_GUARD

denied: the switch is the user's, not the model's

Two details decide whether the guard holds. Every statement is inspected, so export X=1; cd src; A=$(find . -name y); sed -n 1,50p $A | grep -v '^//' does not hide its search behind a chain, and a cd carries into $(...). No deny message names the off switch, so the model cannot talk itself out of the guard.

What the index does not cover is never gated: unindexed files, docs and config, bounded partial reads (an offset with a limit of 250 lines or fewer), edits outside declarations, and anything in a directory outside the indexed repository, such as a reference checkout you are reading upstream logic from. That last one matters: CodeAtlas has no index there, so a denial would leave no working tool. CODEATLAS_GUARD=search keeps only the search redirects and CODEATLAS_GUARD=off disables the guard, both set by you in your own environment.

Only project folders get indexed

CodeAtlas refuses to index anything that is not a project: your home directory, the user folders inside it (Desktop, Documents, Downloads, AppData, OneDrive, ...), drive / filesystem roots and system directories (Windows, Program Files, /usr, /Applications, ...). Projects inside those folders are fine (~/Desktop/my-app). codeatlas init, codeatlas serve and the library all enforce it, and the Claude Code guard ignores a stray index at such a location. CODEATLAS_ALLOW_ANY_ROOT=1 overrides it deliberately.

How it stays fast on large repos

  • One tree-sitter walk per changed file collects definitions, calls, identifier uses, tokens, complexity and patterns; references to new names are found through a token index, never by re-reading files.

  • Incremental everything: a save re-parses one file; PageRank, FTS and relationship inventories refresh lazily and are throttled on no-op checks.

  • Budgets adapt to repository size, scope, candidate count and risk terms; every response is bounded and says so.

Development

uv sync && uv run pytest          # 200+ tests, fixture repos in several languages
cd dashboard && npm install && npm run dev   # React dashboard against a running `codeatlas serve`

MIT License.

Available Tools

38 tools
change_contextA

Git diff blast radius: changed/removed symbols, transitive consumers, config/schema dependencies, and candidate tests with evidence. comparison: working (includes staged), staged, or branch (HEAD). merge_base=True compares a feature branch against its common ancestor with base_ref. Reports caps, uncertainty and index versions; automatic budgets adapt to change risk and fanout. Set token_budget to override. Does not run tests or modify Git.

Inputs: depth, base_ref, max_files, comparison, +4 more. Returns: result

claim_snipeB

Take ownership of an issue (state FIXING) and snapshot its files so verify_snipe can measure the patch surface. Returns level-1 context (symbol names + ranked candidates).

Inputs: id (required), agent. Returns: result

dependenciesC

File-level imports (resolved to repo files), external packages, importers and transitive dependents.

Inputs: path (required). Returns: result

file_outlineA

Tree of classes/functions/methods in a file with line ranges, signatures, reference counts, imports and importers. Read this instead of the file.

Inputs: path (required), show_imports, include_private. Returns: result

findingsB

Static findings from the index: TAG_TODO/TAG_FIXME/TAG_BUG comment tags, EMPTY_CATCH, SWALLOWED_EXCEPTION, BARE_EXCEPT. Filter by code prefix or path.

Inputs: code, path, limit. Returns: result

find_symbolsB

Find definitions by name (exact, prefix, substring, then fuzzy CamelCase words). kind filters by function|method|class|interface|type|enum|struct|module. path filters by path substring.

Inputs: query (required), kind, path, limit. Returns: result

get_snipe_contextA

Lazy context for an issue. Climb only as high as needed: 0 summary, 1 symbol names + candidates with evidence/counter-evidence, 2 signatures, 3 implementation bodies of suspect + related, 4 callers and dependencies, 5 the full suspect file, 6 subsystem context (task_context).

Inputs: id (required), level. Returns: result

grepA

Regex search over indexed source files (smart case). glob like '.ts' or 'backend/'. Use for strings, config keys and dynamic names the symbol index cannot see.

Inputs: pattern (required), glob, limit. Returns: result

hotspotsC

Most complex and longest functions, largest files, key symbols by PageRank, import cycles.

Inputs: limit. Returns: result

impactA

Blast radius: transitive callers of a symbol up to depth hops, affected files and tests. Run before changing a signature or behaviour.

Inputs: name (required), path, depth. Returns: result

index_repoA

Force a re-scan of the repository. The index already auto-updates on file changes; use full=True after changing .gitignore or if results look stale.

Inputs: full. Returns: result

index_statusA

Index health: file/symbol counts, watcher state, dashboard URL, last update time.

Inputs: no named parameters. Returns: result

insert_codeB

Insert new_text on its own lines before or after an existing symbol (where='before'|'after'), matching its indentation. Parse-validated before writing.

Inputs: name (required), new_text (required), path, force, +2 more. Returns: result

list_filesB

List indexed source files under a path prefix with language, line and symbol counts.

Inputs: limit, prefix. Returns: result

module_graphC

Directory-level import graph (which modules depend on which), aggregated at the given path depth.

Inputs: depth, min_edges. Returns: result

next_snipeA

The highest-value isolated issue to fix next (your own in-progress snipe first). Returns the problem, evidence, suspect symbol with confidence, related symbols, context cost, risk and the verification tests. Pass agent="" so several agents never pick the same item.

Inputs: agent. Returns: result

programming_patternsB

Explain 12 programming patterns at actual source locations, with syntax evidence and confidence. Filter by file/path and pattern ID; catalogue=True lists the supported concepts without source scans.

Inputs: path, limit, offset, pattern, +2 more. Returns: result

referencesA

Every place a name is used, grouped by file with line numbers and enclosing symbol. When path (or a qualified name) pins one definition, only references resolving to it are listed. Reports the true total, how many are shown, and a next offset for continuation. kind: call | new | arg | ref | import.

Inputs: name (required), kind, path, limit, +2 more. Returns: result

relationshipsB

Evidence-backed code/config/schema dependencies. source consumes target; direction=in finds consumers of path, out finds dependencies. Includes unresolved local targets and pagination.

Inputs: kind, path, limit, offset, +2 more. Returns: result

rename_symbolA

Rename a symbol at its definition and every reference that resolves to it (identifier nodes only: strings, comments and same-named symbols elsewhere are untouched; ambiguous references are listed and skipped). Defaults to dry_run=True: review the plan, then call again with dry_run=False.

Inputs: name (required), new_name (required), path, dry_run, +1 more. Returns: result

replace_symbolA

Replace exactly one declaration (its syntax-tree span incl. decorators/export) with new_text, re-indented. Neighbours on the same line are untouched. The new file is parsed first and refused if it adds syntax errors (force=True overrides). Pass expected_hash (old_hash from a previous call) to guard against concurrent changes. Returns old text + hashes; re-indexes immediately. dry_run previews.

Inputs: name (required), new_text (required), path, force, +2 more. Returns: result

repo_mapA

Complete map of the repository: every file with its symbols (classes with their methods, functions with signatures), files ordered by PageRank. Nothing is cut unless token_budget is given, in which case only the top-ranked files/symbols that fit are shown. focus_paths/focus_names bias the ranking toward what you are working on. Use it instead of listing or reading files.

Inputs: focus_names, focus_paths, token_budget, exported_only. Returns: result

repo_overviewA

Start here: languages, top directories, hub files, entry points, key symbols, finding counts (~400 tokens).

Inputs: no named parameters. Returns: result

snipe_abortC

Stop condition: the fix stopped being a snipe (schema migration, public API change, many modules). Marks it BLOCKED / INVESTIGATE with the reason so nobody wanders for 40 minutes.

Inputs: id (required), reason (required). Returns: result

snipe_addB

Record a concrete defect (kind=issue) or a dormant improvement (kind=opportunity). Give evidence as 'path:line' or symbol names so NARROW can find the suspect. Do not fix drive-by findings; log them.

Inputs: problem (required), kind, suspect, evidence, +1 more. Returns: result

snipe_boardC

Ready-to-snipe list (score, symbols, tokens, risk), investigating, current work per agent, counts.

Inputs: no named parameters. Returns: result

snipe_configC

Configure verification. test_cmd is a template with {file} (e.g. 'npx vitest run {file}', 'python -m pytest {file} -q'); auto-detected from package.json/pyproject when unset. Stop-condition limits too.

Inputs: lint_cmd, test_cmd, test_timeout, full_test_cmd, +3 more. Returns: result

snipe_itemC

Full record of one issue/opportunity: evidence, candidates, factors, notes.

Inputs: id (required). Returns: result

snipe_listC

List records. kind: issue | opportunity. state: comma list of FOUND,TARGETED,FIXING,VERIFYING,DONE,BLOCKED. priority: 'SNIPE NOW' | INVESTIGATE | DEFER | IGNORE.

Inputs: kind, limit, state, priority. Returns: result

snipe_reportB

Feed external evidence: paste failing test / typecheck / lint / runtime output. Each failing test or distinct location becomes an issue, narrowed to a suspect symbol. source: test | typecheck | lint | runtime.

Inputs: text (required), source. Returns: result

snipe_scanA

Scan for concrete problems. Without run: cheap static pass (unresolved relative imports become issues; complexity/cycles/swallowed errors become dormant opportunities). run='tests'|'typecheck'|'lint' also runs the configured command and turns failures into issues. Index deltas are scanned automatically on every save.

Inputs: run. Returns: result

snipe_updateC

Change state (FOUND|TARGETED|FIXING|VERIFYING|DONE|BLOCKED), priority, suspect or kind; add a note.

Inputs: id (required), kind, note, agent, +3 more. Returns: result

symbolA

Everything about one symbol: location, signature, doc, complexity, members, callers, callees. name may be plain (foo), qualified (Class.foo) or path:line. Use path= to disambiguate.

Inputs: name (required), path. Returns: result

symbol_sourceC

Source text of one symbol (or path:start-end range) with line numbers. Cheaper than reading the file.

Inputs: target (required), path, context, max_lines. Returns: result

task_contextA

One call to start a task: the symbols relevant to the task text (BM25 over names/signatures/docs, boosted by PageRank and graph proximity), with source for the strongest ones, plus tests and config/docs that mention the terms. scope limits to a path prefix (e.g. "backend/src/services"). Always fits an adaptive budget by default (set token_budget to override); each item carries a 'why' and an expand handle. Reports truncation and index version.

Inputs: task (required), scope, max_symbols, token_budget, +1 more. Returns: result

triggersB

What causes a symbol to run: route/event decorators, callback registrations (addEventListener, app.get, subscribe...), direct callers, owning class. Answers 'what triggers what'.

Inputs: name (required), path. Returns: result

unreferencedB

Dead-code candidates: functions/classes with no references anywhere. Verify with triggers/grep before deleting.

Inputs: limit, include_exported. Returns: result

verify_snipeB

Evaluate outward from what you changed: level 1 parse check + dead-reference check + targeted tests; level 2 tests of callers (only if level 1 passed); level 3 full suite only when deep=True or risk is high. PASS -> DONE, FAIL -> back to FIXING with the failure as evidence, blast radius over the limit -> SNIPE ABORTED (promoted to INVESTIGATE).

Inputs: id (required), deep. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 38 tools

    Disambiguation4/5

    Tools generally have distinct purposes, with clear guidance for high-level entry points (repo_overview, repo_map, task_context, change_context) and separate refactoring/snipe workflows. However, several retrieval tools overlap in scope (symbol vs find_symbols vs symbol_source, relationships vs dependencies vs module_graph), so an agent may still need to study descriptions carefully.

    Naming Consistency3/5

    Names are all snake_case, but conventions are mixed: many are bare nouns (symbol, references, impact, findings) while others use verb_noun (find_symbols, replace_symbol, verify_snipe), and one uses get_ (get_snipe_context). The pattern is readable but not consistently predictable.

    Tool Count2/5

    38 tools is far above the ideal 3–15 range and qualifies as too many for a single MCP server. While the domain is complex, many snipe and context tools could be consolidated or hidden behind higher-level operations.

    Completeness4/5

    Coverage is broad: indexing, repo/symbol exploration, dependency analysis, refactoring, grep, static findings, and a full issue-triage/verification workflow. Minor gaps remain (e.g., no explicit symbol deletion/move or multi-symbol refactor), but agents can work around them with replace_symbol/insert_code.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
      19 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a codebase's symbol graph and symbol-aware editing tools to AI agents, enabling targeted symbol lookup, impact analysis, and atomic multi-file edits with reduced context tokens.
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to pull focused, token-bounded context from a local structural code graph stored in SQLite, so they can locate relevant code, traverse relationships between entities, and carry recorded mistakes into later sessions instead of reading whole files. It also supports serving that context over an authenticated local HTTP dashboard.
      24 npm
      MIT