CodeAtlas gives coding agents structured intelligence about a repository: symbols,
calls, imports, execution paths, and change impact. It runs locally, builds a
lightweight graph and lexical index, and exposes the result through MCP and the
CLI.
Understand structure and blast radius before making a change—without requiring a
model download.
A local-first code-intelligence engine with optional AI.
2026-10-28
星數
—
工具
—
可用率
—
Quick start
npm install -g @showdar2112/code-atlas
cd my-project
code-atlas init
code-atlas connect
init creates the local .codeatlas/ state, scans the repository, builds the
graph and lexical indexes, and refreshes the managed AGENTS.md guidance block.
connect detects supported coding-agent installations and opens a selector in
an interactive terminal.
The normal onboarding path needs no model runtime. To bootstrap without indexing
and build the indexes later, use the advanced opt-out:
code-atlas init --no-index
code-atlas index
The selector is illustrative—an agent appears enabled only when CodeAtlas can
detect it in the current environment:
Connect CodeAtlas
Select integrations:
❯ ◯ Codex
◯ OpenCode
◯ Claude Code
◯ Gemini CLI
◯ Cursor
◯ Cline
◯ Windsurf
◯ Zoo Code
Space toggle · A select all detected · Enter confirm · Esc cancel
For scripts and CI, use an explicit integration or --all:
CodeAtlas separates context selection from context delivery. The current stack
works as follows:
Context-aware delivery (Phase15A): decides how much source/context to
deliver for an explicit file or symbol request. context_read remains the
explicit delivery surface.
Task context compilation (Phase15B): decides which files and symbols are
worth reading. It produces a bounded, deterministic, evidence-backed plan;
it does not return source bodies directly.
Durable task context (Phase15C): gives a task context an explicit
taskContextId and durable start, refresh, and close lifecycle. The
lifecycle keeps its session and context-generation identities and reports
delivery metrics such as full, unchanged, delta, and rehydrated results when
those modes apply.
Compile a bounded task-context plan with the CLI:
code-atlas context-compile --task "Fix repository status handling"
code-atlas context-compile --task "Fix repository status handling" --json
The same capability is available through the MCP compile_task_context tool.
The durable lifecycle is available through the CLI commands
context-start, context-refresh, and context-close, and through the MCP
tools start_task_context, refresh_task_context, and close_task_context.
Each lifecycle is isolated by repository and workspace identity. Use
--ttl <seconds> on context-start to set expiry; stale concurrent refreshes
are rejected.
The compiled plan returns file/symbol references and evidence metadata, not
source bodies; context_read remains the explicit delivery step.
Internal context evaluation gate
Phase15D is an internal contributor and release-verification gate for the
Phase15A/B/C context behavior. It is not a new runtime intelligence feature
and is not a public code-atlas eval command.
Run the deterministic, offline evaluator with:
pnpm run eval:context
It uses reviewed synthetic fixtures covering the 12 production languages in
the language registry and frozen real-world snapshots. The gate checks
selection and delivery correctness, exact reconstruction, deterministic
selection/ranking, authority and explicit incomplete-evidence diagnostics,
durable lifecycle behavior, and reviewed quality-regression policy. It emits
human-readable output and a machine-readable report under the transient
artifacts/ directory. It uses no LLM judge, network access, or runtime
corpus download.
Correctness and determinism failures are hard failures. Incomplete evidence
must remain explicit rather than being treated as authoritative negative
evidence. Versioned golden baselines provide catastrophic per-case regression
protection and aggregate quality limits; performance observations are
non-blocking and are not semantic equality criteria.
Synthetic fixtures provide controlled cross-language coverage. Frozen snapshots
provide realistic repository cases with tracked provenance and license-notice
metadata. The evaluator protects corpus truth from accidental mutation; these
snapshots are evaluation inputs, not third-party source shipped as runtime
content.
Why CodeAtlas
Understand before editing
Find symbols, callers, callees, dependencies, and bounded execution paths before
changing unfamiliar code.
Know the blast radius
Impact analysis follows structural dependencies so shared changes can be checked
before they spread through a repository.
Built for coding agents
Use MCP, generated repository guidance, direct CLI workflows, and automatic
configuration for supported coding agents.
Local-first and lightweight
The useful default is graph intelligence plus lexical search. CodeAtlas does not
require model downloads, Transformers, a local LLM, Python, Docker, a GPU, or a
remote indexing service.
Honest confidence
Incomplete graph evidence is surfaced explicitly. CodeAtlas does not turn an
uncertain negative result into a confident claim.
Change intelligence
inspect-change maps the current Git diff to changed and affected symbols. The
result reports risk and evidence quality, so incomplete graph coverage remains
visible instead of becoming a confident guess. Use impact for a focused
dependency walk and affected-tests to find structural test evidence and gaps.
Core capabilities
Capability
What it gives an agent
Code search
Fast lexical search across indexed source and symbols
Symbol lookup
Definitions, locations, types, and qualified names
Call graph
Callers and callees for a resolved symbol
Import graph
Imports and reverse-import relationships
Impact analysis
Direct and transitive affected symbols
Trace
Bounded paths through repository relationships
Incremental sync
Refresh changed, added, and deleted files
Repository status
Readiness, freshness, counts, and recovery hints
Git hooks
Optional post-commit and post-checkout refresh
MCP
The same local intelligence for coding-agent workflows
Optional semantic retrieval
Graph and lexical indexing remain the default. To add semantic retrieval with
the built-in local embedding model:
code-atlas semantic setup --provider builtin-local
code-atlas semantic test
code-atlas semantic status
An OpenAI-compatible embedding endpoint can also be configured without storing
the API key in repository configuration:
The lifecycle also provides semantic upgrade, semantic disable, and
semantic clean. Disable turns off semantic retrieval while retaining its
configuration and vectors; clean removes only the repository's semantic index.
Semantic providers are optional: disabled, unavailable, stale, or failed
semantic retrieval falls back to lexical search, and semantic failures do not
prevent graph or lexical indexing from being published.
MCP search_code supports mode: "hybrid" to combine lexical and semantic
results. inspect_retrieval with includeSemantic: true exposes vector,
lexical, fused, and optional reranked stages. Compact and full details preserve
the same stage order; a candidate appearing in multiple stages remains visible
in each stage.
During TypeScript/JavaScript indexing, CodeAtlas uses scip-typescript for
additive cross-file binding evidence when its CLI is already available in the
project or on PATH. It does not install the tool or invoke npx; if the tool
is unavailable or fails, parser-based graph and lexical indexing continues.
Parser facts remain the syntax baseline, while SCIP improves target binding
where its evidence is unambiguous.
Lexical relevance now uses owner-qualified names when parser facts identify a
class or member owner. Bare identifier queries remain ambiguity-safe, and
deterministic ordering is not treated as relevance evidence.
Agent integrations
CodeAtlas currently supports eight first-class integrations:
Compile bounded evidence, deliver a selected file, and manage its lifecycle
Find callers
find_callers
Assess who depends on a symbol
Find callees
find_callees
Follow what a symbol invokes
Find imports
find_imports
Inspect module dependencies
Find reverse imports
find_imported_by
Find modules depending on a file
Assess impact
impact
Estimate direct and transitive blast radius
Inspect changes
inspect_change
Map Git changes to changed symbols and structural impact
Find affected tests
affected_tests
Select structural test evidence and identify test gaps
Explain incomplete evidence
explain_incomplete
Explain coverage gaps and direct-verification targets
Compare structural changes
graph_delta
Compare structural relationships before and after Git changes
Detect architecture drift
architecture_drift
Detect introduced/resolved policy violations and import cycles
Evaluate change policy
change_gate
Evaluate a Git change against deterministic repository policy
Trace a path
trace
Follow a bounded relationship path
Inspect retrieval
inspect_retrieval
Understand search and context stages
MCP tools/list publishes a description and input schema for each tool. The
descriptions guide tool choice: use search_code for matching-code lookup,
get_symbol when the symbol is known, compile_task_context to assemble bounded
task evidence, and context_read to deliver a selected file. Schemas
include field guidance and constraints. Each tool also publishes the standard
readOnlyHint, destructiveHint, idempotentHint, and openWorldHint
annotations. These are hints for MCP clients, not access controls. Current tool
handlers work with local repositories and state and make no network calls.
Optional MCP response controls (CA-01)
Calls without response keep their existing behavior, including each tool's
existing detail: "compact" | "full" defaults and safety caps. To reduce navigation
output, opt in on search_code, get_symbol, find_callers, find_callees,
find_imports, find_imported_by, impact, trace, execution_flow,
inspect_retrieval, get_community, list_communities, important_symbols,
architectural_bridges, find_cycles, repository_map, list_entries, or
message_links:
compact omits source/provenance and retains relationship identity; focused
keeps source prefixes up to 600 UTF-16 units and provenance; full keeps the
existing full handler depth. Existing upstream result/source caps still apply.
Focused and compact omit repeated retrieval stage/context representations.
inspect_retrieval exposes its primary fused ranking as results when stages
is omitted; selecting stages retains the existing stage field names. Explicit
source inclusion in compact mode uses prefixes up to 160 UTF-16 units.
Use context_read to deliver source and get_symbol to resolve indexed identity.
response option
Contract
mode
Required: compact, focused, or full
sections
Optional explicit selection of source, relationships, provenance, stages; [] omits these sections. Unselected evidence is intentional omission, not evidence that it does not exist.
relationKinds
Optional array of calls, imports, extends, implements, references, contains; filters returned relation records, not traversal or ranking.
maxOutputBytes
512–1,000,000; default 64,000. Bounds UTF-8 bytes of the complete successful MCP CallToolResult, including both text and structuredContent. JSON-RPC framing is excluded.
maxOutputTokens
128–250,000; approximate allowance of 4 bytes per requested token, combined with the byte limit using the smaller allowance. Not an exact tokenizer/model guarantee.
pageSize
1–100; default 100 per top-level collection. Existing limit still bounds retrieval, at most 1,000 where supported.
cursor
Opaque continuation from output.nextCursor; repeat the same tool, arguments and response options, adding only this field.
output.hasMore and remainingItems describe pagination of the retrieved window,
not all matches in the repository. projectionComplete describes projection
of that window, not graph completeness. truncated, omittedFields,
filteredRelations, and the original mayBeIncomplete/reliability evidence
distinguish reduced output from missing index coverage. Source prefixes are not
whole symbols; original line ranges identify the complete symbol. Full mode can
still require continuation when a byte/page budget applies.
Cursors preserve returned ordering, bind query/filter/options/result snapshot and
active index generation, expire after 15 minutes, and become invalid on server
restart. Repeating a cursor is safe. Index changes during retrieval fail closed;
incremental publication invalidates old cursors. Restart without cursor on
invalid_cursor, expired_cursor, or stale_cursor. There is no persistent
per-client pagination state. Pagination applies to top-level collections; a
nested object remains one whole item. output_budget_too_small means essential
metadata or the next whole item cannot fit: increase the byte budget, choose
compact, or use the legacy detailed call. No JSON or UTF-8 sequence is sliced.
Unknown controls are rejected by the existing strict-schema policy.
The adapter projects before MCP serialization. Shared retrieval still hydrates
SQLite source rows; it does not change lexical/hybrid ranking, embeddings, graph
resolution, or context-delivery receipts. Small/empty results can grow due to
explicit projection metadata; use legacy calls when reduction is unnecessary.
Workspace, durable task-context and change-policy tools retain their existing
independent contracts. See CA-01 qualification and reproducible evidence.
Trustworthy evidence
Graph readiness is not the same as graph completeness.
mayBeIncomplete=true means the available graph evidence does not cover a query
confidently enough for an authoritative negative conclusion. risk=unknown means
CodeAtlas cannot safely classify a change from that incomplete evidence.
In particular:
No callers found + mayBeIncomplete=true ≠ no callers exist
CodeAtlas does not infer architecture from folders. With an optional tracked
codeatlas.config.json, architecture_drift compares baseline and target
relationships, reports newly introduced or resolved dependency-policy violations,
and detects newly introduced import cycles even without policy configuration. The
analysis versions the policy with the Git source being inspected, so findings can
be attributed to code_change, policy_change, or both; formatting and
presentation-only policy edits do not create drift.
Groups use repository-relative include/exclude globs. Ambiguous membership is
reported as incomplete evidence rather than resolved by rule order.
An optional gate section turns the same structured evidence into deterministic
CI policy. Gate policy is always read from the repository-root codeatlas.config.json
so a change cannot select another policy file to bypass the committed Gate. For example:
{ "gate": { "risk": { "maxAllowed": "medium" } } }.
Gate evaluates the trusted baseline policy first; a newly added policy is checked
as a target bootstrap, so a change cannot weaken its own enforcement.
When coverage is incomplete, agents are guided to verify important negative
findings directly in the source. This keeps CodeAtlas useful without pretending
that a partial index is complete.
For test intelligence, “no indexed structural test evidence” means no indexed
relationship was found; it does not prove that no test exists.
Agent reporting
Generated AGENTS.md guidance teaches supported coding agents to report material
CodeAtlas findings, limitations, and fallbacks concisely.
Successful analysis might be summarized as:
CodeAtlas impact analysis identified 5 affected symbols across 3 files.
When the index is unavailable:
CodeAtlas impact analysis was unavailable because the repository was not indexed;
direct source inspection was used instead.
The graph and lexical indexes are shared core services. CLI, MCP, UI, and agent
integration workflows consume those services rather than maintaining separate
analysis paths.
Repository status / reliability
status shows the repository path, indexed counts, capability readiness, and
optional services that are not configured. It is the quickest way to check
whether a result is ready to trust before asking for deeper analysis.
Affected tests
affected-tests uses indexed structural evidence to identify tests connected to
changed production symbols. It also calls out potential test gaps when the
available graph evidence is incomplete.
CLI reference
Run code-atlas --help for the live command surface.
Updates are opt-in. Ordinary commands do not check the registry.
code-atlas upgrade --check performs a read-only version check; add --json for
stable fields: currentVersion, latestVersion, updateAvailable, manager,
upgraded, and verifiedVersion. manager is null when no unique supported
global install is found. code-atlas upgrade installs an available update, and
successful code-atlas upgrade --json runs return the same fields.
Automatic updates support unambiguous global npm/pnpm installations on POSIX and
Windows. Windows invokes known JavaScript entrypoints through Node or standalone
executables, without a shell or .cmd shims. CodeAtlas installs the exact registry
version and runs the installed CLI to verify it.
Homebrew installations from caongocquy/showdar use the CodeAtlas formula instead
of npm. Check-only mode reads the current local formula metadata without running
brew update; run that command separately to refresh it. An explicit upgrade
runs brew update, upgrades only the CodeAtlas formula, and verifies the installed
CLI with its bundled Node runtime. Local, linked, portable archive, other-tap,
wrapper-based, or ambiguous installations still fail closed without an automatic
install; check-only mode can check npm when a supported npm entrypoint is available.
Common workflows:
# Initialize and index a repository
code-atlas init
# Refresh changed files
code-atlas sync
# Rebuild the full graph and lexical indexes
code-atlas index
# Inspect readiness and freshness
code-atlas status
# Start the MCP server over stdio
code-atlas mcp
# Start the HTTP adapter for a repository
code-atlas serve [path]
The HTTP Inspector binds to 127.0.0.1 by default. Remote binding requires an
explicit CODE_ATLAS_HTTP_HOST (for example, 0.0.0.0) and a comma-separated
CODE_ATLAS_HTTP_ALLOWED_HOSTS allowlist. Requests with other Host values or a
cross-origin Origin are rejected; /api/source only reads indexed, non-ignored
source files.
Repository lifecycle
First time code-atlas init
After changes code-atlas sync
Full rebuild code-atlas index
Check readiness code-atlas status
Optional Git hooks can keep the local state refreshed after commits and
checkouts:
The Inspector check launches the actual stdio server and verifies protocol
initialization, tools/list, and tool calls. MCP Inspector is pinned to 2.7.0.
Its verifier skips on Node versions below 22.19; CodeAtlas itself still supports
Node.js 22 and newer. The full contributor test suite is pnpm test above.
The evaluation baseline is updated only as an explicit reviewed maintenance
operation, after correctness and determinism are verified:
pnpm run eval:context:update-baseline -- --write
The normal pnpm run eval:context command never writes the golden baseline.
The npm package is @showdar2112/code-atlas; it installs the code-atlas
command. The package can also be installed globally with pnpm:
pnpm add -g @showdar2112/code-atlas
Roadmap
Deferred work includes:
VS Code / GitHub Copilot integration
richer visual exploration
further change-intelligence workflows
These are independent of the lightweight graph and lexical core.
License
ISC. See package.json for the package metadata.
Opt-in relation responses expose output.resultCounts.beforeFilter and
output.resultCounts.afterFilter for the handler's bounded result window, before
pagination. totalReturned counts only results in the current page, including
zero after full filtering. These counts are not repository-wide totals. Calls
without response options retain the legacy handler contract.