CodeLens MCP
Agent-native code intelligence server with bounded workflows, precise fallback, and auditable releases.
If you are preparing automation or host configs for the eventual cutover, use the host-by-host migration guide: docs/migrate-from-codelens.md.
Pure Rust MCP server for multi-agent harnesses with hybrid retrieval (tree-sitter + semantic), mutation-gated refactoring, token compression, and enterprise-ready observability. The binary statically links SQLite, the vector store, and the ONNX runtime, so no external daemons or service installs are required for the core retrieval and mutation surfaces. Semantic search additionally needs a sidecar model directory (~80 MB ONNX) — GitHub Release tarballs bundle it automatically, but users installing via cargo install codelens-mcp must point CODELENS_MODEL_DIR at a separately-fetched model payload (see the Install Channel Matrix).
Surface Snapshot
- Workspace version:
1.13.32
- Workspace members:
2 (crates/codelens-engine, crates/codelens-mcp)
- Registered tool definitions:
87
- Tool output schemas:
55 / 87
- Supported language families:
30 across 49 extensions
- Profiles:
planner-readonly (36), builder-minimal (35), reviewer-graph (40), evaluator-compact (36), refactor-full (35), ci-audit (40), workflow-first (36)
- Presets:
minimal (20), balanced (74), full (87)
- Canonical manifest:
docs/generated/surface-manifest.json
The Problem
Multi-agent coding harnesses fail when every agent sees too many tools, too much raw code, and too many intermediate results. Tokens get burned on tools/list, repeated file reads, and low-value raw graph expansion.
The Solution
CodeLens maintains a live, indexed understanding of your codebase and exposes it as a harness optimization layer. The model asks a precise question and gets a bounded answer with a handle for deeper expansion only when needed.
Without CodeLens With CodeLens (with semantic feature on)
────────────────────────────────────────────────────────────────────────────────────────────
Read file + grep references → 4,600 tokens get_impact_analysis → 1,500 tokens (67% saved)
Read manifest + entry + files → 5,000 tokens onboard_project → 660 tokens (87% saved)
Read + grep × 3 files → 3,200 tokens get_ranked_context → 800 tokens (75% saved)
Measured with tiktoken (cl100k_base) on real projects with --features semantic enabled and the bundled CodeSearchNet model loaded. Reproducible via benchmarks/token-efficiency.py. The default crates.io build (BM25 + AST only) still hits the bounded-output and workflow-shape benefits but does not run the hybrid semantic ranker.
Quick Install
Default (BM25 + AST + call-graph, no model sidecar) — works out of the box, no extra setup:
cargo install codelens-mcp
Hybrid retrieval (semantic + bundled CodeSearchNet model) — pick one:
# Option A: GitHub Release tarball — model is bundled and verified in CI.
curl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash
# Option B: cargo install with the semantic feature, then point CODELENS_MODEL_DIR at a model
# payload (the model is not on crates.io due to the 10 MB cap).
cargo install codelens-mcp --features semantic
export CODELENS_MODEL_DIR=/path/to/codesearch/model
# Option C: Homebrew tap (macOS / Linux) — release-tarball-equivalent
brew install mupozg823/tap/codelens-mcp
HTTP daemon mode — add --features http to either path above. Source builds:
cargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp
cargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp --features semantic,http
The default cargo install codelens-mcp build was switched to default = [] in 1.10.0 (ADR-0012) so a fresh install boots without the ~80 MB ONNX sidecar. Existing users running cargo install --force will see the change in the startup banner.
