edhindex 1.0.0

package/.edhindexignore

@@ -0,0 +1,66 @@
+node_modules
+.git
+dist
+build
+coverage
+.next
+out
+vendor
+bin
+obj
+target
+tmp
+.cache
+.turbo
+.edhindex
+*.exe
+*.dll
+*.so
+*.dylib
+*.bin
+*.wasm
+*.o
+*.a
+*.lib
+*.pyc
+*.class
+*.jar
+*.war
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.svg
+*.ico
+*.webp
+*.bmp
+*.tiff
+*.ico
+*.pdf
+*.doc
+*.docx
+*.xls
+*.xlsx
+*.ppt
+*.pptx
+*.zip
+*.tar
+*.gz
+*.bz2
+*.7z
+*.rar
+*.mp4
+*.avi
+*.mov
+*.wmv
+*.flv
+*.mkv
+*.mp3
+*.wav
+*.flac
+*.ogg
+*.min.js
+*.min.css
+package-lock.json
+yarn.lock
+pnpm-lock.yaml

package/BUILD_BRIEF.md

@@ -0,0 +1,228 @@
+# EDHIndex — build brief
+
+## How to use this
+Save this file as `BUILD_BRIEF.md` in the repo root. Works with whatever AI coding agent you're using — GitHub Copilot, Claude Code, Cursor, Windsurf, or anything else. Reference it however that tool supports. Build the v1 section fully, end to end, before opening the v2 section — v2 exists so an eager agent doesn't try to build everything at once.
+
+## What this is
+EDHIndex is a standalone local tool that indexes a codebase and exposes fast, hybrid code search (keyword + semantic + reranked) as an MCP server. Any MCP-compatible client can connect and call it. Self-contained — no dependency on any editor, terminal, or agent application.
+
+## Think of it as a code intelligence engine, not "a RAG project"
+RAG is one consumer of this engine, not the whole identity of it. Layers, top to bottom:
+```
+CLI
+  |
+Configuration
+  |
+Workspace manager
+  |
+Indexer        (tree-sitter parser, file watcher, git integration)
+  |
+Storage        (SQLite: metadata + FTS5  |  LanceDB: embeddings)
+  |
+Retrieval engine (BM25, vector search, rerank)
+  |
+MCP server
+```
+This separation is what lets you later build a CLI grep tool, a VS Code extension, or anything else on the same core without touching the indexing or retrieval layers.
+
+## Naming conventions
+- Repo / npm package / CLI command: `edhindex` — no exact match found on npm at time of writing, but double-check on npmjs.com right before first publish since registry search results can lag.
+- Local index folder inside any indexed project: `.edhindex/`
+- Ignore file: `.edhindexignore` (same syntax as `.gitignore`)
+
+## Design principles
+These are the non-negotiable values the rest of this brief is derived from. When a build decision isn't spelled out explicitly elsewhere, default back to these:
+- Local-first — the tool works fully on the user's machine
+- Offline-first — no network dependency after the embedding model is downloaded once
+- Zero telemetry
+- No vendor lock-in — interfaces over concrete libraries, everywhere it matters
+- Deterministic indexing — same input produces the same index
+- Incremental updates only — never re-do work that isn't stale
+- Safe-by-default — security guardrails are load-bearing, not optional
+- Extensible without rewriting core components
+
+## Distribution model — git repo, not a hosted service
+- User runs `git clone`, then `npm install`
+- `npx edhindex start` launches it locally, pointed at whichever folder the user opens
+- Everything happens inside that folder — nothing hosted, nothing leaves the machine
+
+## Model tiers — user picks one on first run
+- **Light** — bge-small-en-v1.5 (~130MB) or all-MiniLM-L6-v2 (~46MB). Old/weak hardware.
+- **Balanced** (default) — nomic-embed-text-v1.5/v2 (~270MB). 8,192 token context, best size-to-quality tradeoff.
+- **Max quality** — BGE-M3 (~1.1-2.2GB). Matches commercial APIs on benchmarks, needs more RAM/CPU.
+
+All run locally via `@huggingface/transformers` — no API call, no account, no ongoing cost at any tier. Switching tiers later requires a full re-index — vectors from different models aren't compatible with each other.
+
+---
+
+# V1 — build this first, ship it, then stop
+
+## Supported languages (v1)
+TypeScript, JavaScript, Go, Python. Nothing else yet — don't let an agent try to wire up every Tree-sitter grammar that exists.
+
+## Never index these (v1)
+`node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `out`, `vendor`, `bin`, `obj`, `target`, `tmp`, `.cache`, `.turbo` — plus whatever the user adds to `.edhindexignore`.
+
+## File limits (v1)
+Skip anything over 10MB. Skip binaries, images, PDFs, videos, archives, and anything that looks generated.
+
+## Chunking strategy (v1)
+Priority order: function → method → class → interface → enum → module → file. If a unit exceeds the embedding model's token limit, split it recursively rather than truncating silently.
+
+## Metadata schema (v1)
+Store per chunk in SQLite: `id, file, language, symbol, kind, parent, hash, git_commit, start_line, end_line, imports, exports, embedding_model, last_indexed, checksum`. Define this once, up front — retrofitting new fields into an existing index later is painful.
+
+## Index versioning (v1)
+`.edhindex/version.json`, written on every index build:
+```json
+{
+  "schema": 1,
+  "embeddingModel": "nomic-v2",
+  "chunkStrategy": 1,
+  "createdAt": "2026-07-19T00:00:00Z",
+  "lastIndexed": "2026-07-19T00:00:00Z"
+}
+```
+On startup, compare this against the current build's expected values. Any mismatch (schema bump, model change, chunk strategy change) → trigger a full rebuild automatically rather than surfacing a confusing runtime error. This is the mechanism that makes "switching tiers requires a full re-index" (above) something the tool detects and handles, not something the user has to remember.
+
+## Incremental indexing (v1)
+Hash each file (SHA256). Chokidar triggers a check on save; only re-parse and re-embed if the hash actually changed. Don't re-embed unchanged files just because a save event fired.
+Also hash each chunk individually. When a file's hash changes, diff at the chunk level and only re-embed the chunks whose hash actually changed — not the whole file. A one-function edit in a 2,000-line file should cost one embedding call, not fifty.
+
+## Startup flow (v1)
+- No index found → full scan → build → ready
+- Existing index found → load it → compare hashes → update only what changed → ready
+
+## Ranking formula (v1)
+Top 30 BM25 candidates + top 30 vector candidates → deduplicate → rerank the merged set → return top 10 (configurable). Concrete numbers, not "combine and rerank" left vague. Full pipeline, in order:
+```
+Query
+  |
+Normalize
+  |
+BM25 search (top 30)  +  Vector search (top 30)
+  |
+Merge
+  |
+Deduplicate
+  |
+Rerank
+  |
+Top K (default 10)
+  |
+MCP response
+```
+
+## Embedding and storage abstraction (v1 — cheap now, expensive to retrofit later)
+Define interfaces, don't hardcode the concrete libraries:
+```
+EmbeddingProvider: embed(), dimensions(), name(), load(), dispose()
+VectorStore:       insert(), delete(), search(), compact()
+```
+Ship transformers.js and LanceDB as the default implementations of these interfaces. This is what lets you swap to Ollama, llama.cpp, Qdrant, or anything else later without rewriting the code that calls them.
+
+## Config file (v1)
+`.edhindex/config.json`:
+```json
+{
+  "model": "balanced",
+  "languages": ["ts", "js", "go", "py"],
+  "watch": true,
+  "rerank": true,
+  "maxResults": 10
+}
+```
+
+## Progress reporting (v1)
+Indexing must never look hung. Emit structured progress events (not just log lines) that a CLI progress bar or an MCP client can both consume — e.g. `{ phase: "scanning", current: 118, total: 624 }`, then `{ phase: "embedding", percent: 42 }`, then `{ phase: "building_fts" }`, then `{ phase: "ready" }`.
+
+## Cancellation (v1)
+Indexing must be safely interruptible (Ctrl+C, or an MCP-triggered stop). On interrupt: finish the file currently being processed, flush metadata to SQLite, close the DB cleanly, then exit. Never leave a half-written index — a killed process should produce either the old valid state or the new valid state, never something in between.
+
+## Logging levels (v1)
+Four levels, fixed from the start so an agent doesn't scatter ad hoc `console.log` calls: `silent`, `info` (default), `verbose`, `debug`. Configurable via CLI flag and config file.
+
+## CLI (v1)
+```
+edhindex init
+edhindex start
+edhindex index
+edhindex search <query>
+edhindex status
+edhindex config
+edhindex models
+edhindex doctor
+```
+`doctor` checks SQLite, LanceDB, the embedding model, the MCP server, disk space, permissions, and active file watchers. Build this in v1 — it pays for itself the very first time something breaks and you need to know where.
+
+## Security — non-negotiable, build this in from the start, not after
+- Never execute any indexed code
+- Never follow symlinks that point outside the selected workspace
+- Never transmit source code over the network — enforce this in code, not just as a policy, unless the user explicitly opts into a future remote embedding provider
+- Sanitize every path to prevent directory traversal
+- Restrict every MCP tool operation strictly to the indexed workspace — a calling agent should never be able to reach outside the folder it was pointed at
+
+This matters because once this runs as an MCP server, it can be driven by an autonomous agent acting on file contents it reads — path traversal and symlink escapes are the first thing that will get tried against a tool like this, intentionally or not.
+
+## MCP tools exposed (v1)
+`search_codebase` only. Everything else is v2.
+
+## Non-goals (v1)
+Explicit so an eager agent doesn't add any of these on its own initiative:
+- No chat interface
+- No code generation
+- No cloud sync
+- No telemetry
+- No authentication
+- No web UI
+- No editor integration
+- No remote database
+- No hosted service
+
+## Corrections worth keeping in mind
+- MCP was created by Anthropic (Nov 2024), not OpenAI — now an open, vendor-neutral standard under the Linux Foundation. Use `@modelcontextprotocol/sdk` or FastMCP.
+- `tiktoken` matches OpenAI's tokenizer specifically — treat any token counts here as approximate for other models.
+
+## Recommended stack (v1)
+Tree-sitter (AST), SQLite (metadata + FTS5), LanceDB (vectors), transformers.js (embeddings + reranker, local), chokidar (file watching), simple-git (git integration), MCP server (FastMCP or TypeScript SDK).
+
+Note: Language Server Protocol integration is intentionally **not** in v1. Tree-sitter alone (function/class/import/export boundaries) is enough for a strong index and search experience. LSP adds per-language server lifecycle management, installation, and cross-platform quirks — real complexity that isn't needed until the persisted symbol/call graph (v2) makes it worth it. Don't let an agent reach for LSP in v1.
+
+## Build order (v1)
+1. Repo scaffold, config file, CLI skeleton, ignore rules, file size limits
+2. AST indexing — Tree-sitter, chunking strategy, metadata schema, incremental hashing
+3. Embeddings and vector search — via the `EmbeddingProvider` interface, tier selection on first run
+4. Keyword search — SQLite FTS5
+5. Ranking — the top-30/top-30/dedupe/rerank/top-10 formula
+6. MCP server exposing `search_codebase`, with the security guardrails enforced here
+7. File watching and the cold-start/warm-start flow
+8. `doctor` command and basic recovery (if SQLite fails to open, rebuild from scratch rather than crash)
+
+## Success criteria (v1)
+v1 is done when all of the following hold:
+- Indexes a 100k-line repository successfully
+- Updates incrementally on file save, without a full re-index
+- Returns search results in a reasonable time on a warm index
+- Runs completely offline after the embedding model is downloaded
+- Emits zero network requests beyond that one-time model download
+- Recovers cleanly if `.edhindex/` is deleted (falls back to full scan)
+- Runs on Windows, macOS, and Linux
+- `search_codebase` works end to end through an MCP client
+
+(Hard performance numbers — search latency, index update time, cold start, memory ceiling — are deliberately a v2 tuning target, not a v1 gate. Don't block shipping v1 on numbers that haven't been measured yet.)
+
+---
+
+# V2 — deliberately deferred, don't touch until v1 works end to end
+
+- **Persisted symbol/call graph** (LSP-derived) — enables "expand from a chunk to its related symbols" as part of retrieval. This is the single biggest quality upgrade available, and also the most complex — earn it after the simpler retrieval loop is proven, not before.
+- **Additional MCP tools**: `find_symbol`, `find_references`, `find_definition`, `recent_changes`, `workspace_stats`, `reindex`, `index_status`
+- **Parallel indexing via worker threads** — only once you've actually confirmed indexing speed is a bottleneck on a real repo, not preemptively
+- **Additional languages** beyond the v1 four (Java, C#, Rust, C++, Kotlin, Swift)
+- **Formal test suite** as its own tracked effort — unit, integration, large-repo, corrupt-index, model-switch, recovery, watcher tests
+- **Sophisticated corruption recovery** — attempt repair before falling back to a full rebuild
+- **Full plugin system** — v1 already reserves the extension points via the two interfaces above; a real plugin loader can wait
+- **Performance target tuning** — search under 300ms, index update under 2s, cold startup under 10s, memory under 1GB. Good targets to measure against once v1 exists, not a blocker before it ships
+
+## Scope check
+This is the entire scope of EDHIndex: index a codebase, keep the index live, expose it over MCP, safely. It does not include an editor, a terminal, or a chat interface — those are separate projects, if built at all.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "edhindex",
+  "version": "1.0.0",
+  "description": "Local-first hybrid code search engine with MCP",
+  "type": "module",
+  "bin": {
+    "edhindex": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli/index.js",
+    "dev": "npx tsx src/cli/index.ts"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@lancedb/lancedb": "^0.31.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.11.1",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^15.0.0",
+    "simple-git": "^3.36.0",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "web-tree-sitter": "^0.26.11"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/cli-progress": "^3.11.6",
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/cli/commands/config_cmd.ts

@@ -0,0 +1,58 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadConfig, saveConfig, ModelTier, LogLevelConfig } from '../../config/index.js';
+import chalk from 'chalk';
+
+export function configCommand(rootPath: string, changes: Record<string, string>) {
+  const indexDir = join(rootPath, '.edhindex');
+
+  if (!existsSync(indexDir)) {
+    console.log(chalk.yellow('No .edhindex directory found. Run "edhindex init" first.'));
+    return;
+  }
+
+  const config = loadConfig(indexDir);
+
+  if (Object.keys(changes).length === 0) {
+    console.log(chalk.bold('Current configuration:'));
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+
+  for (const [key, value] of Object.entries(changes)) {
+    switch (key) {
+      case 'model':
+        if (!['light', 'balanced', 'max'].includes(value)) {
+          console.log(chalk.red(`Invalid model: ${value}. Must be light, balanced, or max.`));
+          return;
+        }
+        (config as any).model = value as ModelTier;
+        break;
+      case 'languages':
+        config.languages = value.split(',').map(s => s.trim());
+        break;
+      case 'watch':
+        config.watch = value === 'true';
+        break;
+      case 'rerank':
+        config.rerank = value === 'true';
+        break;
+      case 'maxResults':
+        config.maxResults = parseInt(value, 10) || 10;
+        break;
+      case 'logLevel':
+        if (!['silent', 'info', 'verbose', 'debug'].includes(value)) {
+          console.log(chalk.red(`Invalid logLevel: ${value}`));
+          return;
+        }
+        config.logLevel = value as LogLevelConfig;
+        break;
+      default:
+        console.log(chalk.yellow(`Unknown config key: ${key}`));
+    }
+  }
+
+  saveConfig(indexDir, config);
+  console.log(chalk.green('Configuration updated.'));
+  console.log(JSON.stringify(config, null, 2));
+}

package/src/cli/commands/doctor_cmd.ts

@@ -0,0 +1,31 @@
+import { runDoctor, DoctorResult } from '../../doctor/index.js';
+import chalk from 'chalk';
+
+export async function doctorCommand(rootPath: string, indexDir: string) {
+  console.log(chalk.bold('EDHIndex Diagnostics\n'));
+
+  const results = await runDoctor(rootPath, indexDir);
+
+  let okCount = 0;
+  let warnCount = 0;
+  let errorCount = 0;
+
+  for (const r of results) {
+    const icon = r.status === 'ok' ? chalk.green('✓') : r.status === 'warn' ? chalk.yellow('⚠') : chalk.red('✗');
+    console.log(`  ${icon} ${chalk.bold(r.category)}: ${r.message}`);
+    if (r.detail) console.log(`       ${chalk.dim(r.detail)}`);
+
+    if (r.status === 'ok') okCount++;
+    else if (r.status === 'warn') warnCount++;
+    else errorCount++;
+  }
+
+  console.log('');
+  if (errorCount > 0) {
+    console.log(chalk.red(`  ${errorCount} error(s), ${warnCount} warning(s), ${okCount} ok`));
+  } else if (warnCount > 0) {
+    console.log(chalk.yellow(`  ${warnCount} warning(s), ${okCount} ok`));
+  } else {
+    console.log(chalk.green(`  All ${okCount} checks passed.`));
+  }
+}

package/src/cli/commands/index_cmd.ts

@@ -0,0 +1,121 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { loadConfig, saveConfig, MODEL_CONFIGS } from '../../config/index.js';
+import { logger, setLogLevel, LogLevel } from '../../logging.js';
+import { emitProgress, onProgress } from '../../progress.js';
+import { loadVersion, saveVersion, getExpectedVersion, needsRebuild } from '../../version.js';
+import { MetadataStore } from '../../storage/metadata.js';
+import { FTSStore } from '../../storage/fts.js';
+import { TransformersEmbeddingProvider } from '../../embeddings/transformers.js';
+import { LanceDBStore } from '../../vector/lancedb.js';
+import { Indexer } from '../../indexer/indexer.js';
+import cliProgress from 'cli-progress';
+import chalk from 'chalk';
+
+export async function indexCommand(rootPath: string) {
+  const indexDir = join(rootPath, '.edhindex');
+  if (!existsSync(indexDir)) {
+    mkdirSync(indexDir, { recursive: true });
+  }
+
+  const config = loadConfig(indexDir);
+  const modelCfg = MODEL_CONFIGS[config.model];
+
+  setLogLevel(LogLevel.Info);
+
+  // Check version
+  const version = loadVersion(indexDir);
+  const fullRebuild = needsRebuild(version, config.model);
+
+  if (fullRebuild && version) {
+    console.log(chalk.yellow('Index version mismatch — full rebuild.'));
+  }
+
+  const metadataStore = new MetadataStore(indexDir);
+  const ftsStore = new FTSStore(indexDir);
+  const vectorStore = new LanceDBStore(indexDir, modelCfg.dimensions);
+  await vectorStore.init();
+
+  const embedder = new TransformersEmbeddingProvider(config.model);
+  console.log(chalk.dim('Loading embedding model...'));
+  await embedder.load();
+
+  const indexer = new Indexer({
+    config,
+    rootPath,
+    indexDir,
+    onIndex: async (result) => {
+      for (const chunk of result.chunks) {
+        metadataStore.upsertChunk({
+          id: chunk.id, file: chunk.file, language: chunk.language,
+          symbol: chunk.symbol, kind: chunk.kind, parent: chunk.parent,
+          hash: chunk.hash, git_commit: null,
+          start_line: chunk.startLine, end_line: chunk.endLine,
+          imports: chunk.imports.join('\n'), exports: chunk.exports.join('\n'),
+          embedding_model: embedder.name(), last_indexed: new Date().toISOString(),
+          checksum: chunk.hash,
+        });
+        ftsStore.insertChunk(chunk.id, chunk.content, chunk.file, chunk.symbol, chunk.language);
+      }
+      if (result.chunks.length > 0) {
+        const texts = result.chunks.map(c => c.content);
+        const embeddings = await embedder.embed(texts);
+        await vectorStore.insert(result.chunks.map((c, i) => ({
+          id: c.id, values: embeddings[i],
+          metadata: { file: c.file, symbol: c.symbol, kind: c.kind, text: c.content, language: c.language },
+        })));
+      }
+      metadataStore.upsertFileHash(result.relativePath, result.hash);
+    },
+    onDelete: async (chunkIds) => {
+      for (const id of chunkIds) ftsStore.deleteChunk(id);
+      await vectorStore.delete(chunkIds);
+    },
+  });
+
+  await indexer.initialize();
+
+  const progressBar = new cliProgress.SingleBar({
+    format: '{phase} | {bar} | {percentage}% | {value}/{total}',
+    barCompleteChar: '\u2588',
+    barIncompleteChar: '\u2591',
+    hideCursor: true,
+  });
+  progressBar.start(100, 0, { phase: 'Scanning' });
+  const unsub = onProgress((e) => {
+    if (e.phase === 'scanning' && e.total) {
+      progressBar.setTotal(e.total);
+      progressBar.update(e.current || 0);
+    } else if (e.phase === 'embedding' && e.percent !== undefined) {
+      progressBar.setTotal(100);
+      progressBar.update(e.percent);
+    }
+  });
+
+  const existingHashes = metadataStore.getAllFileHashes();
+  const doFull = fullRebuild || existingHashes.size === 0;
+
+  if (doFull) {
+    await indexer.runFullIndex();
+    const newVersion = getExpectedVersion(config.model);
+    saveVersion(indexDir, newVersion);
+  } else {
+    const existingChunkHashes = metadataStore.getAllChunkHashes();
+    await indexer.runIncremental(existingHashes, existingChunkHashes);
+    const ver = version!;
+    ver.lastIndexed = new Date().toISOString();
+    saveVersion(indexDir, ver);
+  }
+
+  progressBar.stop();
+  unsub();
+
+  const finalChunkCount = metadataStore.getChunkCount();
+  const finalFileCount = metadataStore.getFileCount();
+  console.log(chalk.green(`Index complete. ${finalChunkCount} chunks across ${finalFileCount} files.`));
+  console.log(chalk.dim(`Run "edhindex start" to serve the MCP server.`));
+
+  metadataStore.close();
+  ftsStore.close();
+  await vectorStore.close();
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,25 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { loadConfig, saveConfig, defaultConfig } from '../../config/index.js';
+import { logger } from '../../logging.js';
+import chalk from 'chalk';
+
+export async function initCommand(rootPath: string) {
+  const indexDir = join(rootPath, '.edhindex');
+
+  if (existsSync(indexDir)) {
+    console.log(chalk.yellow('EDHIndex is already initialized in this directory.'));
+    const config = loadConfig(indexDir);
+    console.log(`Current config: model=${config.model}, languages=[${config.languages.join(', ')}]`);
+    return;
+  }
+
+  mkdirSync(indexDir, { recursive: true });
+  const config = defaultConfig();
+  saveConfig(indexDir, config);
+
+  console.log(chalk.green('EDHIndex initialized.'));
+  console.log(`Index directory: ${indexDir}`);
+  console.log(`Configuration: model=${config.model}, languages=[${config.languages.join(', ')}]`);
+  console.log(chalk.dim('Run "edhindex start" to build the index and start the MCP server.'));
+}

package/src/cli/commands/models.ts

@@ -0,0 +1,19 @@
+import { MODEL_CONFIGS } from '../../config/index.js';
+import chalk from 'chalk';
+
+export function modelsCommand() {
+  console.log(chalk.bold('Available embedding models:\n'));
+
+  for (const [tier, cfg] of Object.entries(MODEL_CONFIGS)) {
+    const tag = tier === 'balanced' ? ' (default)' : '';
+    console.log(`  ${chalk.cyan(tier)}${chalk.dim(tag)}`);
+    console.log(`    Model:    ${cfg.displayName}`);
+    console.log(`    Size:     ${cfg.size}`);
+    console.log(`    Dims:     ${cfg.dimensions}`);
+    console.log(`    HF ID:    ${cfg.modelId}`);
+    console.log('');
+  }
+
+  console.log(chalk.dim('Switch models with: edhindex config model <tier>'));
+  console.log(chalk.dim('Note: Changing models requires a full re-index.'));
+}

package/src/cli/commands/search.ts

@@ -0,0 +1,44 @@
+import { join } from 'node:path';
+import { loadConfig, MODEL_CONFIGS } from '../../config/index.js';
+import { setLogLevel, LogLevel } from '../../logging.js';
+import { MetadataStore } from '../../storage/metadata.js';
+import { FTSStore } from '../../storage/fts.js';
+import { TransformersEmbeddingProvider } from '../../embeddings/transformers.js';
+import { LanceDBStore } from '../../vector/lancedb.js';
+import { SearchEngine } from '../../retrieval/search.js';
+import chalk from 'chalk';
+
+export async function searchCommand(rootPath: string, query: string, maxResults: number) {
+  const indexDir = join(rootPath, '.edhindex');
+  setLogLevel(LogLevel.Silent);
+
+  const config = loadConfig(indexDir);
+  const modelCfg = MODEL_CONFIGS[config.model];
+
+  const metadataStore = new MetadataStore(indexDir);
+  const ftsStore = new FTSStore(indexDir);
+  const vectorStore = new LanceDBStore(indexDir, modelCfg.dimensions);
+  await vectorStore.init();
+
+  const embedder = new TransformersEmbeddingProvider(config.model);
+  await embedder.load();
+
+  const engine = new SearchEngine(ftsStore, metadataStore, vectorStore, embedder, null, false);
+  const results = await engine.search({ query, maxResults });
+
+  if (results.length === 0) {
+    console.log(chalk.yellow('No results found.'));
+  } else {
+    for (const r of results) {
+      const tag = r.matchType === 'keyword' ? chalk.blue('KW') : r.matchType === 'vector' ? chalk.magenta('VEC') : chalk.green('HYB');
+      console.log(`${tag} ${chalk.cyan(`${r.file}:${r.startLine}-${r.endLine}`)} (${r.language})`);
+      if (r.symbol) console.log(`    ${chalk.dim('Symbol:')} ${r.symbol}${r.kind ? ` (${r.kind})` : ''}`);
+      console.log(`    ${chalk.dim('Score:')} ${r.score.toFixed(4)}`);
+      console.log('');
+    }
+  }
+
+  metadataStore.close();
+  ftsStore.close();
+  await vectorStore.close();
+}