@showdar2112/code Atlas

CodeAtlas

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.

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:

code-atlas connect codex
code-atlas connect --all
code-atlas disconnect codex
code-atlas disconnect --all

Task context compiler

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

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:

code-atlas semantic setup --provider openai-compatible \
  --base-url https://embedding.example/v1 \
  --model your-embedding-model \
  --api-key-env OPENAI_API_KEY

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:

Codex · OpenCode · Claude Code · Gemini CLI · Cursor · Cline · Windsurf · Zoo Code

Use the registry-driven selector for a terminal workflow:

code-atlas connect
code-atlas disconnect

Use deterministic bulk operations in automation:

code-atlas connect --all
code-atlas disconnect --all

connect --all operates on detected and safely configurable integrations. disconnect --all removes recognizable CodeAtlas-managed configuration while preserving unrelated client settings.

For compatibility with older scripts, these aliases remain available:

code-atlas integration install codex
code-atlas integration uninstall codex
code-atlas integration list
code-atlas integration status

MCP for any client

First-class adapters are convenient, but they are not required. To obtain the durable CodeAtlas stdio launch configuration for another MCP client:

code-atlas integration config --format json

The command prints only this JSON shape and does not modify third-party files:

{
  "command": "/absolute/path/to/node",
  "args": [
    "/absolute/path/to/code-atlas/dist/cli.js",
    "mcp"
  ]
}

The exported launcher uses absolute paths and does not depend on an interactive shell PATH. It can be pasted into any compatible stdio MCP client.

MCP tools

Start CodeAtlas as an MCP server with code-atlas mcp, or let a configured agent start the persisted stdio launcher.

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:

{
  "query": "AuthService",
  "limit": 80,
  "response": {
    "mode": "focused",
    "maxOutputBytes": 16000,
    "pageSize": 20
  }
}

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.

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.

{
  "version": 1,
  "architecture": {
    "groups": [
      { "id": "ui", "include": ["src/ui/**"] },
      { "id": "domain", "include": ["src/domain/**"] },
      { "id": "data", "include": ["src/data/**"] }
    ],
    "defaultCrossGroupAction": "allow",
    "rules": [
      {
        "id": "ui-no-data",
        "from": "ui",
        "to": "data",
        "action": "deny",
        "edgeKinds": ["imports", "calls"],
        "severity": "high"
      }
    ],
    "cycles": { "enabled": true, "severity": "medium" }
  }
}

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.

Trivial tasks do not need CodeAtlas boilerplate.

How it works

Repository → Parsed Facts → Resolver + Graph → Queries → Coding Agent

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.

CLI self-upgrade

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:

code-atlas hook install --post-commit --post-checkout

Local-first by default

CodeAtlas requires Node.js 22 or newer and its regular Node package dependencies. It does not require:

• model downloads
• Transformers or an ONNX semantic runtime
• a local LLM
• Python
• Docker
• a GPU
• a remote indexing service

Semantic providers remain optional. The default experience is useful with graph, lexical, and change/impact intelligence alone.

Development

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm run ui:typecheck
pnpm run eval:context

Focused Phase15E checks:

node --import tsx/esm --test \
  test/phase15e-mcp-metadata.test.ts \
  test/phase15e-upgrade-check.test.ts \
  test/phase15e-upgrade-install.test.ts
pnpm run test:mcp:inspector

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.