localscope

A local code analyst for your AI assistant — and for you.

localscope is an MCP server that indexes your repository on your machine — files, symbols, imports, references, optional embeddings — and lets Claude, Cursor, Codex, Windsurf, or any MCP client answer questions like:

"Where does X break if I change Y?"

without a single byte of your code leaving your machine. And when there's no AI client around, localscope explore puts the same graph in your terminal.

$ localscope explore

  change what? parseConfig
    parseConfig   function · src/utils/config.ts:6
    AppConfig     interface · src/utils/config.ts:1
    … 4 more

  [enter]

  Impact of changing parseConfig
  2 files affected · 2 direct · 0 transitive

  Breaks first
    src/main.ts
    src/services/server.ts

  Esc back to search · Ctrl-C exit

Commands

| Command | What it does | |---|---| | localscope explore | Interactive impact browser: type a symbol or file, see what breaks — fzf-style, in your terminal. ↑/↓ highlights a victim, o opens it in your $EDITOR at the first call site | | localscope report --target X | The same impact analysis, plain text to stdout — pipe it, grep it, put it in CI | | localscope index | Build or refresh the local index (incremental — unchanged files are skipped) |

No AI client, no network, no leaving the repo. The MCP server and the CLI share one index.

Why

Cloud code-search tools are great — until the repo is under NDA, on an air-gapped machine, or you simply don't want your code on someone else's servers. localscope gives assistants codebase vision with a hard guarantee: zero network calls, zero telemetry, zero config.

| | localscope | cloud tools | |---|---|---| | Code leaves machine | never | yes | | Setup | npx localscope-mcp | API key, upload | | Works offline | yes | no | | Impact analysis | AST symbols + call graph | varies |

Quickstart

Requirements: Node 18+.

Claude Code:

claude mcp add localscope -- npx localscope-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "localscope": { "command": "npx", "args": ["localscope-mcp"] }
  }
}

Any MCP client — stdio server, one command:

npx localscope-mcp

Optional: semantic search with local ONNX embeddings (still offline — the model runs on your CPU):

npm install -g @huggingface/transformers

Not installed? localscope automatically falls back to lexical + symbol search. No error, no setup step.

Tools

localscope_index

Build the local index: files, symbols, import graph, embeddings if available. Respects .gitignore and skips node_modules, dist, lockfiles, binaries. Typical repo indexes in well under a second.

Persistent and incremental. The index is cached on disk (under ~/.cache/localscope/<repo-digest>/) and reused across sessions: re-running localscope_index only re-extracts files whose mtime/size changed, and localscope_search / localscope_impact load the persisted index automatically — no full re-index in every session. While the server runs, a file watcher keeps the index fresh: edit a file, and the update lands in the background within ~300ms. Set LOCALSCOPE_CACHE_DIR to relocate the cache.

localscope_search

Find code by meaning ("retry with backoff"), by symbol name ("parseConfig"), or by fragment. Each hit shows file, lines, symbol, score, and how it matched — semantic, lexical, or symbol. Identifiers are split camelCase-aware, so "parse config" finds parseConfig.

localscope_impact

The headline tool. Give it a file path or a symbol name and it walks the reverse dependency graph:

• Direct dependents — files importing the target; these break first
• Transitive dependents — everything downstream, up to max_depth hops
• Symbols at risk — exported functions/classes in the target and why each is fragile
• Fuzzy suggestions — typo in the name? It suggests what you meant

localscope_references

A local "find all usages": every call site and read of a symbol, with exact line numbers per file. where is parseConfig called? → src/main.ts:4 and friends — from the AST reference graph, offline.

localscope_definition

A local "go to definition": file, line span, kind, and export status of a symbol.

localscope_status

Index stats: files, chunks, symbols, embedder mode, timestamp.

Privacy guarantee

localscope makes no outbound network calls — not for search, not for models, not for updates. The ONNX embedder (if you install it) downloads its model once from Hugging Face into your local cache, then runs fully offline. You can verify it yourself: src/services/embedder.ts is the only module that touches @huggingface/transformers, and only when you've installed it.

Air-gap friendly. NDA friendly. Paranoia friendly.

Performance

Measured on ripgrep (233 source files, 110 in Rust), M1 MacBook Air, default Node heap:

| Operation | Time | Result | |---|---|---| | Cold index, ONNX embeddings | ~2 min | 2,786 symbols · 9,288 references · 3,277 chunks | | Cold index, lexical only (no transformers installed) | ~2 s | same graph, no semantic search | | Re-open (warm cache, incremental) | 1.3 s | zero re-extraction | | localscope_impact / references | < 10 ms | from the in-memory graph |

The index persists to disk (~75 MB for ripgrep); every session after the first is the warm number. The file watcher keeps it fresh while the server runs — editing a file lands in the index within ~300 ms.

Star it

If localscope saved you a refactor-induced bug, ⭐ star the repo — it helps others find it.

How impact analysis works

1. Parse each file with tree-sitter (WASM — no native builds, no language servers). Accurate symbols — functions, classes, interfaces, types, methods, constants — with real line spans and export status. Grammars ship inside the package: TypeScript/TSX, JavaScript, Python, Go, Rust, Java, Ruby, PHP, C, C++, C#. No grammar available (exotic file, pruned install)? localscope falls back to regex extraction — zero-config either way.
2. Record references, not just imports: every identifier use (call sites, type references) goes into the symbol graph, so impact analysis answers "who actually calls this", not just "who imports the file it lives in".
3. Resolve imports into a file graph. TypeScript-style .js → .ts mapping included (ESM-style imports resolve correctly).
4. Answer "who breaks?" by traversing the reverse graph and cross-referencing the symbol table.

No LSP server. No language server per language. No daemon. Just reading files fast and getting the graph right.

HTTP mode (optional)

stdio is the default and right for local use. If you need HTTP (e.g. a shared dev-machine setup):

LOCALSCOPE_TRANSPORT=http LOCALSCOPE_PORT=3000 npx localscope-mcp
# MCP endpoint: http://127.0.0.1:3000/mcp

Binds to 127.0.0.1 only, rejects non-local origins. Do not expose it to the network.

Configuration

Zero required. Everything is optional:

| Env var | Default | Purpose | |---|---|---| | LOCALSCOPE_TRANSPORT | stdio | stdio or http | | LOCALSCOPE_PORT | 3000 | HTTP port | | LOCALSCOPE_RG_PATH | auto-detect | Path to ripgrep binary, if you have one | | LOCALSCOPE_CACHE_DIR | ~/.cache/localscope | Base dir for persisted indexes |

Development

git clone <repo> && cd localscope
npm install
npm test        # 62 tests
npm run build
npx @modelcontextprotocol/inspector node dist/index.js

CI runs typecheck, lint, and tests on Node 18/20/22 across Linux, macOS, and Windows.

License

MIT