Code Compass

Code Compass turns a JavaScript, TypeScript, or Python web repository into a local, evidence-backed system map. It connects modules, symbols, calls, HTTP clients and routes, and static SQL usage without uploading source code or requiring a framework-specific plugin.

The design rule is simple: prove what can be proved, label what is inferred, and preserve what could not be resolved. The graph never silently disappears facts to look cleaner.

Start

Code Compass requires Node.js 20.19 or newer. Python analysis uses a local Python 3.9+ interpreter when the repository contains Python files.

npx code-compass-graph .

That indexes the complete supported source tree under the current repository—including workspace packages and mixed frontend/backend code—starts the local portal on 127.0.0.1, and prints its URL. Other workflows are explicit:

code-compass index .
code-compass index . --compact
code-compass serve . --port 4747
code-compass mcp .
code-compass doctor .
code-compass init .

index writes .code-compass/graph.json atomically. Config-derived output stays inside that tool-owned directory; an explicit CLI --output can deliberately target another JSON path. serve, doctor, and mcp otherwise keep their snapshot in memory, so they also work against read-only checkouts. serve exposes the portal and a small loopback-only API. mcp speaks JSON-RPC over stdio, so logs stay on stderr.

What it understands

• JavaScript and TypeScript projects use their real tsconfig.json/jsconfig.json, module resolution, compiler options, workspace boundaries, AST, and TypeChecker.
• Python is parsed once per index with the standard-library AST. Imports, nested methods, decorators, call sites, source roots, effects, and unresolved facts are retained.
• HTTP requests and server routes are connected across languages when method and normalized path provide a unique match. Proven framework routers and raw Node http/https listeners are supported, including handler factories, reachable routing helpers, literal and parameterized-regex pathname checks, method guards, and thin local request wrappers.
• Static SQL definitions and reads/writes—including .sql migrations—produce portable database, table, column, foreign-key, and access evidence. Database URI credentials and query values are never emitted. Code Compass does not connect to a live database.
• CSS-family imports, package dependencies, repository projects, cycles, blast radius, and centrality complete the architecture view.

Every relationship has a confidence grade:

| Grade | Meaning | | --- | --- | | semantic-exact | Compiler/type information proves the target. | | syntax-exact | Unambiguous syntax proves the local fact. | | inferred | Strong project evidence identifies one likely target. | | heuristic | Useful but ambiguous evidence; inspect before acting. | | unresolved | The source fact is real, but Code Compass cannot prove a target. |

Stable symbol IDs are based on repository path, qualified name, kind, and overload identity—not source line numbers—so adding lines does not churn integrations.

Configuration

Configuration is optional. Put code-compass.config.json in the target root when the portable defaults need help:

{
  "$schema": "./node_modules/code-compass-graph/schema/config.schema.json",
  "projectName": "commerce-platform",
  "ignore": ["node_modules", "dist", ".venv", "generated"],
  "areas": [
    { "name": "storefront", "pattern": "apps/storefront/**" },
    { "name": "orders", "pattern": "services/orders/**" }
  ],
  "typescript": { "enabled": true, "configFiles": "auto" },
  "python": { "enabled": true, "roots": ["services/api/src"] },
  "database": { "enabled": true },
  "output": ".code-compass/graph.json"
}

The configuration JSON Schema and an example ship with the package. Paths stay repository-relative. Symlinks are skipped, source access is containment-checked, and project config files are read as data rather than executed.

Repository configuration cannot select an executable. Code Compass discovers a Python 3.9+ interpreter without running repository code; an operator can choose a different interpreter with the CODE_COMPASS_PYTHON environment variable. Embedders that already control their inputs may instead pass python.command as a trusted programmatic override. This setting is deliberately absent from—and rejected in—code-compass.config.json and .code-compassrc.json.

Library API

The same index powers the portal, JSON artifact, and MCP server:

import { createCodeCompassService, createGraphQuery, indexRepository } from 'code-compass-graph'

const graph = await indexRepository('/absolute/path/to/repository')
const query = createGraphQuery(graph)

console.log(query.fileDetails('src/server.ts'))
console.log(query.traceSymbol('createOrder'))

const service = createCodeCompassService({ root: '/absolute/path/to/repository' })
const snapshot = await service.ensureGraph()
await service.close()

The exported TypeScript declarations and versioned graph schema make the snapshot a supported integration surface. Query traversal is bounded by caller-controlled depth and result limits.

MCP

The MCP transport exposes ten narrow repository questions instead of dumping the entire graph into model context: overview, search, file explanation, dependency impact, symbol tracing, path explanation, cross-language system flows, database overview, database details, and table details. Results include source evidence and confidence, and all queries reuse one freshness-aware index.

Example Codex/Claude-style server configuration:

{
  "command": "npx",
  "args": ["-y", "code-compass-graph", "mcp", "/absolute/path/to/repository"]
}

Performance model

Discovery is deterministic and ignores generated/vendor directories by default. A cheap metadata fingerprint avoids compiler work when nothing relevant changed. Concurrent requests share one in-flight index, publishing is atomic, and one bounded retry handles edits that land during analysis. Exact blast radius uses a stack-safe condensed graph with structurally shared reachability; betweenness samples sources on large repositories while preserving complete nodes and edges.

No symbol cap is applied: accepted files and relationships remain complete. Hostile or accidentally generated trees are contained by explicit deterministic safety budgets: at most 50,000 relevant files, 128 MiB of retained source plus project metadata, and an immutable 8 MiB ceiling per source file (the portable default is 1.5 MiB). Crossing a budget stops discovery at a stable path boundary and emits a diagnostic instead of exhausting memory; normal ignored generated/vendor directories never consume the budget.

Accuracy boundaries

Static analysis cannot prove runtime reflection, generated modules that do not exist on disk, monkey-patching, dynamic import expressions, framework routes assembled from arbitrary values, or SQL constructed entirely at runtime. Those cases appear as unresolved or inferred evidence where detectable. Native-language syntax errors and missing interpreters are diagnostics; they do not erase the rest of the repository map.

Development

npm test
npm run build
npm pack --dry-run

Set CODE_COMPASS_ROOT=/path/to/repository when developing the portal against a different target, then run npm run dev.

MIT licensed.