CodeLens MCP — Platform Setup Guide

One binary, cached hybrid retrieval, compressed context, and verification tooling for planner/reviewer/refactor harnesses.

Quick Install

Capability Matrix By Install Channel

What Needs Extra Installation

Commands

# Option 1: crates.io
cargo install codelens-mcp

# Option 1b: crates.io with shared HTTP daemon support
cargo install codelens-mcp --features http

# Option 2: Homebrew
brew install mupozg823/tap/codelens-mcp

# Option 3: One-line installer (downloads pre-built binary)
curl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash

# Option 4: Build from source
git clone https://github.com/mupozg823/codelens-mcp-plugin
cd codelens-mcp-plugin && cargo build --release --features http
cp target/release/codelens-mcp ~/.local/bin/

Verify: codelens-mcp . --cmd get_capabilities --args '{}'

Semantic search is not part of the lean crates.io default. It is available in GitHub Release, Homebrew, installer, or source builds that include the semantic feature, and it needs a sidecar model directory containing codesearch/model.onnx. Set CODELENS_MODEL_DIR to that parent directory or place models/codesearch/ next to the executable.

If you need a feature that exists on main but not in your installed binary, compare these before debugging:

1. codelens-mcp --version
2. latest GitHub tag
3. your install channel (crates.io, tagged release, or git/source build)

Tagged release binaries and Homebrew installs do not include unreleased commits from main.

Platform Configurations

Preferred: Shared HTTP Daemon

# One project writer; clients select review/builder per session and RBAC gates writes
codelens-mcp /path/to/project --transport http --profile builder --daemon-mode mutation-enabled --port 7838

Use HTTP as the default for multi-agent harnesses. Keep stdio for single local sessions only.

Recommended daemon contract:

• one mutation-capable project writer on 7838
• planner/reviewer/CI sessions select a read-only profile on that endpoint
• mutation remains gated by per-session RBAC, preflight, and coordination

For this repository's local launchd workflow, use scripts/install-http-daemons-launchd.sh. It installs one repo-local writer from a current --features http,semantic build, writes CODELENS_MODEL_DIR into the plist when the repo-local model sidecar exists, and disables the legacy readonly launchd label.

After changing runtime-facing retrieval or daemon behavior in this repository, refresh the local deployment and prove that the daemon is serving the same binary as HEAD:

bash scripts/redeploy-daemons.sh --build --probe
bash scripts/daemon-stale-check.sh
python3 scripts/runtime-snapshot.py --write --check
.codelens/bin/codelens-mcp-http . --cmd index_embeddings
python3 scripts/smoke-embedding-coverage.py --binary .codelens/bin/codelens-mcp-http --project .

The local launchd installer also defaults CODELENS_EMBED_RESOURCE_PROFILE=low_power. That caps semantic embedding work to the low-power runtime path (CPU provider, small batches, and at most two embedding threads) so always-on daemons do not compete aggressively with editor, browser, or model workloads. Use --embed-resource-profile balanced or --embed-resource-profile throughput only when measuring semantic indexing/search throughput.

That installer also writes repo-local host_attach.per_host_urls overrides into .codelens/config.json so codelens-mcp attach, status, and doctor render and verify against the same canonical 7838 contract.

All host configuration examples below use the canonical :7838 endpoint; profiles and RBAC provide the read-only versus mutation boundary.

If you need a public planner -> builder delegation pattern, including fixed preflight order, coordination TTL discipline, and explicit release_files, see Multi-agent integration.

For builder-session audit operations after a run:

1. get_tool_metrics({"session_id":"<builder-session>"})
2. audit_builder_session({"session_id":"<builder-session>"})
3. export_session_markdown({"session_id":"<builder-session>","name":"builder-audit"})

Planner/reviewer sessions use the same session filter shape:

1. get_tool_metrics({"session_id":"<planner-session>"})
2. audit_planner_session({"session_id":"<planner-session>"})
3. export_session_markdown({"session_id":"<planner-session>","name":"planner-audit"})

get_tool_metrics() without session_id still returns the global snapshot. Add session_id only when you want one logical session instead of the daemon-wide aggregate.

For host-side session closeout, prefer export_session_markdown(session_id=...) as the canonical per-session artifact source. Claude Stop hooks should treat it as best-effort augmentation of local raw audit rows, not as a blocking closeout step.

For daemon-wide aggregation across currently tracked runtime sessions, enqueue the single shipped eval lane:

1. start_analysis_job({"kind":"eval_session_audit","profile_hint":"review"})
2. get_analysis_job({"job_id":"<job-id>"})
3. get_analysis_section({"analysis_id":"<analysis-id>","section":"audit_pass_rate"})
4. get_analysis_section({"analysis_id":"<analysis-id>","section":"session_rows"})

eval_session_audit is runtime-scoped. It summarizes the sessions the daemon is currently tracking and does not backfill prior daemon restarts or external telemetry logs.

For operator snapshots against a running HTTP daemon, use scripts/export-eval-session-audit.sh. That script is intentionally separate from host Stop hooks because aggregate runtime state only exists in the daemon, not in a fresh one-shot CLI process.

Examples:

# JSON snapshot (default)
bash scripts/export-eval-session-audit.sh

# Human-readable operator report
bash scripts/export-eval-session-audit.sh --format markdown

# JSON snapshot plus refreshed historical summary
bash scripts/export-eval-session-audit.sh \
  --history-summary-path .codelens/reports/daily/latest-summary.md

# JSON snapshot plus refreshed operator gate artifact
bash scripts/export-eval-session-audit.sh \
  --history-gate-path .codelens/reports/daily/latest-gate.md

For a complete productivity proof bundle around one real agent work loop, run:

bash scripts/run-productivity-proof-loop.sh .

That wrapper combines local tool-usage analysis, live daemon audit export, history summary, latest-vs-previous productivity trend output, and operator gate output under .codelens/reports/productivity/. Use it when evaluating whether CodeLens actually reduces tool thrash, missed suggestions, audit warnings, and session rework over repeated runs.

For a daily macOS operator snapshot, install the launchd wrapper with scripts/install-eval-session-audit-launchd.sh. Example:

bash scripts/install-eval-session-audit-launchd.sh . --hour 23 --minute 55
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.codelens.eval-session-audit.codelens-mcp-plugin.plist

Add --format markdown if the operator lane should emit directly readable daily reports instead of JSON snapshots. For scheduled jobs, prefer the default JSON output so the history summarizer continues to have canonical input artifacts.

Once daily JSON snapshots accumulate, summarize recent drift/trend over that history with:

# Readable summary to stdout
bash scripts/summarize-eval-session-audit-history.sh

# Last 7 snapshots only
bash scripts/summarize-eval-session-audit-history.sh --limit 7

# Persist the rendered summary
bash scripts/summarize-eval-session-audit-history.sh .codelens/reports/daily/latest-summary.md

The history summarizer is file-based and offline. It reads prior eval-session-audit-*.json artifacts under .codelens/reports/daily/ and does not depend on a currently running daemon.

install-eval-session-audit-launchd.sh automatically wires the daily JSON snapshot job to refresh .codelens/reports/daily/latest-summary.md and .codelens/reports/daily/latest-gate.md after each run. Override those with --history-summary-path <path> and --history-gate-path <path>, or disable both by switching the scheduled job to --format markdown only if you intentionally do not want JSON history.

If you want an operator verdict instead of only a descriptive report, run:

# pass/warn/fail classification, exit non-zero only on fail
bash scripts/eval-session-audit-operator-gate.sh

# escalate warn to a failing exit code for stricter automation
bash scripts/eval-session-audit-operator-gate.sh --fail-on-warn

The operator gate reuses the historical summary data and applies lightweight thresholds over the latest builder/planner pass rates plus coverage gaps. It is an operator/CI layer on top of the file-based trend report, not a replacement for per-session audit_builder_session / audit_planner_session.

If .codelens/eval-session-audit-gate.json exists in the repo root, the gate script loads that policy automatically. Use CLI flags or env vars only when you intentionally want to override the repo-local baseline.

Example policy:

{
  "version": 1,
  "limit": 14,
  "thresholds": {
    "min_builder_pass_rate": 0.5,
    "min_planner_pass_rate": 0.5,
    "max_no_applicable_snapshots": 0,
    "fail_on_warn": false
  }
}

The export script can refresh that gate artifact automatically after each JSON snapshot, so the recommended operator chain is:

1. eval-session-audit-*.json as canonical daily history
2. latest-summary.md as the rolling descriptive report
3. latest-gate.md as the rolling pass/warn/fail verdict

That launchd wrapper defaults to http://127.0.0.1:7838/mcp so it matches the canonical single-writer endpoint. Pass --mcp-url only if your running daemon uses a different address.

If export-eval-session-audit.sh fails with unsupported analysis job kind 'eval_session_audit', the running daemon is older than the current aggregate lane. Restart that daemon from a current build before treating it as a script failure.

Use resources/read on codelens://surface/manifest when you need the canonical source for workspace version, tool counts, profile membership, or supported-language inventory. Repository docs are generated from the same manifest.

Use resources/read on codelens://harness/spec when the host needs the portable contract for preflight order, coordination TTL discipline, audit hooks, or handoff artifact skeletons.

Use resources/read on codelens://harness/host-adapters when the host needs portable guidance for adapting that contract to Claude Code, Codex, Cursor, Cline, or another agent runtime with different native primitives.

Use resources/read on codelens://harness/host with {"host":"claude-code"} or another host id when the consumer expects one resolved host summary instead of the broader adapter index. This compatibility alias returns detected_host, selection_source, bootstrap_sequence, task_stages, and guardrails in a single payload.

Use resources/read on codelens://host-adapters/<host> when you need concrete host-native template bundles rather than only the cross-host summary. Example: codelens://host-adapters/codex.

For a local copy-ready version of the same host bundle, run codelens-mcp attach <host>. Example: codelens-mcp attach codex.

To preview cleanup without touching files, run codelens-mcp detach <host> --dry-run. To actually remove machine-editable host config, run codelens-mcp detach <host> or codelens-mcp detach --all. The installer also exposes the same cleanup entrypoint via bash install.sh detach.

To verify that the host-native config is really attached after editing files, run codelens-mcp doctor <host> or codelens-mcp status <host>. Use --all to inspect every supported host contract at once, --strict to probe HTTP-daemon embedding_coverage_report and fail non-zero when attached semantic coverage is not ready or cannot be verified, or --json when a host-side script needs a machine-readable status payload.

If your 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 ~/.local/bin/codelens-mcp to the current checkout.

For the repo-local aggregate gate, run bash scripts/mcp-doctor.sh . --strict. That script reuses host status data across supported clients, ignores non-machine policy files, fails when a configured transport is unreachable or its machine-readable attach is malformed, and calls embedding_coverage_report against HTTP daemons so model assets, index freshness, query cache, model mismatch, and last index SHA are visible in the same smoke. CI and release smoke also run scripts/smoke-embedding-coverage.py against the packaged binary so a semantic-off build, missing model assets, model mismatch, or missing coverage fields fails before the heavier retrieval matrices run.

If you are preparing for the future public rename rather than changing runtime behavior today, use Migrate from CodeLens to Symbiote for host-by-host config diffs and the cutover checklist.

Use resources/read on codelens://design/agent-experience when the host needs the portable product-flow contract: naming gate, attach UX, user flow, agent flow, tool flow, reference flow, and harness flow.

Use resources/read on codelens://schemas/handoff-artifact/v1 when the host needs the JSON schema for persisted planner/builder/reviewer handoff artifacts.

prepare_harness_session also accepts optional host_context and task_overlay hints. Those hints compile into advisory bootstrap routing and overlay notes without changing the active tool surface or profile, so the same profile can adapt to Claude Code, Codex, Cursor, Cline, Windsurf, or a different task mode.

Retrieval Lane Quick Rule

Use the sparse BM25 lane when the query is lexical and narrow:

• bm25_symbol_search for identifiers, symbol paths, signature fragments, and 2-4 token short phrases
• find_relevant_rules for CLAUDE.md / project memory / policy snippets
• get_ranked_context for long natural-language intent, semantic exploration, and broad architecture questions

If a host starts with get_ranked_context, inspect retrieval.preferred_lane and retrieval.sparse_lane_recommended in the response before deciding whether to retry on the sparse lane.

For the full routing matrix, output-card contract, and corpus-separation rules, see BM25 sparse lane spec.

tools/list and tools/call expose the host-neutral execution contract as _meta["codelens/executionPolicy"]. The policy reports execution_class, risk, cost_hint, and concurrency_safe; it never selects a model, vendor, or agent. prepare_harness_session can also accept explicit host_capabilities facts so the host can negotiate native tool search, subagents, worktrees, editing, task, dynamic-tool, workspace-binding, and approval support without inferring capabilities from its name.

In HTTP sessions, initialize advertises capabilities.tools.listChanged = true, and CodeLens emits notifications/tools/list_changed after runtime surface switches such as set_profile or set_preset. Hosts that cache tool registries should use that notification to refresh tools/list instead of assuming the initial surface is static.

Successful responses use suggested_next_calls only for concrete callable follow-ups. A suggested mutation tool is host-neutral mutation intent: the host chooses the executor, preserves the provided arguments, and still applies normal approval, preflight, and mutation gates. CodeLens does not prepend a synthetic model- or vendor-specific handoff action.

For deferred loading flows, opt in during initialize with {"deferredToolLoading": true}. After that, the default tools/list call returns only the profile's preferred namespaces and tiers first, and omits outputSchema during bootstrap to keep session overhead bounded. Clients can expand one namespace at a time with {"namespace":"reports"}, open primitive tools with {"tier":"primitive"}, request the full surface explicitly with {"full": true}, or opt back into schemas with {"includeOutputSchema": true}. In deferred sessions, hidden namespaces and primitive tiers can gate tools/call until the client explicitly loads them, and codelens://tools/list / codelens://session/http resources reflect the same session state.

Recommended Harness Modes

• Default communication pattern: asymmetric-handoff
• Live bidirectional agent chat: discouraged
• Planner -> builder delegation: recommended
• Builder -> planner escalation: explicit-only
• Canonical harness modes: solo-local, planner-builder, reviewer-gate, batch-analysis
• Runtime resources: codelens://harness/modes, codelens://harness/spec
• Handoff schema resource: codelens://schemas/handoff-artifact/v1

Live Claude/Codex bidirectional chat is not the default operating model. The recommended pattern is still asymmetric handoff over shared CodeLens state, with builder-to-planner escalation kept explicit and rare.

1. Claude Code (CLI / Desktop / Web)

The host-specific attach examples in this section use the canonical daemon URL http://127.0.0.1:7838/mcp. Read-only behavior is selected per session.

Global config (~/.claude.json):

{
  "mcpServers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

Per-project (.mcp.json in project root):

{
  "mcpServers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

Profiles (preferred):

• readonly — bounded lookup and planning surface
• review — graph-aware review and risk-analysis surface
• builder — preflight-gated implementation and refactoring surface

Recommended bootstrap order:

1. prepare_harness_session
2. explore_codebase
3. trace_request_path or review_changes
4. plan_safe_refactor before any multi-file mutation

The previous names (planner-readonly, reviewer-graph, builder-minimal, refactor-full, and ci-audit) are deprecated input aliases. Use prepare_harness_session and role-filtered tools/list for the live visible-surface count in the active session.

For builder, use a preflight-first path:

1. verify_change_readiness
2. safe_rename_report or unresolved_reference_check for rename-heavy changes
3. get_analysis_section for extra evidence
4. mutation execution

Recent matching preflight is required before builder content mutations execute.

After a builder/refactor pass completes, run audit_builder_session on that session id. Treat warn as missing process evidence, and fail as a contract violation that should block merge/review until explained or rerun.

After a planner/reviewer pass completes, run audit_planner_session on that same session id. Treat warn as missing bootstrap / workflow-first / evidence discipline, and fail as a read-side contract break (for example a mutation attempt from a read-only surface).

If Claude Code consumes a mutation intent from suggested_next_calls, keep executor selection in the host and apply the target tool's normal approval and preflight rules before execution.

Legacy presets:

• minimal — smallest point-tool surface
• balanced — default workflow-first surface
• full — full visible registry for the current build

2. Cursor

Project config (.cursor/mcp.json):

{
  "mcpServers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

Global config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

If a Cursor foreground or background agent forwards a suggested mutation, preserve the concrete tool arguments and apply the target tool's approval and preflight rules; do not infer an executor from a server-generated model label.

3. Codex (OpenAI)

~/.codex/config.toml:

[mcp_servers.codelens]
url = "http://127.0.0.1:7838/mcp"
http_headers = { "x-codelens-project" = "/absolute/path/to/your/workspace" }

Prefer codelens-mcp attach codex for a copy-ready template: it stamps the workspace path into http_headers so each Codex session binds at initialize instead of inheriting the daemon's default project.

Ad hoc read-only smoke via CLI:

codex --mcp-server "http://127.0.0.1:7838/mcp"

Profiles (preferred):

• readonly — bounded lookup and planning surface
• review — graph-aware review and risk-analysis surface
• builder — preflight-gated implementation and refactoring surface

Recommended Codex bootstrap order:

1. prepare_harness_session
2. explore_codebase
3. trace_request_path or review_changes
4. plan_safe_refactor before any multi-file mutation

The previous profile names remain deprecated input aliases. Use prepare_harness_session and role-filtered tools/list when you need the exact session-local count.

For builder, use a preflight-first path:

1. verify_change_readiness
2. safe_rename_report or unresolved_reference_check for rename-heavy changes
3. get_analysis_section for extra evidence
4. mutation execution

Recent matching preflight is required before builder content mutations execute.

For write-capable builder agents attached over HTTP, use the same session id with get_tool_metrics, audit_builder_session, and export_session_markdown to review one builder session in isolation instead of the daemon-wide aggregate.

For planner/reviewer agents on readonly or review, replace the audit call with audit_planner_session. export_session_markdown(session_id=...) chooses the builder or planner audit summary automatically from the session surface.

If the host receives a concrete mutation intent in suggested_next_calls, it may reuse the supplied arguments after the normal approval, preflight, and mutation gates pass.

4. VS Code (Copilot / Continue / Cline)

.vscode/mcp.json:

{
  "servers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

5. JetBrains (IntelliJ / WebStorm / PyCharm)

Settings → Tools → MCP Servers → Add:

• Name: codelens
• URL: http://127.0.0.1:7838/mcp
• Transport: HTTP

6. Windsurf (Codeium)

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codelens": {
      "type": "http",
      "url": "http://127.0.0.1:7838/mcp"
    }
  }
}

Note: Windsurf has a 100-tool limit across all MCP servers. Prefer builder or readonly to keep the surface bounded.

6b. Cline

mcp_servers.json:

{
  "codelens": {
    "type": "http",
    "url": "http://127.0.0.1:7838/mcp"
  }
}

7. HTTP Transport (Remote / Multi-client)

For remote deployment or multi-agent harness scenarios:

# One project writer. Clients select readonly/review/builder per session.
codelens-mcp /path/to/project --transport http --profile builder --daemon-mode mutation-enabled --port 7838

# Client connects to:
#   POST http://localhost:7838/mcp          (JSON-RPC)
#   GET  http://localhost:7838/mcp          (SSE stream)
#   GET  http://localhost:7838/.well-known/mcp.json  (Server Card)

Published binary targets in the current release workflow:

• darwin-arm64
• linux-x86_64
• windows-x86_64

Docker:

FROM rust:1.83-slim AS builder
RUN apt-get update && apt-get install -y pkg-config libssl-dev
COPY . /app
WORKDIR /app
RUN cargo build --release --features http

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/codelens-mcp /usr/local/bin/
EXPOSE 7838
ENTRYPOINT ["codelens-mcp", "/workspace", "--transport", "http", "--port", "7838"]

8. Claude Agent SDK / Custom Agents

import anthropic
from anthropic.types import MCPServerStdio

client = anthropic.Anthropic()

# Use CodeLens as a compressed context server for your agent
agent = client.agents.create(
    model="claude-sonnet-4-20250514",
    mcp_servers=[
        MCPServerStdio(
            command="codelens-mcp",
            args=[".", "--profile", "readonly"],
        )
    ],
)

Environment Variables

vNext Workflow Defaults

• Planner/reviewer paths should start with analyze_change_request, impact_report, module_boundary_report, or dead_code_report.
• Refactor paths should start with refactor_safety_report or safe_rename_report.
• builder mutation execution is preflight-gated. Missing, stale, or blocked verifier evidence is rejected at runtime.
• Precise edit paths should opt into semantic_edit_backend=lsp when a language server is available. Current product-green LSP authority is rename, declaration/definition/implementation/type-definition resolution, and safe_delete_check. Guarded delete apply and LSP code-action refactors are conditional paths: they require inspectable minimal WorkspaceEdit evidence and must not be advertised as authoritative_apply until per-language fixture and external matrix gates are green. IDE integration remains a CodeLens adapter boundary: semantic_edit_backend=jetbrains and semantic_edit_backend=roslyn are optional local adapters, not bundled core dependencies. They are authoritative only when the adapter returns an inspectable minimal WorkspaceEdit; opaque commands, full-file replacements, and unsupported refactors fail closed instead of falling back to approximate text edits.
• Heavier reports can use start_analysis_job and poll via get_analysis_job.
• Expand detail only through get_analysis_section or codelens://analysis/{id}/... resources.
• Mutation-enabled profiles write audit logs to .codelens/audit/mutation-audit.jsonl.

Preset Comparison

• Workspace version: 1.13.35
• Presets: minimal (22), balanced (69), full (95)
• Profiles: readonly (40), builder (40), review (20)
• Canonical manifest: docs/generated/surface-manifest.json

Feature                    MINIMAL      BALANCED      FULL
─────────────────────────  ──────────   ──────────    ────────
Symbol lookup (find/get)   ✓            ✓             ✓
Code editing (rename/etc)  ✓            ✓             ✓
File I/O (read/list/find)  ✓            ✗¹            ✓
LSP diagnostics            ✓            ✓             ✓
Impact analysis            ✗            ✓             ✓
Dead code / cycles         ✗            ✗             ✓
PageRank importance        ✗            ✗             ✓
Semantic search            ✗            ✓²            ✓²
Multi-project queries      ✗            ✓             ✓
Unified insert/replace     ✓            ✓             ✓
─────────────────────────
¹ Claude Code has built-in Read/Glob/Grep
² Counts and semantic rows assume the default semantic-enabled build

Verify Installation

# Check binary
codelens-mcp --help 2>&1 || codelens-mcp . --cmd get_capabilities --args '{}'

# Check tool count per legacy preset
codelens-mcp . --cmd set_preset --args '{"preset":"full"}'
codelens-mcp . --cmd set_preset --args '{"preset":"balanced"}'
codelens-mcp . --cmd set_preset --args '{"preset":"minimal"}'

# Test symbol extraction
codelens-mcp /path/to/project --cmd find_symbol --args '{"name":"main","include_body":true}'