Documentation

Getting Started

LENS is an open-source code intelligence engine. It indexes your codebase locally and serves structural context to AI agents via MCP or CLI. No API keys, no cloud, fully deterministic. Currently supports TypeScript/JavaScript with a pluggable parser architecture for adding more languages.

Install

Requires Node.js 20+.

$ npm install -g lens-engine

Quick Start

Three commands. lens register handles everything — indexes files via TF-IDF, builds the import graph, and analyzes git history. One pass.

Example Session

$ lens daemon start
LENS daemon running on http://localhost:4111
$ lens register .
Registered: my-project
Scanning files... 847 files
Building import graph... done
Analyzing git history... done
Index complete in 2.3s
$ lens grep "auth|middleware|session"
[auth] 8 results
  src/middleware/auth.ts  [hub]  0.94
    importers: routes/login.ts, routes/api.ts
  src/lib/tokens.ts             0.87
    importers: middleware/auth.ts

What It Does

Every search query runs through a multi-stage pipeline. Your code never leaves your machine.

1. 1

   Diff Scan

   Detects changed files since last index. Only re-processes what changed — full re-index on first run, incremental after.

2. 2

   TF-IDF Scoring

   Tokenizes file content, path segments, exports, and docstrings. Applies code-domain stopwords (import, export, const, etc.) so real signal isn't diluted.

3. 3

   Concept Expansion

   Static synonyms + repo-specific vocab expand your query. "auth" matches verifyToken, sessionMiddleware, loginHandler — even if those words never appear in your prompt.

4. 4

   Import Graph

   Builds a directed graph of every import/require. Hub files (imported by many) get boosted. Surfaces dependencies that text search misses.

5. 5

   Git Co-Change

   Analyzes commit history for files that change together. Catches cross-cutting concerns — like a test file that always moves with its source — that text search misses entirely.

6. 6

   Cache

   Auto-reindex on git HEAD change. Under 1s cold queries, near-instant for unchanged repos.

Language Support

LENS uses a pluggable parser registry. Each language parser extracts imports, exports, symbols, and call sites to build the structural graph.

Benchmarks & Findings

We ran controlled A/B benchmarks across multiple repos (32-2000+ files) to measure what LENS actually does for AI agents. Here's what we found — the good and the honest.

What works

• ++15.8pp on unfamiliar repos — when agents explore a codebase they've never seen, pre-injected LENS context improved answer accuracy by 15.8 percentage points vs baseline.
• +Sub-second queries — ranked results return under 1s cold. The pipeline (TF-IDF, import graph, co-change, concept expansion) runs entirely local.
• +Co-change catches what grep misses — git history analysis surfaces files that always change together (e.g. a service + its test + its migration). No keyword overlap needed.
• +Import graph traversal — dependency walking finds structural relationships that flat file search can't.

What we learned

• ~Agents are good at grep — on tasks with obvious search keywords, agents score equally well with or without LENS. Grep + Glob is already effective for keyword-rich tasks.
• ~MCP tool adoption is hard — agents tend to default to built-in tools (Grep, Glob, Read) regardless of tool descriptions. LENS MCP tools work best when explicitly referenced in CLAUDE.md instructions.
• ~Value scales with unfamiliarity — LENS helps most when the agent (or developer) doesn't know where to start. On repos you work in daily, you already know the right files. On new codebases, LENS's structural ranking provides real signal.

MCP Integration

LENS exposes 4 MCP tools via HTTP Streamable transport. Add a single entry to your project's .mcp.json and the daemon handles the rest. The daemon must be running (lens daemon start).

Claude Code, Cursor, and any MCP-compatible agent reads .mcp.json on startup and calls LENS tools autonomously.

.mcp.json

{
  "mcpServers": {
    "lens": {
      "type": "http",
      "url": "http://localhost:4111/mcp"
    }
  }
}

Exposed MCP Tools

Daemon Mode

The daemon runs on port 4111 and serves the REST API, MCP endpoint, and local dashboard. Data is stored at ~/.lens/ (SQLite for index + traces).

Example Session

$ lens daemon start
LENS daemon running on http://localhost:4111
$ lens dashboard
Opening http://localhost:4111
$ lens status
LENS v2.0.0 — running
Uptime: 3h 42m
URL: http://localhost:4111