{"id":48748978,"url":"https://github.com/mupozg823/codelens-mcp-plugin","last_synced_at":"2026-04-21T08:01:11.228Z","repository":{"id":347318067,"uuid":"1192747748","full_name":"mupozg823/codelens-mcp-plugin","owner":"mupozg823","description":"Harness-native compressed context engine for AI coding agents — Pure Rust MCP server, 89+ tools, 25 languages, 50-87% token reduction","archived":false,"fork":false,"pushed_at":"2026-04-20T15:13:02.000Z","size":61492,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T17:25:09.974Z","etag":null,"topics":["agent-harness","ai-tools","claude-code","code-intelligence","codex","cursor","developer-tools","harness","lsp","mcp","mcp-server","rust","semantic-search","token-optimization","tree-sitter"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/codelens-mcp","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mupozg823.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-26T14:21:33.000Z","updated_at":"2026-04-19T00:16:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mupozg823/codelens-mcp-plugin","commit_stats":null,"previous_names":["mupozg823/codelens-mcp-plugin"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/mupozg823/codelens-mcp-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mupozg823%2Fcodelens-mcp-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mupozg823%2Fcodelens-mcp-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mupozg823%2Fcodelens-mcp-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mupozg823%2Fcodelens-mcp-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mupozg823","download_url":"https://codeload.github.com/mupozg823/codelens-mcp-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mupozg823%2Fcodelens-mcp-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32082780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-harness","ai-tools","claude-code","code-intelligence","codex","cursor","developer-tools","harness","lsp","mcp","mcp-server","rust","semantic-search","token-optimization","tree-sitter"],"created_at":"2026-04-12T15:13:49.271Z","updated_at":"2026-04-21T08:01:11.218Z","avatar_url":"https://github.com/mupozg823.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n\n# CodeLens MCP \n\n**Agent-native code intelligence server with bounded workflows, precise fallback, and auditable releases.**\n\n\nIf you are preparing automation or host configs for the eventual cutover, use the host-by-host migration guide: [`docs/migrate-from-codelens.md`](docs/migrate-from-codelens.md).\n\nPure Rust MCP server for multi-agent harnesses with hybrid retrieval (tree-sitter + semantic), mutation-gated refactoring, token compression, and enterprise-ready observability — all in a single self-contained binary, no external daemons or service installs required (the binary statically links its dependencies and ships its own SQLite, vector store, and ONNX runtime).\n\n[![CI](https://github.com/mupozg823/codelens-mcp-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/mupozg823/codelens-mcp-plugin/actions)\n[![crates.io](https://img.shields.io/crates/v/codelens-mcp.svg)](https://crates.io/crates/codelens-mcp)\n[![docs.rs](https://docs.rs/codelens-engine/badge.svg)](https://docs.rs/codelens-engine)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Downloads](https://img.shields.io/crates/d/codelens-mcp.svg)](https://crates.io/crates/codelens-mcp)\n\n\u003c/div\u003e\n\n\u003c!-- SURFACE_MANIFEST_README_SNAPSHOT:BEGIN --\u003e\n## Surface Snapshot\n\n- Workspace version: `1.9.46`\n- Workspace members: `3` (`crates/codelens-engine`, `crates/codelens-mcp`, `crates/codelens-tui`)\n- Registered tool definitions: `111`\n- Tool output schemas: `77 / 111`\n- Supported language families: `30` across `49` extensions\n- Profiles: `planner-readonly` (35), `builder-minimal` (36), `reviewer-graph` (35), `evaluator-compact` (14), `refactor-full` (49), `ci-audit` (43), `workflow-first` (19)\n- Presets: `minimal` (27), `balanced` (78), `full` (111)\n- Canonical manifest: [`docs/generated/surface-manifest.json`](docs/generated/surface-manifest.json)\n\u003c!-- SURFACE_MANIFEST_README_SNAPSHOT:END --\u003e\n\n---\n\n## The Problem\n\nMulti-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.\n\n## The Solution\n\nCodeLens 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.\n\n```\nWithout CodeLens                                    With CodeLens\n─────────────────────────────────────────────────────────────────\nRead file + grep references   → 4,600 tokens       get_impact_analysis    → 1,500 tokens  (67% saved)\nRead manifest + entry + files → 5,000 tokens       onboard_project        →   660 tokens  (87% saved)\nRead + grep × 3 files         → 3,200 tokens       get_ranked_context     →   800 tokens  (75% saved)\n```\n\n\u003e Measured with tiktoken (cl100k_base) on real projects. Reproducible via `benchmarks/token-efficiency.py`.\n\n## Quick Install\n\n```bash\n# From crates.io (recommended for stdio; add `--features http` for shared daemon mode)\ncargo install codelens-mcp\n\n# From crates.io with HTTP transport enabled\ncargo install codelens-mcp --features http\n\n# Homebrew (macOS / Linux)\nbrew install mupozg823/tap/codelens-mcp\n\n# GitHub installer (prebuilt release binary)\ncurl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash\n\n# From source\ncargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp\n\n# From source with HTTP transport enabled\ncargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp --features http\n```\n\nLatest release: [v1.9.35](https://github.com/mupozg823/codelens-mcp-plugin/releases/tag/v1.9.35)\n\n### Install Channel Matrix\n\n| Channel                                      | What you get                                                     | Good for                                             | Extra install needed?                                                          |\n| -------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ |\n| `cargo install codelens-mcp`                 | crates.io package version, stdio-first default build             | Single-agent local MCP sessions                      | Add `--features http` if you want shared HTTP daemons                          |\n| `cargo install codelens-mcp --features http` | crates.io package version with HTTP transport                    | Shared daemon mode from crates.io                    | No extra CodeLens package, but you still need the host client config           |\n| GitHub Releases / installer / Homebrew       | latest tagged release binary, built in CI with `--features http` | Tagged release users who want HTTP without compiling | No extra CodeLens build; semantic still needs a model sidecar or airgap bundle |\n| `cargo install --git ...` or source build    | current repository HEAD                                          | Unreleased features on `main` / branch testing       | No extra package, but you compile locally                                      |\n\nImportant:\n\n- `CodeLens standalone` means the `codelens-mcp` binary itself. Basic stdio MCP use needs only that binary plus host MCP config.\n- `Shared HTTP + multi-agent coordination` still uses the same binary, but the binary must include the `http` feature and the clients must attach by URL.\n- If a feature is mentioned in this repository but not present in your installed binary, compare `codelens-mcp --version` with the latest GitHub release and your install channel before assuming a bug.\n\n## Setup\n\n### Claude Code / Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"codelens\": {\n      \"command\": \"codelens-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Shared HTTP Daemon (Multi-Agent)\n\nRunning every editor or agent as its own stdio subprocess spawns **one `codelens-mcp` instance per session**, each with its own index and embedding state. Measured on a typical developer laptop with Claude Code + Codex Desktop + Cursor attached to the same project, this adds up to **200–300 MB** of duplicated resident memory for effectively the same data. The HTTP daemon collapses that into a single shared process.\n\nIf you installed from crates.io or built from source and need HTTP transport, make sure the binary was built with the `http` feature. The prebuilt release assets and the installer fallback should ship HTTP support.\n\nMinimal setup:\n\n```bash\n# Start once, keep running in the background\ncodelens-mcp /path/to/project --transport http --profile reviewer-graph --daemon-mode read-only --port 7837\n\n# Optional: a second daemon scoped for refactor-capable agents\ncodelens-mcp /path/to/project --transport http --profile refactor-full --daemon-mode mutation-enabled --port 7838\n```\n\nThose ports are the public generic example. In this repository's local launchd\nworkflow, the repo-local dual-daemon installer uses `:7839` for the read-only\ndaemon and `:7838` for the mutation daemon.\n\nEvery MCP client then attaches by URL instead of spawning a subprocess:\n\n```json\n{\n  \"mcpServers\": {\n    \"codelens\": { \"type\": \"http\", \"url\": \"http://127.0.0.1:7837/mcp\" }\n  }\n}\n```\n\nIf you are following this repository's local launchd workflow, replace the\nread-only example URL above with `http://127.0.0.1:7839/mcp`. The `:7837`\naddress remains the public generic example used throughout this section.\n\n#### When to prefer HTTP vs stdio\n\n| Situation                                            | Transport                 | Why                                                                    |\n| ---------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------- |\n| Single-agent, ephemeral sessions                     | stdio                     | Zero setup, auto-lifecycle, no port management                         |\n| 2+ agents (Claude + Codex + Cursor) on the same repo | **HTTP**                  | One shared index, 100–200 MB saved per extra agent                     |\n| Long-running agent or automation loop                | **HTTP**                  | Avoids cold-start on every session                                     |\n| CI / one-shot script                                 | stdio                     | `--oneshot` matches short-lived commands                               |\n| Mutation-heavy workflow needing isolation            | **HTTP with two daemons** | Read-only port for planners, mutation-enabled port for refactor agents |\n\nFor shared HTTP deployments, treat CodeLens coordination as advisory evidence rather than a central lock manager. The practical pattern is: bootstrap with `prepare_harness_session`, register intent with `register_agent_work`, claim mutation targets with `claim_files`, and let `verify_change_readiness` surface `overlapping_claims` as a `caution` signal before edits.\n\nWhat the standalone binary does and does not cover:\n\n- `CodeLens only` is enough for stdio use, HTTP daemon use, role-based surfaces, mutation gates, and coordination tools.\n- `Semantic retrieval` needs a model sidecar (`CODELENS_MODEL_DIR/codesearch/model.onnx`) or an air-gapped bundle.\n- `SCIP precise navigation` needs a binary built with `--features scip-backend` and an external SCIP index.\n- `Claude -\u003e Codex` live delegation is not a CodeLens feature. It additionally needs Claude configured with a `codex` MCP server and a working Codex CLI install.\n\nRecommended operating policy:\n\n- one mutation-enabled agent per worktree\n- additional agents stay planner/reviewer/read-only on the same daemon\n- use `codelens://activity/current` to inspect active sessions, recent intent, and advisory file claims\n\n#### Troubleshooting\n\n- **`Failed to reconnect` on the client** — the daemon likely exited or the configured URL/port is wrong. Verify with `curl \u003cconfigured-mcp-url\u003e`; for this repository's local launchd workflow that is usually `http://127.0.0.1:7839/mcp` for read-only and `http://127.0.0.1:7838/mcp` for mutation.\n- **Stale index warning on first attach** — expected when the watcher hasn't caught up after a daemon restart. Call `refresh_symbol_index` via MCP once, or restart the daemon with the project root as its CWD.\n- **Host config sanity check** — `codelens-mcp doctor \u003chost\u003e` (or `codelens-mcp status \u003chost\u003e`) inspects the host-native files and tells you whether the CodeLens entry is attached exactly, customized, missing, or needs manual review. Add `--json` when another script or host automation needs a machine-readable report.\n- **Broken or stale `~/.local/bin/codelens-mcp`** — if `cargo clean` removed the repo build a symlink points at, or if PATH still resolves to an older cargo-installed binary that does not know newer subcommands like `doctor` / `status`, run `bash scripts/sync-local-bin.sh .` to rebuild and re-link the local checkout, or `cargo install --path crates/codelens-mcp --force` to install a fresh standalone binary under `~/.cargo/bin/`.\n- **Multiple daemons listening on the same port** — only one will actually bind; the rest exit immediately. Check the actual configured port, for example `lsof -iTCP:7839 -sTCP:LISTEN` or `lsof -iTCP:7838 -sTCP:LISTEN` in this repository's local launchd workflow.\n- **Health check** — `scripts/mcp-doctor.sh . --strict` verifies that the configured transport matches an actual attach.\n\n#### Auto-start on macOS (launchd)\n\nFor this repository, prefer the installer script over hand-editing plist files:\n\n```bash\nbash scripts/install-http-daemons-launchd.sh . --load\n```\n\nThat installs two repo-local launchd agents from a current `--features http`\nbuild:\n\n- `dev.codelens.mcp-readonly` -\u003e `reviewer-graph` on `:7839`\n- `dev.codelens.mcp-mutation` -\u003e `refactor-full` on `:7838`\n\nIt also updates `.codelens/config.json` with repo-local `host_attach` URL\noverrides so `codelens-mcp attach`, `status`, and `doctor` reuse the same\nhost-to-daemon contract.\n\nGeneric single-daemon example, if you want to hand-edit a plist instead of\nusing the installer above:\n\n```xml\n\u003c!-- ~/Library/LaunchAgents/dev.codelens.mcp.plist --\u003e\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cplist version=\"1.0\"\u003e\u003cdict\u003e\n  \u003ckey\u003eLabel\u003c/key\u003e            \u003cstring\u003edev.codelens.mcp\u003c/string\u003e\n  \u003ckey\u003eProgramArguments\u003c/key\u003e \u003carray\u003e\n    \u003cstring\u003e/Users/you/.local/bin/codelens-mcp\u003c/string\u003e\n    \u003cstring\u003e/Users/you/your-project\u003c/string\u003e\n    \u003cstring\u003e--transport\u003c/string\u003e\u003cstring\u003ehttp\u003c/string\u003e\n    \u003cstring\u003e--profile\u003c/string\u003e\u003cstring\u003ereviewer-graph\u003c/string\u003e\n    \u003cstring\u003e--daemon-mode\u003c/string\u003e\u003cstring\u003eread-only\u003c/string\u003e\n    \u003cstring\u003e--port\u003c/string\u003e\u003cstring\u003e7837\u003c/string\u003e\n  \u003c/array\u003e\n  \u003ckey\u003eRunAtLoad\u003c/key\u003e        \u003ctrue/\u003e\n  \u003ckey\u003eKeepAlive\u003c/key\u003e        \u003ctrue/\u003e\n  \u003ckey\u003eStandardOutPath\u003c/key\u003e  \u003cstring\u003e/tmp/codelens-mcp.out.log\u003c/string\u003e\n  \u003ckey\u003eStandardErrorPath\u003c/key\u003e\u003cstring\u003e/tmp/codelens-mcp.err.log\u003c/string\u003e\n\u003c/dict\u003e\u003c/plist\u003e\n```\n\n```bash\nlaunchctl load ~/Library/LaunchAgents/dev.codelens.mcp.plist\nlaunchctl list | grep codelens   # confirm it's running\n```\n\nFor the separate daily aggregate audit snapshot, install the operator job with:\n\n```bash\nbash scripts/install-eval-session-audit-launchd.sh . --hour 23 --minute 55\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.codelens.eval-session-audit.codelens-mcp-plugin.plist\n```\n\nThat scheduled job keeps JSON snapshots as the canonical history and refreshes\n`.codelens/reports/daily/latest-summary.md` plus\n`.codelens/reports/daily/latest-gate.md` after each run by default.\n\nFor an ad hoc operator snapshot without launchd, run:\n\n```bash\nbash scripts/export-eval-session-audit.sh\nbash scripts/export-eval-session-audit.sh --format markdown\nbash scripts/export-eval-session-audit.sh --history-summary-path .codelens/reports/daily/latest-summary.md\nbash scripts/export-eval-session-audit.sh --history-gate-path .codelens/reports/daily/latest-gate.md\n```\n\nTo summarize recent daily snapshots into a drift/trend report, run:\n\n```bash\nbash scripts/summarize-eval-session-audit-history.sh\nbash scripts/summarize-eval-session-audit-history.sh --limit 7\n```\n\nTo turn that history into an operator `pass` / `warn` / `fail` verdict, run:\n\n```bash\nbash scripts/eval-session-audit-operator-gate.sh\nbash scripts/eval-session-audit-operator-gate.sh --fail-on-warn\n```\n\nIf `.codelens/eval-session-audit-gate.json` exists, the gate script loads it\nautomatically. CLI flags and env vars still override the repo-local policy.\n\nThe export script can also refresh that gate artifact automatically after each\nJSON snapshot, so scheduled operators do not need a second wrapper job just to\nkeep `latest-gate.md` current.\n\nSee [docs/platform-setup.md](docs/platform-setup.md) for Codex, Windsurf, VS Code, and other platforms.\n\n### Distribution Channels\n\n| Channel          | Delivery                                  | Notes                                            |\n| ---------------- | ----------------------------------------- | ------------------------------------------------ |\n| crates.io        | `cargo install codelens-mcp`              | Standard Rust install path                       |\n| Homebrew tap     | `brew install mupozg823/tap/codelens-mcp` | macOS/Linux package install                      |\n| GitHub Releases  | prebuilt archives                         | `darwin-arm64`, `linux-x86_64`, `windows-x86_64` |\n| installer script | `install.sh`                              | Convenience bootstrap for release assets         |\n| source build     | `cargo build --release`                   | Custom feature builds and local hacking          |\n\n## Why CodeLens?\n\n|                       | CodeLens                             | Read/Grep baseline           |\n| --------------------- | ------------------------------------ | ---------------------------- |\n| **Token cost**        | 50-87% less                          | Full file content every time |\n| **Context quality**   | Ranked, bounded, structured          | Raw text, no prioritization  |\n| **Multi-file impact** | 1 tool call                          | 5-10 grep + read cycles      |\n| **Runtime**           | Single Rust binary, \u003c12ms cold start | N/A                          |\n| **Language support**  | Generated from the surface manifest  | N/A                          |\n| **Agent awareness**   | Doom-loop detection, mutation gates  | None                         |\n\n## Key Features\n\n### Problem-First Workflows\n\nInstead of starting from the full raw tool registry, begin with the workflow-first entrypoints:\n\n| Workflow                | Tool                      | When                                  |\n| ----------------------- | ------------------------- | ------------------------------------- |\n| Explore codebase        | `explore_codebase`        | First look or targeted context search |\n| Trace execution         | `trace_request_path`      | Follow request or symbol flow         |\n| Audit architecture      | `review_architecture`     | Boundaries, coupling, module shape    |\n| Plan safe refactor      | `plan_safe_refactor`      | Preview rename/refactor risk first    |\n| Review changes          | `review_changes`          | Diff-aware pre-merge review           |\n| Diagnose issues         | `diagnose_issues`         | File, symbol, or directory diagnosis  |\n| Cleanup duplicate logic | `cleanup_duplicate_logic` | Duplicate or removable logic cleanup  |\n\n### Role-Based Surfaces\n\n| Profile            | Tools Visible                  | Use Case                                        |\n| ------------------ | ------------------------------ | ----------------------------------------------- |\n| `planner-readonly` | Workflow-first                 | Planner/architect context compression           |\n| `builder-minimal`  | Workflow-first                 | Implementation with focused Codex/agent surface |\n| `reviewer-graph`   | Review-heavy                   | Graph-aware review and risk analysis            |\n| `refactor-full`    | Preview-first + gated mutation | Safe refactors                                  |\n| `ci-audit`         | Machine-oriented               | CI/CD review and report emission                |\n\n### Adaptive Token Compression\n\n5-stage budget-aware compression automatically adjusts response size:\n\n- **Stage 1** (\u003c75% budget): Full detail pass-through\n- **Stage 2-3** (75-95%): Structured summarization\n- **Stage 4-5** (\u003e95%): Skeleton + truncation with expansion handles\n\n### Analysis Handles\n\nHeavy reports run as durable async jobs. Agents poll for completion and expand only needed sections:\n\n```\nstart_analysis_job → get_analysis_job → get_analysis_section(\"impact\")\n```\n\n### Mutation Safety\n\nRefactor flows require verification before code changes:\n\n```\nverify_change_readiness → \"ready\" → rename_symbol\n                        → \"blocked\" → fix blockers first\n```\n\n## Language Support\n\n\u003c!-- SURFACE_MANIFEST_README_LANGUAGES:BEGIN --\u003e\nCanonical parser families (30): C, Clojure/ClojureScript, C++, C#, CSS, Dart, Erlang, Elixir, Go, Haskell, HTML, Java, Julia, JavaScript, Kotlin, Lua, OCaml, PHP, Python, R, Ruby, Rust, Scala, Bash/Shell, Swift, TOML, TypeScript, TSX/JSX, YAML, Zig\n\nImport-graph capable families: C, C++, C#, CSS, Dart, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Scala, Swift, TypeScript, TSX/JSX\n\nThe canonical family/extension inventory is generated from `codelens_engine::lang_registry` and published in [`docs/generated/surface-manifest.json`](docs/generated/surface-manifest.json).\n\u003c!-- SURFACE_MANIFEST_README_LANGUAGES:END --\u003e\n\n## Performance\n\n| Operation              | Time  | Backend                 |\n| ---------------------- | ----- | ----------------------- |\n| `find_symbol`          | \u003c1ms  | SQLite FTS5             |\n| `get_symbols_overview` | \u003c1ms  | Cached                  |\n| `get_ranked_context`   | ~20ms | 4-signal hybrid ranking |\n| `get_impact_analysis`  | ~1ms  | Graph cache             |\n| Cold start             | ~12ms | No LSP boot needed      |\n\n## Semantic Search\n\nOptional embedding-based code search (feature-gated: `semantic`):\n\n- **Sidecar MiniLM-L12 CodeSearchNet** model (ONNX INT8) — load from `CODELENS_MODEL_DIR` or next to the binary\n- Hybrid ranking: semantic supplements structural in `get_ranked_context`\n- 2-tier NL→code bridging: generic core (15 entries) + auto-generated project bridges (`.codelens/bridges.json`)\n- Multi-language test symbol filtering: Python, JS/TS, Go, Java, Kotlin, Ruby\n\n### Retrieval Quality\n\nSelf-benchmark re-measured on commit `26d513e` (v1.9.32, 2026-04-17), model `MiniLM-L12-CodeSearchNet-INT8` (SHA256 prefix `ef1d1e9c`), dataset `benchmarks/embedding-quality-dataset-self.json` (104 queries). Two independent runs produced identical numbers (0% variance — deterministic).\n\n| Method                            | MRR@10    | Acc@1   | Acc@3   | Avg ms  |\n| --------------------------------- | --------- | ------- | ------- | ------- |\n| Lexical only (no semantic)        | 0.583     | 53%     | 65%     | 41      |\n| Semantic only                     | 0.689     | 65%     | 74%     | 498     |\n| **Hybrid** (`get_ranked_context`) | **0.712** | **68%** | **75%** | **115** |\n\nHybrid uplift over lexical: **+0.128 MRR, +15% Acc@1**. Semantic alone beats lexical but hybrid beats semantic by blending both signals. Identifier queries reach `MRR 0.935` with every method (structural matching is sufficient); the hybrid advantage concentrates on natural-language queries (+0.159 MRR) and short phrases (+0.318 MRR).\n\n\u003e **v1.9.23 → v1.9.32 re-measurement**: Hybrid −0.046 (0.758 → 0.712), Semantic −0.043, Lexical −0.018. Dataset and model unchanged. Commit span `84c825d..26d513e` includes retrieval-path tuning that slightly dropped the aggregate score; the architecture refactors in v1.9.31–v1.9.32 (`dispatch/`, `tools/`, `main.rs` splits) do not touch retrieval code. Root-cause investigation is a follow-up in a dedicated bench session.\n\nCross-project matrix (6 languages, last run v1.9.23 line — not re-measured this cycle): Rust (self / axum / ripgrep), Python (django / requests), TS/JS (jest / next-js / react-core / typescript), Go (gin), Java (gson), C (curl). Historical hybrid numbers for those projects are tracked in `benchmarks/embedding-quality-phase3-matrix.json`.\n\n\u003e 2-tier NL→code bridges: generic core (15 entries) + auto-generated project bridges (`.codelens/bridges.json`). The self-benchmark above runs with both tiers active.\n\u003e\n\u003e **Bridge measurement honesty (v1.9.46 three-arm ablation, 2026-04-18)**: on the self dataset, project bridges (`.codelens/bridges.json`, 581 entries) contribute **0 MRR** — both-on and generic-on are bit-exact identical to six decimals. Generic core contributes **+0.010 MRR** overall (+0.016 on natural-language queries). Flask pilot (n=20, Python) found **0/20 generic-term matches** — the generic bridges are CodeLens-dev-tooling vocabulary (\"categorize\", \"camelcase\", \"who calls\", \"into an ast\"), not a language-agnostic mapping. Cross-language bridge contribution remains unverified pending multi-repo pilots. Artifacts: `benchmarks/results/v1.9.46-3arm-bridge-*.json`.\n\n```bash\n# Measure on your project\npython3 benchmarks/embedding-quality.py . --isolated-copy\n```\n\n## Enterprise Features\n\n| Feature                    | Status                                                                     |\n| -------------------------- | -------------------------------------------------------------------------- |\n| Config policy              | `.codelens/config.json` per-project feature flags                          |\n| Rate limiting              | Session-level throttle (default 300 calls, configurable)                   |\n| Schema versioning          | `schema_version: \"1.0\"` in all responses                                   |\n| Intelligence sources       | `tree_sitter`, `lsp`, `semantic`, `scip` — reported via `get_capabilities` |\n| Mutation audit log         | `.codelens/audit/mutation-audit.jsonl`                                     |\n| OTel exporter              | OTLP gRPC via `--features otel` + `CODELENS_OTEL_ENDPOINT` env var         |\n| OTel-ready spans           | `tool.success`, `tool.backend`, `tool.elapsed_ms`, `otel.status_code`      |\n| SBOM                       | CycloneDX per release                                                      |\n| Dataset lint               | CI-integrated benchmark hygiene (5 rules)                                  |\n| Multi-language test filter | Python, JS/TS, Go, Java, Kotlin, Ruby test symbols excluded from index     |\n| SCIP precise backend       | `--features scip-backend` — definitions, references, diagnostics, hover    |\n| Docker                     | Release-runtime `Dockerfile.release` with healthcheck                      |\n\n## vs Serena\n\n| Axis             | CodeLens                                    | Serena                    |\n| ---------------- | ------------------------------------------- | ------------------------- |\n| Runtime          | Single Rust binary, \u003c12ms cold start        | Python + uv               |\n| Intelligence     | tree-sitter + SQLite + optional LSP/SCIP    | LSP by default            |\n| Token efficiency | Bounded workflows, 50-87% savings           | Standard tool responses   |\n| Workflow layer   | Composite reports + analysis handles        | Symbolic tools            |\n| Semantic search  | Sidecar ONNX + hybrid ranking + NL bridging | No bundled model          |\n| Refactoring      | Preview-first gated mutations               | Stronger IDE-backed edits |\n| Enterprise       | Config policy, rate limit, OTel, SBOM       | None                      |\n| Offline          | Works offline with a staged sidecar model   | Depends on backend        |\n\nSee [docs/serena-comparison.md](docs/serena-comparison.md) for detailed gap analysis.\n\n## Building\n\n```bash\ncargo build --release                              # semantic pipeline enabled (76MB)\ncargo build --release --no-default-features        # without ML model (23MB)\ncargo build --release --features http              # add HTTP transport\ncargo build --release --features otel              # add OpenTelemetry OTLP exporter\ncargo build --release --features scip-backend      # add SCIP precise navigation\ncargo build --release --features http,otel         # HTTP + OTel\n\n# Core verification\ncargo test -p codelens-engine\ncargo test -p codelens-mcp\ncargo test -p codelens-mcp --features http\ncargo test -p codelens-mcp --no-default-features   # semantic=off path\n```\n\n### Feature Flags\n\n| Feature        | Description                               | Binary Size Impact |\n| -------------- | ----------------------------------------- | ------------------ |\n| `semantic`     | Semantic pipeline with sidecar ONNX model | +53MB              |\n| `http`         | Streamable HTTP + SSE transport           | +2MB               |\n| `otel`         | OpenTelemetry OTLP gRPC exporter          | +4MB               |\n| `scip-backend` | SCIP index precise navigation             | +1MB               |\n\n## Harness Architecture\n\nCodeLens is designed as a **harness coprocessor** — it doesn't replace your agent, it makes your agent's harness smarter.\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                        Agent Harness                             │\n│                                                                  │\n│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │\n│   │ Planner  │  │ Builder  │  │ Reviewer  │  │ Refactor │       │\n│   └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │\n│        │              │              │              │             │\n│        └──────────────┴──────────────┴──────────────┘             │\n│                              │ MCP                               │\n│                    ┌─────────▼──────────┐                        │\n│                    │   CodeLens MCP     │                        │\n│                    │  ┌──────────────┐  │                        │\n│                    │  │  Profiles    │  │ planner-readonly       │\n│                    │  │  Workflows   │  │ builder-minimal        │\n│                    │  │  Handles     │  │ reviewer-graph         │\n│                    │  │  Gates       │  │ refactor-full          │\n│                    │  └──────┬───────┘  │                        │\n│                    │         │          │                        │\n│                    │  ┌──────▼───────┐  │                        │\n│                    │  │codelens-engine│  │ tree-sitter + SQLite  │\n│                    │  │  25 langs    │  │ + embedding + graphs  │\n│                    │  └──────────────┘  │                        │\n│                    └────────────────────┘                        │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n**Each agent role sees a different tool surface:**\n\n- **Planner** gets `analyze_change_request`, `onboard_project` — compressed context, no mutations\n- **Builder** gets `find_symbol`, `get_ranked_context` — minimal surface, focused implementation\n- **Reviewer** gets `impact_report`, `diff_aware_references` — graph-aware bounded reviews\n- **Refactor** gets `safe_rename_report`, `verify_change_readiness` — gate-protected mutations\n\n**Harness primitives built in:**\n\n- **Analysis handles** — agents expand only the section they need, not the full report\n- **Mutation gates** — verification required before code changes, preventing blind rewrites\n- **Doom-loop detection** — identical tool calls auto-detected and redirected\n- **Token compression** — 5-stage adaptive budget keeps responses bounded\n- **Suggested next tools** — contextual chaining guides agents through optimal tool sequences\n\n## MCP Spec Compliance\n\n| Feature                                 | Status                                 |\n| --------------------------------------- | -------------------------------------- |\n| Streamable HTTP + SSE                   | Supported                              |\n| Role-based capability negotiation       | `--profile` flag                       |\n| Tool Annotations (readOnly/destructive) | Supported                              |\n| Tool Output Schemas                     | Generated from the surface manifest    |\n| `.well-known/mcp.json` Server Card      | HTTP transport                         |\n| Analysis handles + section expansion    | Supported                              |\n| Durable analysis jobs                   | Supported                              |\n| Mutation audit log                      | `.codelens/audit/mutation-audit.jsonl` |\n| Multi-project queries                   | `query_project`                        |\n| Contextual tool chaining                | `suggested_next_tools`                 |\n| MCP 2025-03-26 spec                     | Full compliance                        |\n\n## Quality Assurance\n\n| Suite                      | Tests   | Scope                                      |\n| -------------------------- | ------- | ------------------------------------------ |\n| codelens-engine            | 286     | Parsing, ranking, embedding, IR            |\n| codelens-mcp               | 238     | Dispatch, workflows, profiles, schemas     |\n| codelens-mcp (no semantic) | ~190    | Feature-off path verification              |\n| Dataset lint               | 5 rules | file_exists, negative≠positive, duplicates |\n\n```bash\n# Full verification\ncargo test -p codelens-engine \u0026\u0026 cargo test -p codelens-mcp\ncargo test -p codelens-mcp --no-default-features  # semantic=off path\npython3 benchmarks/lint-datasets.py --project .     # dataset hygiene\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue first to discuss what you'd like to change.\n\n```bash\n# Development workflow\ncargo check \u0026\u0026 cargo test -p codelens-engine \u0026\u0026 cargo test -p codelens-mcp\ncargo clippy -- -W clippy::all\n```\n\n## License\n\n[Apache-2.0](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmupozg823%2Fcodelens-mcp-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmupozg823%2Fcodelens-mcp-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmupozg823%2Fcodelens-mcp-plugin/lists"}