CodeLens MCP

코딩 에이전트를 위한 살아 있는 코드 인덱스 — 더 적게 읽고, 더 정확하게 찾고, 안전하게 수정합니다.

A live code index for coding agents — bounded context, verifiable structure, and safer edits.

설치 · 문서 · 아키텍처 · 최신 릴리스

CI crates.io docs.rs License Downloads

CodeLens turns a noisy dependency graph into focused, verifiable code context

CodeLens MCP는 에이전트나 에디터를 대체하지 않습니다. Codex, Claude Code, Cursor 같은 MCP host가 대화를 소유하는 동안, CodeLens는 저장소의 현재 구조를 인덱싱하고 필요한 맥락만 제한된 크기로 반환하며 변경 전후 검증을 연결하는 코드 인텔리전스 보조 계층입니다.

기본 바이너리는 tree-sitter, BM25/sparse retrieval, graph/LSP 탐색, mutation gate를 제공합니다. Semantic search는 별도의 model sidecar가 있을 때 지연 활성화됩니다. GitHub Release에는 모델이 포함되며, crates.io 설치는 Install Channel Matrix의 추가 설정을 따릅니다. Host 연결 방법은 Platform setup에 정리되어 있습니다.

30초 소개

English: CodeLens in 30 seconds.

목표 CodeLens가 제공하는 것
더 적게 읽기 문제 중심 verb와 profile/preset으로 tool 표면과 응답 크기를 제한합니다.
더 정확하게 찾기 live symbol index, BM25, graph/LSP, 선택적 semantic retrieval을 한 project binding에 결합합니다.
현재 상태 검증 index freshness, daemon drift, output schema, 분석 handle로 근거와 신선도를 드러냅니다.
안전하게 수정 host-neutral session, single-writer runtime, role/mutation gate, audit와 readiness 검증을 적용합니다. 
cargo install codelens-mcp
codelens-mcp . --cmd get_capabilities --args '{}'

아키텍처 한눈에 보기

English: Architecture at a glance.

flowchart LR
  Host["Host agents<br/>Claude Code / Codex / Cursor"] --> Transport["MCP transport<br/>stdio or HTTP daemon"]
  Transport --> Server["codelens-mcp<br/>tool surface / session binding / response envelope"]
  Server --> Dispatch["dispatch pipeline<br/>rate limit / role gate / mutation gate"]
  Dispatch --> Tools["problem-first tools<br/>explore / trace / review / verify"]
  Dispatch --> Engine["codelens-engine<br/>symbols / graph / search / LSP / edits"]
  Engine --> Index["project index<br/>tree-sitter / BM25 / SQLite / SCIP* / semantic*"]
  Server --> Ops["observability<br/>surface manifest / audit sink / tool metrics"]

  classDef host fill:#eef6ff,stroke:#4d7fb8
  classDef core fill:#f7f7f7,stroke:#777
  classDef data fill:#fff7df,stroke:#a77d20
  class Host host
  class Server,Dispatch,Tools,Engine core
  class Index,Ops data

CodeLens는 host가 대화를 소유하고, codelens-mcp가 MCP tool 표면과 session policy를 관리하며, codelens-engine이 실제 코드 index와 graph/search/edit primitive를 제공하는 구조입니다. mutation은 engine primitive를 직접 호출하지 않고 MCP dispatch pipeline을 통과해야 role gate, preflight, audit, cache invalidation이 일관되게 적용됩니다.

English: The host owns the conversation, codelens-mcp owns the MCP surface and session policy, and codelens-engine owns repository indexing and code-intelligence primitives. Mutations are expected to pass through the MCP dispatch pipeline so gates, audits, and cache invalidation stay consistent.

영역 핵심 코드 역할
서버 부팅/transport crates/codelens-mcp/src/main.rs stdio, HTTP/HTTPS, one-shot CLI, profile/preset, semantic banner, daemon mode를 선택합니다.
MCP 요청 처리 crates/codelens-mcp/src/server/router.rs, crates/codelens-mcp/src/dispatch/mod.rs JSON-RPC tool call을 파싱하고 rate limit, role gate, access check, mutation gate, response shaping을 적용합니다.
tool 표면 crates/codelens-mcp/src/tools/mod.rs, crates/codelens-mcp/src/tool_defs/ 100개 tool 정의, profile/preset별 visible surface, workflow alias, schema output을 관리합니다.
session bootstrap crates/codelens-mcp/src/tools/session/project_ops/prepare_harness.rs prepare_harness_session(project=...)로 project binding, index recovery, host/skill hint, visible tool context를 반환합니다.
runtime state crates/codelens-mcp/src/state.rs, crates/codelens-mcp/src/state/ project context cache, watcher, LSP pool, analysis artifacts, coordination claims, audit sinks, semantic engine 상태를 보관합니다.
engine primitive crates/codelens-engine/src/lib.rs, crates/codelens-engine/src/symbols/, crates/codelens-engine/src/search.rs tree-sitter symbol index, sparse/BM25 ranking, hybrid search, graph/LSP/read primitive를 제공합니다.
semantic lane crates/codelens-mcp/src/dispatch/semantic/, crates/codelens-engine/src/embedding/ semantic feature와 model sidecar가 있을 때 embedding indexing/search를 활성화합니다.
검증/감사 crates/codelens-mcp/src/tools/reports/verifier_reports.rs, crates/codelens-mcp/src/audit_sink.rs verify_change_readiness, analysis handle, mutation audit, session report를 제공합니다.

Surface Snapshot

  • Workspace version: 1.13.35
  • Workspace members: 2 (crates/codelens-engine, crates/codelens-mcp)
  • Registered tool definitions: 100
  • Tool output schemas: 71 / 100
  • Supported language families: 34 across 56 extensions
  • Profiles: readonly (40), builder (40), review (20)
  • Presets: minimal (22), balanced (69), full (95)
  • Canonical manifest: docs/generated/surface-manifest.json

왜 필요한가

multi-agent 코딩 환경은 각 agent가 너무 많은 tool, 너무 많은 원본 코드, 너무 많은 중간 결과를 한꺼번에 보면 쉽게 느려집니다. tools/list, 반복적인 파일 읽기, 가치 낮은 raw graph expansion에 token이 낭비되고, 실제 수정에 필요한 판단 맥락은 오히려 흐려집니다.

English: Multi-agent coding harnesses waste tokens and attention when every agent receives too many tools, raw files, and intermediate graph results.

CodeLens가 하는 일

CodeLens는 코드베이스의 살아 있는 index와 구조 이해를 유지하고, 이를 MCP host가 바로 사용할 수 있는 최적화 계층으로 노출합니다. 모델은 정확한 질문을 던지고, 필요한 만큼 제한된 답변과 후속 확장 handle을 받습니다. 큰 코드베이스에서도 처음부터 전체 파일을 읽지 않고 “어디를 봐야 하는지”를 먼저 좁힐 수 있습니다.

English: CodeLens keeps a live indexed model of the repository and returns bounded, expandable answers instead of forcing the model to read everything up front.

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.

빠른 설치

English: Quick install options.

기본 설치 (BM25 + AST + call-graph, model sidecar 없음) — 추가 설정 없이 바로 동작합니다:

English: Default install. BM25 + AST + call graph, no model sidecar required.

cargo install codelens-mcp

Hybrid retrieval (semantic + bundled CodeSearchNet model) — semantic 검색까지 쓰려면 아래 중 하나를 선택하세요:

English: Pick one of these channels when you want semantic retrieval with the bundled CodeSearchNet model.

# Option A: GitHub Release tarball — 모델이 번들되어 있고 CI에서 검증됩니다.
curl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash

# Option B: semantic feature로 cargo install 후 CODELENS_MODEL_DIR를 모델 payload로 지정합니다.
#          crates.io 10 MB 제한 때문에 모델은 별도로 받아야 합니다.
cargo install codelens-mcp --features semantic
export CODELENS_MODEL_DIR=/path/to/codesearch/model

# Option C: Homebrew tap (macOS / Linux) — release tarball과 같은 구성입니다.
brew install mupozg823/tap/codelens-mcp

HTTP daemon mode — 위 설치 경로에 --features http를 추가하면 됩니다. Source build 예시는 다음과 같습니다:

English: Add --features http when you want shared HTTP daemon mode.

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.

최신 릴리스: GitHub Releases. 로컬에서 릴리스를 비교할 때는 문서에 고정 태그를 그대로 복사하지 말고 git tag --sort=-v:refname | head -1을 사용하세요.

English: Latest release: GitHub Releases. For local release comparisons, use git tag --sort=-v:refname | head -1 instead of copying a fixed tag into docs.

런타임 smoke 증빙: docs/quickstart-transcript.md는 격리된 임시 prefix에서 install -> doctor/status -> index -> coverage -> retrieve 흐름을 기록합니다.

English: Runtime smoke proof: docs/quickstart-transcript.md captures install -> doctor/status -> index -> coverage -> retrieve from an isolated temp prefix.

공개 저장소, 릴리스 페이지, plugin marketplace 설명은 이 README와 동일한 짧은 제품 소개 문구를 사용해야 합니다. 국가/언어별 페이지용 현지화 배포 문구는 docs/release-distribution.md#localized-deployment-page-copy에 있습니다.

English: Public repo, release-page, and plugin-marketplace descriptions should use the same short product line as this README. Localized deployment copy for country/language-specific pages lives in docs/release-distribution.md#localized-deployment-page-copy.

Install Channel Matrix

Channel What you get Good for Extra install needed?
cargo install codelens-mcp crates.io package, BM25 + AST + call-graph default (no semantic, no model needed) Single-agent local MCP sessions, fast first install Add --features semantic for hybrid retrieval (model sidecar required, see below). Add --features http for shared HTTP daemons.
cargo install codelens-mcp --features semantic crates.io package + ONNX/fastembed/sqlite-vec compiled in Hybrid retrieval users who prefer crates.io Semantic search requires a sidecar model directory — model files are excluded from cargo publish (10 MB cap on crates.io); fetch one from a GitHub Release tarball and point CODELENS_MODEL_DIR at it
cargo install codelens-mcp --features http crates.io package, BM25/AST default + HTTP transport Shared daemon mode from crates.io without semantic Combine with --features semantic,http if hybrid retrieval is wanted
GitHub Releases / installer / Homebrew latest tagged release binary, built in CI with --features http (http,coreml on macOS) Tagged release users who want HTTP without compiling Model payload is bundled in the tarball and verified pre-/post-archive in CI; airgap users can rebundle via scripts/build-airgap-bundle.sh
cargo install --git ... or source build current repository HEAD Unreleased features on main / branch testing Models live at crates/codelens-engine/models/codesearch/ in the source tree; no extra fetch needed

Important:

  • CodeLens standalone means the codelens-mcp binary itself. Basic stdio MCP use needs only that binary plus host MCP config.
  • 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.
  • 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.

Codex Plugin

Codex plugin은 $codelens skill과 호출 정책만 제공합니다. MCP 서버를 중복 등록하거나 별도 daemon을 시작하지 않으므로, 먼저 host-level codelens MCP가 canonical :7838 endpoint를 가리키는지 확인하세요:

English: The Codex plugin provides the $codelens skill and invocation policy only. It does not register another MCP server or start another daemon. Confirm the host-level codelens MCP points to the canonical :7838 endpoint first:

codex mcp get codelens
# 등록이 아직 없을 때만:
codex mcp add codelens --url http://127.0.0.1:7838/mcp

저장소 marketplace를 추가한 뒤 plugin을 설치하세요. 현재 Codex CLI의 설치 subcommand는 plugin add입니다:

English: Add the repository marketplace, then install the plugin. The current Codex CLI install subcommand is plugin add:

codex plugin marketplace add mupozg823/codelens-mcp-plugin
codex plugin add codelens@codelens

설치 후 새 Codex task에서 $codelens를 명시적으로 호출합니다. discovery 계약은 다음으로 확인할 수 있습니다:

English: Start a new Codex task after installation and invoke $codelens explicitly. Verify discovery with:

codex plugin list
codex debug prompt-input 'Use $codelens to review this repository architecture.'

Claude Code Plugin

CodeLens는 Claude Code plugin 형태로도 제공되며, 설치 한 번으로 MCP 서버와 CodeLens 전용 skill들, 읽기 전용 explorer agent를 함께 연결합니다.

English: CodeLens ships as a Claude Code plugin that wires the MCP server plus the CodeLens-specific skills and read-only explorer agent in one install.

사전 조건 — 바이너리를 먼저 설치하세요. plugin은 PATH에 있는 codelens-mcp 바이너리에 연결할 뿐, plugin 시스템 자체가 바이너리를 빌드해주지는 않습니다. 권장 경로는 installer 또는 GitHub Release tarball이며, 여기에는 semantic 모델이 번들되어 있어 semantic_search와 hybrid retrieval이 별도 설정 없이 바로 동작합니다:

English: Prerequisite — install the binary first. The plugin connects to a codelens-mcp binary on your PATH; the plugin system does not build it. The recommended path is the installer or a GitHub Release tarball, which bundle the semantic model so semantic_search and hybrid retrieval work out of the box:

curl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash

더 가벼운 cargo install codelens-mcp도 동작하지만 BM25 + AST + call-graph만 제공합니다(semantic 모델 없음; --features semantic와 모델 디렉터리를 추가하기 전까지 semantic_search는 자연스럽게 비활성 상태로 남습니다 — Install Channel Matrix 참고).

English: A leaner cargo install codelens-mcp also works but provides BM25 + AST + call-graph only (no semantic model; semantic_search is gracefully absent until you add --features semantic and a model directory — see the Install Channel Matrix).

plugin 설치:

English: Install the plugin:

/plugin marketplace add mupozg823/codelens-mcp-plugin
/plugin install codelens@codelens

제공되는 것: mcp__codelens__* tool들, codelens-analyze·codelens-review· codelens-onboard skill, 그리고 읽기 전용 codelens-explorer agent입니다.

English: What you get: the mcp__codelens__* tools, the codelens-analyze, codelens-review, and codelens-onboard skills, and the read-only codelens-explorer agent.

설치 후 tool이 보이지 않는다면 바이너리가 PATH에 없다는 뜻입니다. 다음으로 설치를 확인하세요:

English: If the tools don't appear after install, the binary isn't on your PATH. Verify the install with:

codelens-mcp doctor claude-code

Hook은 전부 선택 사항입니다. plugin 설치는 hook을 하나도 등록하지 않습니다 (hooks/hooks.json 없음). hooks/의 스크립트는 모두 opt-in이며, 바로 병합할 수 있는 등록 조각은 hooks/optional/에 있습니다 — 예: codelens-first.hooks.json(symbol 성격의 Grep/Bash를 CodeLens 호출로 유도하는 PreToolUse hook). 편집한 파일마다 CodeLens 진단을 실행하는 hooks/post-edit-diagnostics.sh도 같은 의미의 opt-in 예제입니다. 활성화 절차와 비용은 hooks/README.md를 참고하세요.

English: All hooks are optional. Installing the plugin registers zero hooks (there is no hooks/hooks.json). Every script under hooks/ is opt-in; ready-to-merge registration fragments live in hooks/optional/ — e.g. codelens-first.hooks.json, the PreToolUse hook that steers symbol-shaped Grep/Bash calls toward CodeLens. hooks/post-edit-diagnostics.sh, which runs CodeLens diagnostics on each edited file, is an opt-in example in the same sense. See hooks/README.md for the enable procedure and costs.

Setup

Environment Variables

.env.example을 .env로 복사한 뒤 사용 환경에 맞게 값을 채우세요:

English: Copy .env.example to .env and fill in the values for your environment:

cp .env.example .env

주요 변수로는 semantic search용 CODELENS_MODEL_DIR, telemetry용 CODELENS_OTEL_ENDPOINT, 프로젝트별 NL→code bridge를 활성화하는 CODELENS_PROJECT_BRIDGES_ON이 있습니다.

English: Key variables include CODELENS_MODEL_DIR for semantic search, CODELENS_OTEL_ENDPOINT for telemetry, and CODELENS_PROJECT_BRIDGES_ON to opt into project-specific NL→code bridges.

Claude Code / Cursor

{
  "mcpServers": {
    "codelens": {
      "command": "codelens-mcp",
      "args": []
    }
  }
}

Shared HTTP Daemon (Multi-Agent)

모든 editor나 agent를 각자의 stdio subprocess로 실행하면 세션마다 별도의 codelens-mcp 인스턴스가 뜨고, 각각 자체 index와 embedding 상태를 갖게 됩니다. 동일 프로젝트에 Claude Code + Codex Desktop + Cursor를 붙인 일반적인 개발자 노트북에서 측정한 결과, 사실상 같은 데이터를 위해 200–300 MB의 중복 상주 메모리가 발생합니다. HTTP daemon은 이를 하나의 공유 프로세스로 통합합니다.

English: Running 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.

crates.io로 설치했거나 소스에서 직접 빌드했고 HTTP transport가 필요하다면, 바이너리가 http feature를 포함해 빌드되었는지 확인하세요. 미리 빌드된 release 자산과 installer fallback에는 기본적으로 HTTP 지원이 포함되어 있습니다.

English: If 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.

최소 설정:

English: Minimal setup:

# Start one writer once, keep it running in the background. Clients select
# readonly/review/builder per session during initialize and RBAC gates mutation.
codelens-mcp /path/to/project --transport http --profile builder --daemon-mode mutation-enabled --port 7838

이 저장소의 로컬 launchd workflow도 같은 단일-writer 계약을 사용합니다: dev.codelens.mcp-mutation이 :7838에서 실행되고, Claude/Codex/Cursor의 host attach URL은 모두 http://127.0.0.1:7838/mcp입니다.

English: This repository's local launchd workflow uses the same single-writer contract: dev.codelens.mcp-mutation listens on :7838, and Claude/Codex/Cursor host attach URLs all point to http://127.0.0.1:7838/mcp.

이후 모든 MCP client는 subprocess를 새로 띄우는 대신 URL로 붙습니다:

English: Every MCP client then attaches by URL instead of spawning a subprocess:

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

이 저장소의 로컬 launchd workflow를 따르고 있다면 URL을 http://127.0.0.1:7838/mcp로 설정하세요. 읽기 전용/검토 표면은 별도 프로세스가 아니라 세션의 profile/RBAC로 선택합니다.

English: If you are following this repository's local launchd workflow, set the URL to http://127.0.0.1:7838/mcp. Read-only/review surfaces are selected by the session profile/RBAC rather than a second process.

When to prefer HTTP vs stdio

Situation Transport Why
Single-agent, ephemeral sessions stdio Zero setup, auto-lifecycle, no port management
2+ agents (Claude + Codex + Cursor) on the same repo HTTP One shared index, 100–200 MB saved per extra agent
Long-running agent or automation loop HTTP Avoids cold-start on every session
CI / one-shot script stdio --oneshot matches short-lived commands
Mutation-heavy workflow needing isolation HTTP with one writer + per-session RBAC Keep one project runtime; planner/reviewer sessions stay read-only by profile

HTTP를 공유하는 배포 환경에서는 CodeLens의 coordination을 중앙 lock manager가 아니라 참고용 증거(advisory evidence)로 취급하세요. 실무 패턴은 다음과 같습니다: prepare_harness_session으로 부트스트랩하고, register_agent_work로 작업 의도를 등록하고, claim_files로 mutation 대상을 claim한 뒤, 편집 전에 verify_change_readiness가 overlapping_claims를 caution 신호로 드러내도록 합니다.

English: For 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.

standalone 바이너리가 다루는 것과 다루지 않는 것:

English: What the standalone binary does and does not cover:

  • CodeLens only is enough for stdio use, HTTP daemon use, role-based surfaces, mutation gates, and coordination tools.
  • Semantic retrieval needs the packaged model sidecar at ./models/codesearch/ next to the binary, an installed prefix sidecar such as ../models/codesearch/, or an explicit CODELENS_MODEL_DIR. Release packaging fails closed if the model payload is incomplete; release CI can point at a staged model root with CODELENS_RELEASE_MODELS_DIR. macOS release binaries enable the coreml feature so the INT8 ONNX model can use the CoreML execution provider instead of silently falling back to CPU.
  • IDE adapters are external adapter endpoints that can be plugged in for IDE-specific semantic edits; no bundled adapters are required for core operation. semantic_edit_backend=tree_sitter is the default and always available.
  • SCIP precise navigation needs a binary built with --features scip-backend and an external SCIP index.
  • Claude -> Codex live delegation is not a CodeLens feature. It additionally needs Claude configured with a codex MCP server and a working Codex CLI install.

권장 운영 정책:

English: Recommended operating policy:

  • one mutation-enabled agent per worktree
  • additional agents stay planner/reviewer/read-only on the same daemon
  • use codelens://activity/current to inspect active sessions, recent intent, and advisory file claims

Troubleshooting

  • Failed to reconnect on the client — the daemon likely exited or the configured URL/port is wrong. Verify with curl <configured-mcp-url>; for this repository's local launchd workflow use http://127.0.0.1:7838/mcp for every host.
  • 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.
  • Host config sanity check — codelens-mcp doctor <host> (or codelens-mcp status <host>) inspects the host-native files and tells you whether the CodeLens entry is attached exactly, customized, missing, or needs manual review. Add --strict to probe HTTP-daemon embedding_coverage_report; the command exits non-zero when semantic coverage is attached but not ready or cannot be verified. Add --json when another script or host automation needs a machine-readable report.
  • 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/.
  • project_writer_busy or duplicate daemons — only one process may own a project's runtime. Stop/disable the legacy dev.codelens.mcp-readonly label, then run bash scripts/redeploy-daemons.sh --probe; inspect lsof -iTCP:7838 -sTCP:LISTEN for the canonical writer.
  • Health check — scripts/mcp-doctor.sh . --strict verifies that the configured transport matches an actual attach.

Auto-start on macOS (launchd)

이 저장소에서는 plist 파일을 직접 편집하기보다 installer 스크립트를 사용하는 것을 권장합니다:

English: For this repository, prefer the installer script over hand-editing plist files:

bash scripts/install-http-daemons-launchd.sh . --load

이 스크립트는 기본적으로 현재 --features http,semantic 빌드로부터 저장소 로컬 launchd agent 하나를 설치합니다:

English: That installs one canonical repo-local launchd agent from a current --features http,semantic build by default:

  • dev.codelens.mcp-mutation -> builder / mutation-enabled on :7838

The installer explicitly disables and boots out the legacy dev.codelens.mcp-readonly label. It never creates or bootstraps that plist; reviewer/planner sessions use readonly or review profiles on the canonical URL instead.

빌드 플래그 참고 (v1.10.1+): installer는 기본적으로 daemon을 http,semantic으로 빌드하며, 저장소 로컬 모델 sidecar가 존재하면 plist에 CODELENS_MODEL_DIR을 기록합니다. --no-semantic은 HTTP 전용 daemon을 의도적으로 원할 때만 사용하세요. 전체 feature-flag matrix는 docs/release-verification.md를 참고하세요.

English: Build flag reminder (v1.10.1+): the installer builds the daemon with http,semantic by default and writes CODELENS_MODEL_DIR into the plists when the repo-local model sidecar exists. Use --no-semantic only when you intentionally want an HTTP-only daemon. See docs/release-verification.md for the full feature-flag matrix.

또한 .codelens/config.json에 저장소 로컬 host_attach URL override를 갱신하여 codelens-mcp attach, status, doctor가 동일한 host-to-daemon 계약을 재사용하도록 합니다.

English: It also updates .codelens/config.json with repo-local host_attach URL overrides so codelens-mcp attach, status, and doctor reuse the same host-to-daemon contract.

위 installer 대신 plist를 직접 편집하고 싶다면 참고할 수 있는 일반적인 단일 daemon 예시입니다:

English: Generic single-daemon example, if you want to hand-edit a plist instead of using the installer above:

<!-- ~/Library/LaunchAgents/dev.codelens.mcp-mutation.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
  <key>Label</key>            <string>dev.codelens.mcp-mutation</string>
  <key>ProgramArguments</key> <array>
    <string>/Users/you/.local/bin/codelens-mcp</string>
    <string>/Users/you/your-project</string>
    <string>--transport</string><string>http</string>
    <string>--profile</string><string>builder</string>
    <string>--daemon-mode</string><string>mutation-enabled</string>
    <string>--port</string><string>7838</string>
  </array>
  <key>RunAtLoad</key>        <true/>
  <key>KeepAlive</key>        <true/>
  <key>StandardOutPath</key>  <string>/tmp/codelens-mcp.out.log</string>
  <key>StandardErrorPath</key><string>/tmp/codelens-mcp.err.log</string>
</dict></plist>

launchctl load ~/Library/LaunchAgents/dev.codelens.mcp-mutation.plist
launchctl list | grep codelens   # confirm it's running

별도의 일일 집계 audit snapshot을 위해서는 다음으로 operator job을 설치하세요:

English: For the separate daily aggregate audit snapshot, install the operator job with:

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

이 예약 job은 JSON snapshot을 정본 기록으로 유지하며, 기본적으로 실행할 때마다 .codelens/reports/daily/latest-summary.md와 .codelens/reports/daily/latest-gate.md를 갱신합니다.

English: That scheduled job keeps JSON snapshots as the canonical history and refreshes .codelens/reports/daily/latest-summary.md plus .codelens/reports/daily/latest-gate.md after each run by default.

launchd 없이 일회성 operator snapshot을 얻으려면 다음을 실행하세요:

English: For an ad hoc operator snapshot without launchd, run:

bash scripts/export-eval-session-audit.sh
bash scripts/export-eval-session-audit.sh --format markdown
bash scripts/export-eval-session-audit.sh --history-summary-path .codelens/reports/daily/latest-summary.md
bash scripts/export-eval-session-audit.sh --history-gate-path .codelens/reports/daily/latest-gate.md

최근 일일 snapshot들을 drift/trend 리포트로 요약하려면 다음을 실행하세요:

English: To summarize recent daily snapshots into a drift/trend report, run:

bash scripts/summarize-eval-session-audit-history.sh
bash scripts/summarize-eval-session-audit-history.sh --limit 7

그 기록을 operator pass / warn / fail 판정으로 바꾸려면 다음을 실행하세요:

English: To turn that history into an operator pass / warn / fail verdict, run:

bash scripts/eval-session-audit-operator-gate.sh
bash scripts/eval-session-audit-operator-gate.sh --fail-on-warn

.codelens/eval-session-audit-gate.json이 존재하면 gate 스크립트가 이를 자동으로 로드합니다. CLI 플래그와 환경 변수는 여전히 저장소 로컬 정책보다 우선합니다.

English: If .codelens/eval-session-audit-gate.json exists, the gate script loads it automatically. CLI flags and env vars still override the repo-local policy.

export 스크립트는 각 JSON snapshot 이후 해당 gate artifact를 자동으로 갱신할 수도 있어서, 예약된 operator가 latest-gate.md를 최신 상태로 유지하기 위해 별도의 wrapper job을 둘 필요가 없습니다.

English: The export script can also refresh that gate artifact automatically after each JSON snapshot, so scheduled operators do not need a second wrapper job just to keep latest-gate.md current.

실제 agent 루프에 대한 전체 생산성 증거 묶음을 수집하려면 다음을 실행하세요:

English: To collect a full productivity evidence bundle for a real agent loop, run:

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

이 명령은 .codelens/reports/productivity/ 아래에 tool 사용 분석, 실시간 daemon audit snapshot, 최근 기록 요약, 최신-이전 비교 생산성 trend 요약, operator gate 판정을 기록합니다.

English: That command writes tool-usage analysis, a live daemon audit snapshot, recent history summary, a latest-vs-previous productivity trend summary, and an operator gate verdict under .codelens/reports/productivity/.

Codex, Windsurf, VS Code 등 다른 플랫폼은 docs/platform-setup.md를 참고하세요.

English: See docs/platform-setup.md for Codex, Windsurf, VS Code, and other platforms.

Distribution Channels

Channel Delivery Notes
crates.io cargo install codelens-mcp Standard Rust install path
Homebrew tap brew install mupozg823/tap/codelens-mcp macOS/Linux package install
GitHub Releases prebuilt archives darwin-arm64, linux-x86_64, windows-x86_64
installer script install.sh Convenience bootstrap for release assets
source build cargo build --release Custom feature builds and local hacking

Why CodeLens?

CodeLens Read/Grep baseline
Token cost 50-87% less Full file content every time
Expensive-model fit Lean response contract: −17-18% text channel N/A
Context quality Ranked, bounded, structured Raw text, no prioritization
Multi-file impact 1 tool call 5-10 grep + read cycles
Runtime Single Rust binary, <12ms cold start N/A
Language support Generated from the surface manifest N/A
Agent awareness Doom-loop detection, mutation gates None

Token Economics for Fable-Class Models

프론티어급 agent 모델(Claude Fable 5: MTok당 $10/$50)은 저장된 모든 tool 응답을 다음 턴마다 입력으로 다시 지불합니다 — 응답 바이트는 일회성이 아니라 반복되는 비용입니다. CodeLens는 agent 소비 경제성을 아키텍처의 1급 관심사로 다루며, 이는 Anthropic의 공식 tool 설계 가이드(tool 응답은 10K 토큰에서 경고, text channel은 host가 주입하고 카운트하는 대상)에 근거합니다:

English: Frontier agent models (Claude Fable 5: $10/$50 per MTok) re-pay every persisted tool response as input on each subsequent turn — response bytes are a recurring cost, not a one-time one. CodeLens treats agent-consumption economics as a first-class architectural concern, grounded in Anthropic's official tool-design guidance (tool responses warn at 1