codemogger

Code indexing library for AI coding agents. Parses source code with tree-sitter, chunks it into semantic units (functions, structs, classes, impl blocks), embeds them locally, and stores everything in a single SQLite file with vector + full-text search.

No Docker, no server, no API keys. One .db file per codebase.

Why

Coding agents need to understand codebases. They need to find where things are defined, discover how concepts are implemented across files, and navigate unfamiliar code quickly. This requires both keyword search (precise identifier lookup) and semantic search (natural language queries when you don't know the exact names).

As AI coding tools become more composable - agents calling agents, MCP servers plugging into different hosts - this capability needs to exist as a library that runs locally. No external servers, no API keys, no Docker containers. Just a function call that returns results.

codemogger is that library. Embedded SQLite (via Turso) with FTS + vector search in a single .db file.

Install

npm install -g codemogger

Or use npx to run without installing.

Quick start

# Index a project
codemogger index ./my-project

# Search
codemogger search "authentication middleware"

Add to your coding agent's MCP config (Claude Code, OpenCode, etc.):

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

The MCP server exposes three tools:

• codemogger_search - semantic and keyword search over indexed code

• codemogger_index - index a codebase for the first time

• codemogger_reindex - update the index after modifying files

Add the local db to .gitignore:

# codemogger db
.codemogger/

SDK

codemogger is also usable as a library. The SDK has no model dependency - you provide your own embedding function:

import { CodeIndex } from "codemogger"
import { pipeline } from "@huggingface/transformers"

// Load embedding model (runs locally, no API keys)
const extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", { dtype: "q8" })

const embedder = async (texts: string[]): Promise<number[][]> => {
  const output = await extractor(texts, { pooling: "mean", normalize: true })
  return output.tolist() as number[][]
}

const db = new CodeIndex({
  dbPath: "./my-project.db",
  embedder,
  embeddingModel: "all-MiniLM-L6-v2",
})

await db.index("/path/to/project")

// Semantic: "what does this codebase do?"
const results = await db.search("authentication middleware", { mode: "semantic" })

// Keyword: precise identifier lookup
const results = await db.search("BTreeCursor", { mode: "keyword" })

await db.close()

The MCP server and CLI ship with all-MiniLM-L6-v2 by default.

CLI

# Install globally
npm install -g codemogger

# Index a directory
codemogger index ./my-project

# Search
codemogger search "authentication middleware"

# List indexed codebases
codemogger list

How it works

1. Scan - walk directory, respect .gitignore, detect language from extension

2. Chunk - parse each file with tree-sitter (WASM), extract top-level definitions (functions, structs, classes, impl blocks). Items >150 lines are split into sub-items.

3. Embed - encode each chunk with the provided embedding model (runs locally, no API)

4. Store - write chunks + embeddings to SQLite with FTS index

5. Search - vector cosine similarity (semantic) or FTS with weighted fields (keyword)

Incremental: only changed files (by SHA-256 hash) are re-processed on subsequent runs.

Languages

Rust, C, C++, Go, Python, Zig, Java, Scala, JavaScript, TypeScript, TSX, PHP, Ruby.

Benchmarks

Benchmarked on 4 real-world codebases on an Apple M2 (8GB). Each project uses its own isolated database. Embeddings use vector8 (int8 quantized, 395 bytes/chunk vs 1,536 for float32). Embedding model: all-MiniLM-L6-v2 (q8 quantized, local CPU). Search times are p50 over 3 runs.

Performance

Keyword search is 25x-370x faster than ripgrep and returns precise definitions instead of thousands of file matches.

Indexing is a one-time cost dominated by embedding (~97% of time). Subsequent runs only re-embed changed files.

Search quality: semantic search vs ripgrep

The real advantage isn't speed - it's finding the right code when you don't know the exact keywords.

"write-ahead log replication and synchronization" (Turso)

"SQL statement parsing and compilation" (Turso)

"HTTP request parsing and response writing" (Bun)

"scheduling pods to nodes based on resource requirements" (Kubernetes)

"container health check probes and restart policy" (Kubernetes)

ripgrep matches thousands of files on common keywords. codemogger returns the 5 most relevant definitions.

Architecture

• Bun/TypeScript runtime

• tree-sitter (WASM) for AST-aware chunking - 13 language grammars

• all-MiniLM-L6-v2 for local embeddings (384 dimensions, q8 quantized)

• Turso for storage - embedded SQLite with FTS + vector search extensions

• Single DB file stores multiple codebases with per-codebase FTS tables and global vector search

License

MIT