CodeAtlas
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CodeAtlas Where is the refresh token rotated on resume and which test covers it?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | iexmacOS / Linux
curl -fsSL https://raw.githubusercontent.com/5hihan/codeatlas/main/install.sh | shThat 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 herePlatform | How | Then |
Claude Code | plugin |
|
Codex |
| type |
Cursor |
| the MCP tools appear in the agent |
Anything else (MCP) |
| 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 |
| 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 |
| languages, packages, hubs, entry points; the complete symbol map, files ordered by PageRank (pass |
| outlines with reference counts and pattern tags; signature, doc, callers, callees; just the lines of one symbol |
| who uses it, what breaks, what makes it run, import graphs |
| code ↔ config ↔ schema: env keys read and declared, SQL tables declared and used, literal config paths |
| 12 patterns (generics, closures, decorators, async, generators, error handling, ...) at real locations with evidence |
| git blast radius: changed symbols, consumers to re-check, config/schema touched, tests to run, risk |
| 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) → nextScan is event-driven: removed-but-still-referenced symbols, broken imports, syntax errors and new
FIXMEs become issues on the next save;snipe_reportturns 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, |
|
whole-file Read, |
|
Edit whose old_string lies inside a declaration (up to 150 lines) |
|
Write over an existing source file, |
|
any command that sets | 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 toolschange_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
Scored across 38 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 PyPI4MIT
- FlicenseNot gradedqualityBmaintenanceProvides efficient code navigation and graph-based analysis for AI agents, enabling symbol resolution, callers, implementations, and type schemas with minimal token usage.-
- AlicenseNot gradedqualityBmaintenanceExposes 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT