@optave/codegraph 1.3.0 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">codegraph</h1>
 
 <p align="center">
-  <strong>Local code dependency graph CLI — parse, query, and visualize your codebase at file and function level.</strong>
+  <strong>Always-fresh code intelligence for AI agents — sub-second incremental rebuilds, zero-cost by default, optionally enhanced with your LLM.</strong>
 </p>
 
 <p align="center">
@@ -13,7 +13,7 @@
   <a href="https://github.com/optave/codegraph/blob/main/LICENSE"><img src="https://img.shields.io/github/license/optave/codegraph?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="Apache-2.0 License" /></a>
   <a href="https://github.com/optave/codegraph/actions"><img src="https://img.shields.io/github/actions/workflow/status/optave/codegraph/codegraph-impact.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 20" />
-  <img src="https://img.shields.io/badge/platform-local%20only-important?style=flat-square&logo=shield&logoColor=white" alt="Local Only" />
+  <img src="https://img.shields.io/badge/graph-always%20fresh-brightgreen?style=flat-square&logo=shield&logoColor=white" alt="Always Fresh" />
 </p>
 
 <p align="center">
@@ -31,9 +31,35 @@
 
 ---
 
-> **Zero network calls. Zero telemetry. Your code never leaves your machine.**
+> **The code graph that keeps up with your commits.**
 >
-> Codegraph uses [tree-sitter](https://tree-sitter.github.io/) (via WASM — no native compilation required) to parse your codebase into an AST, extracts functions, classes, imports, and call sites, resolves dependencies, and stores everything in a local SQLite database. Query it instantly from the command line.
+> Codegraph parses your codebase with [tree-sitter](https://tree-sitter.github.io/) (native Rust or WASM), builds a function-level dependency graph in SQLite, and keeps it current with sub-second incremental rebuilds. Every query runs locally — no API keys, no Docker, no setup. When you want deeper intelligence, bring your own LLM provider and codegraph enhances search and analysis through the same API you already use. Your code only goes where you choose to send it.
+
+---
+
+## 🔄 Why most code graph tools can't keep up with your commits
+
+If you use a code graph with an AI agent, the graph needs to be **current**. A stale graph gives the agent wrong answers — deleted functions still show up, new dependencies are invisible, impact analysis misses the code you just wrote. The graph should rebuild on every commit, ideally on every save.
+
+Most tools in this space can't do that:
+
+| Problem | Who has it | Why it breaks on every commit |
+|---|---|---|
+| **Full re-index on every change** | code-graph-rag, CodeMCP, axon, autodev-codebase | No file-level change tracking. Change one file → re-parse and re-insert the entire codebase. On a 3,000-file project, that's 30+ seconds per commit minimum |
+| **Cloud API calls baked into the pipeline** | code-graph-rag, autodev-codebase, Claude-code-memory, CodeRAG | Embeddings are generated through cloud APIs (OpenAI, Voyage AI, Gemini). Every rebuild = API round-trips for every function. Slow, expensive, and rate-limited. You can't put this in a commit hook |
+| **Heavy infrastructure that's slow to restart** | code-graph-rag (Memgraph), axon (KuzuDB), badger-graph (Dgraph) | External databases add latency to every write. Bulk-inserting a full graph into Memgraph is not a sub-second operation |
+| **No persistence between runs** | glimpse, pyan, cflow | Re-parse from scratch every time. No database, no delta, no incremental anything |
+
+**Codegraph solves this with incremental builds:**
+
+1. Every file gets an MD5 hash stored in SQLite
+2. On rebuild, only files whose hash changed get re-parsed
+3. Stale nodes and edges for changed files are cleaned, then re-inserted
+4. Everything else is untouched
+
+**Result:** change one file in a 3,000-file project → rebuild completes in **under a second**. Put it in a commit hook, a file watcher, or let your AI agent trigger it. The graph is always current.
+
+And because the core pipeline is pure local computation (tree-sitter + SQLite), there are no API calls, no network latency, and no cost. LLM-powered features (semantic search, richer embeddings) are a separate optional layer — they enhance the graph but never block it from being current.
 
 ---
 
@@ -41,52 +67,53 @@
 
 <sub>Comparison last verified: February 2026</sub>
 
-Most dependency graph tools only tell you which **files** import which — codegraph tells you which **functions** call which, who their callers are, and what breaks when something changes. Here's how it compares to the alternatives:
+Most code graph tools make you choose: **fast local analysis with no AI, or powerful AI features that require full re-indexing through cloud APIs on every change.** Codegraph gives you both — a graph that rebuilds in milliseconds on every commit, with optional LLM enhancement through the provider you're already using.
 
 ### Feature comparison
 
-| Capability | codegraph | Madge | dep-cruiser | Skott | Nx graph | Sourcetrail |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| Function-level analysis | **Yes** | — | — | — | — | **Yes** |
-| Multi-language | **10** | 1 | 1 | 1 | Any (project) | 4 |
-| Semantic search | **Yes** | — | — | — | — | — |
-| MCP / AI agent support | **Yes** | — | — | — | — | — |
-| Git diff impact | **Yes** | — | — | — | Partial | — |
-| Persistent database | **Yes** | — | — | — | — | Yes |
-| Watch mode | **Yes** | — | — | — | Daemon | — |
-| CI workflow included | **Yes** | — | Rules | — | Yes | — |
-| Cycle detection | **Yes** | Yes | Yes | Yes | — | — |
-| Zero config | **Yes** | Yes | — | Yes | — | — |
-| Fully local / no telemetry | **Yes** | Yes | Yes | Yes | Partial | Yes |
-| Free & open source | **Yes** | Yes | Yes | Yes | Partial | Archived |
+| Capability | codegraph | [code-graph-rag](https://github.com/vitali87/code-graph-rag) | [glimpse](https://github.com/seatedro/glimpse) | [CodeMCP](https://github.com/SimplyLiz/CodeMCP) | [axon](https://github.com/harshkedia177/axon) | [autodev-codebase](https://github.com/anrgct/autodev-codebase) | [arbor](https://github.com/Anandb71/arbor) | [Claude-code-memory](https://github.com/Durafen/Claude-code-memory) |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Function-level analysis | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | — |
+| Multi-language | **11** | Multi | Multi | SCIP langs | Few | **40+** | Multi | — |
+| Semantic search | **Yes** | **Yes** | — | — | — | **Yes** | **Yes** | **Yes** |
+| MCP / AI agent support | **Yes** | **Yes** | — | **Yes** | — | — | **Yes** | **Yes** |
+| Git diff impact | **Yes** | — | — | — | **Yes** | — | — | — |
+| Watch mode | **Yes** | — | — | — | — | — | — | — |
+| CI workflow included | **Yes** | — | — | — | — | — | — | — |
+| Cycle detection | **Yes** | — | — | — | **Yes** | — | — | — |
+| Incremental rebuilds | **Yes** | — | — | — | — | — | — | — |
+| Zero config | **Yes** | — | **Yes** | — | — | — | **Yes** | — |
+| LLM-optional (works without API keys) | **Yes** | — | **Yes** | **Yes** | **Yes** | — | **Yes** | — |
+| Open source | **Yes** | Yes | Yes | Custom | — | — | Yes | — |
 
 ### What makes codegraph different
 
 | | Differentiator | In practice |
 |---|---|---|
+| **⚡** | **Always-fresh graph** | Sub-second incremental rebuilds via file-hash tracking. Run on every commit, every save, in watch mode — the graph is never stale. Competitors re-index everything from scratch |
+| **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider for richer embeddings and AI-powered search — your code only goes to the provider you already chose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
-| **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + Terraform in a single graph — no juggling Madge, pyan, and cflow |
-| **🤖** | **AI-agent ready** | Built-in [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly via `codegraph fn <name>` |
+| **🤖** | **Built for AI agents** | 13-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
+| **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — no juggling Madge, pyan, and cflow |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow |
-| **🔒** | **Fully local, zero telemetry** | No accounts, no API keys, no cloud, no data exfiltration — Apache-2.0, free forever |
-| **⚡** | **Build once, query instantly** | SQLite-backed — build in ~30s, every query under 100ms. Native Rust engine with WASM fallback. Most competitors re-parse every run |
-| **🧠** | **Semantic search** | `codegraph search "handle auth"` uses local embeddings — multi-query with RRF ranking via `"auth; token; JWT"` |
+| **🧠** | **Semantic search** | Local embeddings by default, LLM-powered embeddings when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
 
 ### How other tools compare
 
-Many tools in this space are cloud-based or SaaS — meaning your code leaves your machine. Others require external services, accounts, or API keys. Codegraph makes **zero network calls** and has **zero telemetry**. Everything runs locally.
+The key question is: **can you rebuild your graph on every commit in a large codebase without it costing money or taking minutes?** Most tools in this space either re-index everything from scratch (slow), require cloud API calls for core features (costly), or both. Codegraph's incremental builds keep the graph current in milliseconds — and the core pipeline needs no API keys at all. LLM-powered features are opt-in, using whichever provider you already work with.
 
-| Tool | What it does well | Where it falls short |
+| Tool | What it does well | The tradeoff |
 |---|---|---|
+| [code-graph-rag](https://github.com/vitali87/code-graph-rag) | Graph RAG with Memgraph, multi-provider AI, semantic search, code editing via AST | No incremental rebuilds — full re-index + re-embed through cloud APIs on every change. Requires Docker |
+| [glimpse](https://github.com/seatedro/glimpse) | Clipboard-first LLM context tool, call graphs, LSP resolution, token counting | Context-packing tool, not a dependency graph — no persistence, no MCP, no incremental updates |
+| [CodeMCP](https://github.com/SimplyLiz/CodeMCP) | SCIP compiler-grade indexing, compound operations (83% token savings), secret scanning | No incremental builds. Custom license, requires SCIP toolchains per language |
+| [axon](https://github.com/harshkedia177/axon) | 11-phase pipeline, KuzuDB, community detection, dead code, change coupling | Full pipeline re-run on changes. No license, Python-only, no MCP |
+| [autodev-codebase](https://github.com/anrgct/autodev-codebase) | 40+ languages, interactive Cytoscape.js visualization, LLM reranking | Re-embeds through cloud APIs on changes. No license, complex setup |
+| [arbor](https://github.com/Anandb71/arbor) | Native GUI, confidence scoring, architectural role classification, fuzzy search | GUI-focused — no CLI pipeline, no watch mode, no CI integration |
+| [Claude-code-memory](https://github.com/Durafen/Claude-code-memory) | Persistent codebase memory for Claude Code, Memory Guard quality gate | Requires Voyage AI (cloud) + Qdrant (Docker) for core features |
 | [Madge](https://github.com/pahen/madge) | Simple file-level JS/TS dependency graphs | No function-level analysis, no impact tracing, JS/TS only |
 | [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) | Architectural rule validation for JS/TS | Module-level only (function-level explicitly out of scope), requires config |
-| [Skott](https://github.com/antoine-music/skott) | Module graph with unused code detection | File-level only, JS/TS only, no persistent database |
 | [Nx graph](https://nx.dev/) | Monorepo project-level dependency graph | Requires Nx workspace, project-level only (not file or function) |
-| [Sourcetrail](https://github.com/CoatiSoftware/Sourcetrail) | Rich GUI with symbol-level graphs | Archived/discontinued (2021), no JS/TS, no CLI |
-| [Sourcegraph](https://sourcegraph.com/) | Enterprise code search and navigation | Cloud/SaaS — code sent to servers, $19+/user/mo, no longer open source |
-| [CodeSee](https://www.codesee.io/) | Visual codebase maps | Cloud-based — code leaves your machine, acquired by GitKraken |
-| [Understand](https://scitools.com/) | Deep multi-language static analysis | $100+/month per seat, proprietary, GUI-only, no CI or AI integration |
-| [Snyk Code](https://snyk.io/) | AI-powered security scanning | Cloud-based — code sent to Snyk servers for analysis, not a dependency graph tool |
 | [pyan](https://github.com/Technologicat/pyan) / [cflow](https://www.gnu.org/software/cflow/) | Function-level call graphs | Single-language each (Python / C only), no persistence, no queries |
 
 ---
@@ -127,8 +154,8 @@ codegraph deps src/index.ts  # file-level import/export map
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | Model Context Protocol integration for AI assistants |
-| 🔒 | **Fully local** | No network calls, no data exfiltration, SQLite-backed |
+| 🤖 | **MCP server** | 13-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🔒 | **Your code, your choice** | Zero-cost core with no API keys. Optionally enhance with your LLM provider — your code only goes where you send it |
 
 ## 📦 Commands
 
@@ -212,12 +239,30 @@ A single trailing semicolon is ignored (falls back to single-query mode). The `-
 
 The model used during `embed` is stored in the database, so `search` auto-detects it — no need to pass `--model` when searching.
 
+### Multi-Repo Registry
+
+Manage a global registry of codegraph-enabled projects. The registry stores paths to your built graphs so the MCP server can query them when multi-repo mode is enabled.
+
+```bash
+codegraph registry list        # List all registered repos
+codegraph registry list --json # JSON output
+codegraph registry add <dir>   # Register a project directory
+codegraph registry add <dir> -n my-name  # Custom name
+codegraph registry remove <name>  # Unregister
+```
+
+`codegraph build` auto-registers the project — no manual setup needed.
+
 ### AI Integration
 
 ```bash
-codegraph mcp                  # Start MCP server for AI assistants
+codegraph mcp                  # Start MCP server (single-repo, current project only)
+codegraph mcp --multi-repo     # Enable access to all registered repos
+codegraph mcp --repos a,b      # Restrict to specific repos (implies --multi-repo)
 ```
 
+By default, the MCP server only exposes the local project's graph. AI agents cannot access other repositories unless you explicitly opt in with `--multi-repo` or `--repos`.
+
 ### Common Flags
 
 | Flag | Description |
@@ -228,7 +273,7 @@ codegraph mcp                  # Start MCP server for AI assistants
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
 | `--engine <engine>` | Parser engine: `native`, `wasm`, or `auto` (default: `auto`) |
-| `-k, --kind <kind>` | Filter by kind: `function`, `method`, `class` (search) |
+| `-k, --kind <kind>` | Filter by kind: `function`, `method`, `class`, `struct`, `enum`, `trait`, `record`, `module` (search) |
 | `--file <pattern>` | Filter by file path pattern (search) |
 | `--rrf-k <n>` | RRF smoothing constant for multi-query search (default 60) |
 
@@ -309,12 +354,18 @@ Benchmarked on a ~3,200-file TypeScript project:
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server, so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 13 tools, so AI assistants can query your dependency graph directly:
 
 ```bash
-codegraph mcp
+codegraph mcp                  # Single-repo mode (default) — only local project
+codegraph mcp --multi-repo     # Multi-repo — all registered repos accessible
+codegraph mcp --repos a,b      # Multi-repo with allowlist
 ```
 
+**Single-repo mode (default):** Tools operate only on the local `.codegraph/graph.db`. The `repo` parameter and `list_repos` tool are not exposed to the AI agent.
+
+**Multi-repo mode (`--multi-repo`):** All tools gain an optional `repo` parameter to target any registered repository, and `list_repos` becomes available. Use `--repos` to restrict which repos the agent can access.
+
 ### CLAUDE.md / Agent Instructions
 
 Add this to your project's `CLAUDE.md` to help AI agents use codegraph:
@@ -366,6 +417,7 @@ See **[docs/recommended-practices.md](docs/recommended-practices.md)** for integ
 - **CI/CD** — PR impact comments, threshold gates, graph caching
 - **AI agents** — MCP server, CLAUDE.md templates, Claude Code hooks
 - **Developer workflow** — watch mode, explore-before-you-edit, semantic search
+- **Secure credentials** — `apiKeyCommand` with 1Password, Bitwarden, Vault, macOS Keychain, `pass`
 
 ## 🔁 CI / GitHub Actions
 
@@ -395,6 +447,23 @@ Create a `.codegraphrc.json` in your project root to customize behavior:
 }
 ```
 
+### LLM credentials
+
+Codegraph supports an `apiKeyCommand` field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:
+
+```json
+{
+  "llm": {
+    "provider": "openai",
+    "apiKeyCommand": "op read op://vault/openai/api-key"
+  }
+}
+```
+
+The command is split on whitespace and executed with `execFileSync` (no shell injection risk). Priority: **command output > `CODEGRAPH_LLM_API_KEY` env var > file config**. On failure, codegraph warns and falls back to the next source.
+
+Works with any secret manager: 1Password CLI (`op`), Bitwarden (`bw`), `pass`, HashiCorp Vault, macOS Keychain (`security`), AWS Secrets Manager, etc.
+
 ## 📖 Programmatic API
 
 Codegraph also exports a full API for use in your own tools:
@@ -449,7 +518,7 @@ const { results: fused } = await multiSearchData(
 See **[ROADMAP.md](ROADMAP.md)** for the full development roadmap. Current plan:
 
 1. ~~**Rust Core**~~ — **Complete** (v1.3.0) — native tree-sitter parsing via napi-rs, parallel multi-core parsing, incremental re-parsing, import resolution & cycle detection in Rust
-2. **Foundation Hardening** — ~~parser registry~~, complete MCP server, test coverage, enhanced config
+2. ~~**Foundation Hardening**~~ — **Complete** (v1.4.0) — parser registry, 12-tool MCP server with multi-repo support, test coverage 62%→75%, `apiKeyCommand` secret resolution, global repo registry
 3. **Intelligent Embeddings** — LLM-generated descriptions, hybrid search
 4. **Natural Language Queries** — `codegraph ask` command, conversational sessions
 5. **Expanded Language Support** — 8 new languages (12 → 20)
@@ -476,5 +545,5 @@ Looking to add a new language? Check out **[Adding a New Language](docs/adding-a
 ---
 
 <p align="center">
-  <sub>Built with <a href="https://tree-sitter.github.io/">tree-sitter</a> and <a href="https://github.com/WiseLibs/better-sqlite3">better-sqlite3</a>. No data leaves your machine. Ever.</sub>
+  <sub>Built with <a href="https://tree-sitter.github.io/">tree-sitter</a> and <a href="https://github.com/WiseLibs/better-sqlite3">better-sqlite3</a>. Your code only goes where you choose to send it.</sub>
 </p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
@@ -61,10 +61,10 @@
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "1.3.0",
-    "@optave/codegraph-darwin-x64": "1.3.0",
-    "@optave/codegraph-linux-x64-gnu": "1.3.0",
-    "@optave/codegraph-win32-x64-msvc": "1.3.0"
+    "@optave/codegraph-darwin-arm64": "2.0.0",
+    "@optave/codegraph-darwin-x64": "2.0.0",
+    "@optave/codegraph-linux-x64-gnu": "2.0.0",
+    "@optave/codegraph-win32-x64-msvc": "2.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/builder.js

@@ -4,24 +4,26 @@ import path from 'node:path';
 import { loadConfig } from './config.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
 import { initSchema, openDb } from './db.js';
-import { warn } from './logger.js';
+import { debug, warn } from './logger.js';
 import { getActiveEngine, parseFilesAuto } from './parser.js';
 import { computeConfidence, resolveImportPath, resolveImportsBatch } from './resolve.js';
 
 export { resolveImportPath } from './resolve.js';
 
-export function collectFiles(dir, files = [], config = {}) {
+export function collectFiles(dir, files = [], config = {}, directories = null) {
+  const trackDirs = directories !== null;
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     warn(`Cannot read directory ${dir}: ${err.message}`);
-    return files;
+    return trackDirs ? { files, directories } : files;
   }
 
   // Merge config ignoreDirs with defaults
   const extraIgnore = config.ignoreDirs ? new Set(config.ignoreDirs) : null;
 
+  let hasFiles = false;
   for (const entry of entries) {
     if (entry.name.startsWith('.') && entry.name !== '.') {
       if (IGNORE_DIRS.has(entry.name)) continue;
@@ -32,12 +34,16 @@ export function collectFiles(dir, files = [], config = {}) {
 
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      collectFiles(full, files, config);
+      collectFiles(full, files, config, directories);
     } else if (EXTENSIONS.has(path.extname(entry.name))) {
       files.push(full);
+      hasFiles = true;
     }
   }
-  return files;
+  if (trackDirs && hasFiles) {
+    directories.add(dir);
+  }
+  return trackDirs ? { files, directories } : files;
 }
 
 export function loadPathAliases(rootDir) {
@@ -163,7 +169,9 @@ export async function buildGraph(rootDir, opts = {}) {
     );
   }
 
-  const files = collectFiles(rootDir, [], config);
+  const collected = collectFiles(rootDir, [], config, new Set());
+  const files = collected.files;
+  const discoveredDirs = collected.directories;
   console.log(`Found ${files.length} files to parse`);
 
   // Check for incremental build
@@ -179,23 +187,28 @@ export async function buildGraph(rootDir, opts = {}) {
 
   if (isFullBuild) {
     db.exec(
-      'PRAGMA foreign_keys = OFF; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
+      'PRAGMA foreign_keys = OFF; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
     );
   } else {
     console.log(`Incremental: ${changed.length} changed, ${removed.length} removed`);
-    // Remove nodes/edges for changed and removed files
+    // Remove metrics/edges/nodes for changed and removed files
     const deleteNodesForFile = db.prepare('DELETE FROM nodes WHERE file = ?');
     const deleteEdgesForFile = db.prepare(`
       DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f)
       OR target_id IN (SELECT id FROM nodes WHERE file = @f)
     `);
+    const deleteMetricsForFile = db.prepare(
+      'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    );
     for (const relPath of removed) {
       deleteEdgesForFile.run({ f: relPath });
+      deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
     for (const item of changed) {
       const relPath = item.relPath || normalizePath(path.relative(rootDir, item.file));
       deleteEdgesForFile.run({ f: relPath });
+      deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
   }
@@ -539,8 +552,39 @@ export async function buildGraph(rootDir, opts = {}) {
   });
   buildEdges();
 
+  // Build line count map for structure metrics
+  const lineCountMap = new Map();
+  for (const [relPath] of fileSymbols) {
+    const absPath = path.join(rootDir, relPath);
+    try {
+      const content = fs.readFileSync(absPath, 'utf-8');
+      lineCountMap.set(relPath, content.split('\n').length);
+    } catch {
+      lineCountMap.set(relPath, 0);
+    }
+  }
+
+  // Build directory structure, containment edges, and metrics
+  const relDirs = new Set();
+  for (const absDir of discoveredDirs) {
+    relDirs.add(normalizePath(path.relative(rootDir, absDir)));
+  }
+  try {
+    const { buildStructure } = await import('./structure.js');
+    buildStructure(db, fileSymbols, rootDir, lineCountMap, relDirs);
+  } catch (err) {
+    debug(`Structure analysis failed: ${err.message}`);
+  }
+
   const nodeCount = db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
   console.log(`Graph built: ${nodeCount} nodes, ${edgeCount} edges`);
   console.log(`Stored in ${dbPath}`);
   db.close();
+
+  try {
+    const { registerRepo } = await import('./registry.js');
+    registerRepo(rootDir);
+  } catch (err) {
+    debug(`Auto-registration failed: ${err.message}`);
+  }
 }

package/src/cli.js

@@ -19,6 +19,13 @@ import {
   moduleMap,
   queryName,
 } from './queries.js';
+import {
+  listRepos,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  unregisterRepo,
+} from './registry.js';
 import { watchProject } from './watcher.js';
 
 const program = new Command();
@@ -186,9 +193,81 @@ program
   .command('mcp')
   .description('Start MCP (Model Context Protocol) server for AI assistant integration')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('--multi-repo', 'Enable access to all registered repositories')
+  .option('--repos <names>', 'Comma-separated list of allowed repo names (restricts access)')
   .action(async (opts) => {
     const { startMCPServer } = await import('./mcp.js');
-    await startMCPServer(opts.db);
+    const mcpOpts = {};
+    mcpOpts.multiRepo = opts.multiRepo || !!opts.repos;
+    if (opts.repos) {
+      mcpOpts.allowedRepos = opts.repos.split(',').map((s) => s.trim());
+    }
+    await startMCPServer(opts.db, mcpOpts);
+  });
+
+// ─── Registry commands ──────────────────────────────────────────────────
+
+const registry = program.command('registry').description('Manage the multi-repo project registry');
+
+registry
+  .command('list')
+  .description('List all registered repositories')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    const repos = listRepos();
+    if (opts.json) {
+      console.log(JSON.stringify(repos, null, 2));
+    } else if (repos.length === 0) {
+      console.log(`No repositories registered.\nRegistry: ${REGISTRY_PATH}`);
+    } else {
+      console.log(`Registered repositories (${REGISTRY_PATH}):\n`);
+      for (const r of repos) {
+        const dbExists = fs.existsSync(r.dbPath);
+        const status = dbExists ? '' : ' [DB missing]';
+        console.log(`  ${r.name}${status}`);
+        console.log(`    Path: ${r.path}`);
+        console.log(`    DB:   ${r.dbPath}`);
+        console.log();
+      }
+    }
+  });
+
+registry
+  .command('add <dir>')
+  .description('Register a project directory')
+  .option('-n, --name <name>', 'Custom name (defaults to directory basename)')
+  .action((dir, opts) => {
+    const absDir = path.resolve(dir);
+    const { name, entry } = registerRepo(absDir, opts.name);
+    console.log(`Registered "${name}" → ${entry.path}`);
+  });
+
+registry
+  .command('remove <name>')
+  .description('Unregister a repository by name')
+  .action((name) => {
+    const removed = unregisterRepo(name);
+    if (removed) {
+      console.log(`Removed "${name}" from registry.`);
+    } else {
+      console.error(`Repository "${name}" not found in registry.`);
+      process.exit(1);
+    }
+  });
+
+registry
+  .command('prune')
+  .description('Remove registry entries whose directories no longer exist')
+  .action(() => {
+    const pruned = pruneRegistry();
+    if (pruned.length === 0) {
+      console.log('No stale entries found.');
+    } else {
+      for (const entry of pruned) {
+        console.log(`Pruned "${entry.name}" (${entry.path})`);
+      }
+      console.log(`\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`);
+    }
   });
 
 // ─── Embedding commands ─────────────────────────────────────────────────
@@ -244,6 +323,53 @@ program
     });
   });
 
+program
+  .command('structure [dir]')
+  .description(
+    'Show project directory structure with hierarchy, cohesion scores, and per-file metrics',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Max directory depth')
+  .option('--sort <metric>', 'Sort by: cohesion | fan-in | fan-out | density | files', 'files')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (dir, opts) => {
+    const { structureData, formatStructure } = await import('./structure.js');
+    const data = structureData(opts.db, {
+      directory: dir,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      sort: opts.sort,
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(formatStructure(data));
+    }
+  });
+
+program
+  .command('hotspots')
+  .description(
+    'Find structural hotspots: files or directories with extreme fan-in, fan-out, or symbol density',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Number of results', '10')
+  .option('--metric <metric>', 'fan-in | fan-out | density | coupling', 'fan-in')
+  .option('--level <level>', 'file | directory', 'file')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (opts) => {
+    const { hotspotsData, formatHotspots } = await import('./structure.js');
+    const data = hotspotsData(opts.db, {
+      metric: opts.metric,
+      level: opts.level,
+      limit: parseInt(opts.limit, 10),
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(formatHotspots(data));
+    }
+  });
+
 program
   .command('watch [dir]')
   .description('Watch project for file changes and incrementally update the graph')

package/src/config.js

@@ -1,6 +1,7 @@
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 
 export const CONFIG_FILES = ['.codegraphrc.json', '.codegraphrc', 'codegraph.config.json'];
 
@@ -18,6 +19,10 @@ export const DEFAULTS = {
     defaultDepth: 3,
     defaultLimit: 20,
   },
+  embeddings: { model: 'minilm', llmProvider: null },
+  llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
+  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15 },
+  ci: { failOnCycles: false, impactThreshold: null },
 };
 
 /**
@@ -33,13 +38,50 @@ export function loadConfig(cwd) {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const config = JSON.parse(raw);
         debug(`Loaded config from ${filePath}`);
-        return mergeConfig(DEFAULTS, config);
+        return resolveSecrets(applyEnvOverrides(mergeConfig(DEFAULTS, config)));
       } catch (err) {
         debug(`Failed to parse config ${filePath}: ${err.message}`);
       }
     }
   }
-  return { ...DEFAULTS };
+  return resolveSecrets(applyEnvOverrides({ ...DEFAULTS }));
+}
+
+const ENV_LLM_MAP = {
+  CODEGRAPH_LLM_PROVIDER: 'provider',
+  CODEGRAPH_LLM_API_KEY: 'apiKey',
+  CODEGRAPH_LLM_MODEL: 'model',
+};
+
+export function applyEnvOverrides(config) {
+  for (const [envKey, field] of Object.entries(ENV_LLM_MAP)) {
+    if (process.env[envKey] !== undefined) {
+      config.llm[field] = process.env[envKey];
+    }
+  }
+  return config;
+}
+
+export function resolveSecrets(config) {
+  const cmd = config.llm.apiKeyCommand;
+  if (typeof cmd !== 'string' || cmd.trim() === '') return config;
+
+  const parts = cmd.trim().split(/\s+/);
+  const [executable, ...args] = parts;
+  try {
+    const result = execFileSync(executable, args, {
+      encoding: 'utf-8',
+      timeout: 10_000,
+      maxBuffer: 64 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    if (result) {
+      config.llm.apiKey = result;
+    }
+  } catch (err) {
+    warn(`apiKeyCommand failed: ${err.message}`);
+  }
+  return config;
 }
 
 function mergeConfig(defaults, overrides) {

package/src/constants.js

@@ -20,8 +20,6 @@ export const IGNORE_DIRS = new Set([
   '.env',
 ]);
 
-// Re-export as an indirect binding to avoid TDZ in the circular
-// parser.js ↔ constants.js import (no value read at evaluation time).
 export { SUPPORTED_EXTENSIONS as EXTENSIONS };
 
 export function shouldIgnore(dirName) {