Devlens

DevLens — codebase intelligence via the DevLens MCP

DevLens precomputes a structural graph of a repo: nodes (components, hooks, functions, routes, classes, methods, structs, traits, stores) joined by typed edges (CALLS, IMPORTS, READS_FROM, IMPLEMENTS, …), each carrying a technical summary, a business/functional summary, and a security assessment. You query it through the DevLens MCP tools — not by reading files.

Supported languages (analyzed with native parsers, not regex/tree-sitter):

(Full per-language node/edge table in reference.md → "Node & edge types by language". A graph is per-repo/per-language: the node types you can query with find_nodes nodeTypes depend on the repo's language.)

Tool names. The DevLens MCP server is bundled with this plugin and registers automatically. Its tools appear to you as mcp__plugin_devlens_devlens__<name>. Throughout these recipes a tool is named by its short <name> (e.g. get_subgraph, find_nodes, get_blast_radius); call the matching mcp__plugin_devlens_devlens__… tool. Every tool is keyed by a graphId (and optionally a commitHash); read each tool's own description for its parameters.

Why this saves tokens: a node summary is ~50 tokens; the underlying file is ~2000. Querying summaries, and using get_blast_radius/get_khop/get_subgraph to fetch only the relevant slice, costs a fraction of reading files. Reach for raw source (get_node_code) only as a last resort.

Standing rule — prefer summaries when available: whenever a node has a technical or business summary, read it (get_node / get_summaries) to understand the code instead of opening the file — it is far cheaper and usually enough. Fall back to get_node_code or reading the file only when no summary exists (structure-only graph) or the summary is genuinely insufficient to act. This applies to every subcommand below.

Pre-flight check — the devlens://repos resource

The devlens://repos MCP resource is auto-attached by the host — read it to get the graphId for this repo without a tool call. If the resource is not available, call list_analyzed_repos once per session. Cache the graphId and reuse it for every subsequent query. Do not ask the user's permission; this is automatic.

Freshness guard — ALWAYS run before any workflow tool call

Before ANY workflow tool call (architecture_brief, security_brief, review_pr, onboarding_tour, get_context), run check_freshness once. If stale === true, ask the user before proceeding (or re-analyze structure-only if dirty). Do not silently answer against a stale graph.

On a { code: STALE_GRAPH | COMMIT_NOT_ANALYZED } error from any tool, call analyze (structure-only) and retry once; do not ask the user unless summarize permission is required.

If result.schemaVersion !== 1 on any composed tool result, stop and warn the user the skill is out of date with the installed DevLens.

When to reach for DevLens vs. plain file tools (routing policy)

On a repo in a supported language (TS/JS, Python, Go, Rust, Java), DevLens is the default way to understand code — querying the graph is cheaper and more accurate than grepping. Reach for DevLens (don't Grep/Glob/Read first) whenever you need to:

• Locate — "where is X", which file/component/class/handler/route does something → find_nodes / get_nodes_in_path.
• Understand — what a function/class/module does before relying on or editing it → get_node / get_summaries (summary first, source last).
• Assess impact — "what breaks if I change Y", who calls/uses X, what X depends on → get_blast_radius / get_khop.
• Orient before an edit — getting your bearings in an unfamiliar area → get_repo_overview / get_subgraph.
• Review — architecture, security, tech-debt, cycles, onboarding → the matching subcommand.

This is the fix for "grepping for every little task": don't fan out grep/Read to reconstruct what a node does or who depends on it — one graph query (a ~50-token summary) replaces several greps and full-file reads.

Use plain Read/grep/Glob instead when:

• You already know the exact file and the task is small and localized (a typo, a one-liner, a rename in a known spot).
• You need the literal current bytes to edit — once DevLens tells you where and what, pull the file to make the change (DevLens decides where/what; file tools make the edit).
• The repo is not in a supported language (plain C/C++/Ruby/Swift/… codebases aren't parsed yet), or no graph exists and the user doesn't want to analyze.
• You're searching things the graph doesn't model (config, docs, generated output, non-code assets).
• You need to confirm an empty blast radius (zero callers "in the graph" is not proof of safety) — a targeted grep here is the right tool.

Rule of thumb: DevLens to decide where and what; file tools to make the actual change. If you catch yourself about to grep a supported-language repo to understand a symbol, query the graph instead.

Step 1 — Ensure the DevLens MCP is connected

Call list_analyzed_repos. If it returns (even an empty list), the MCP is live — proceed. If the tool is not available (no mcp__plugin_devlens_devlens__* tools), the DevLens MCP isn't connected: tell the user and stop. To enable it, they can reinstall/enable this plugin, or register the server directly:

claude mcp add devlens -- npx -y @devlensio/cli mcp

(The MCP ships inside the @devlensio/cli package, so no separate install is needed once registered.)

Step 2 — Graph freshness guard (ALWAYS run before any query)

Resolve graphId ONCE per session, then reuse. Use the devlens://repos resource (auto-attached) or list_analyzed_repos to find the entry whose repo path matches this repo. Cache the graphId and reuse it. Re-resolve only if the user switches repos or you re-analyze.

Then call check_freshness once. Based on the result:

1. dirty === true → re-analyze structure-only: call analyze with this repo's path. Existing summaries are inherited for unchanged nodes. Then proceed.
2. behind === true (clean worktree, HEAD ahead of graph) → call analyze (structure only) for the current HEAD. Then ask the user whether to summarize this commit. Proceed structure-only if they decline.
3. stale === false → use the graph directly.
4. If the subcommand needs summaries and the graph has none (summariesCoverage.pct === 0) → STOP and ask the user for permission to summarize before running summarization. If they decline, continue structure-only and say what's limited.

Golden rule: structural analyze may run automatically; summarizing requires explicit user permission every time — it costs LLM calls. Never summarize silently.

Step 3 — Route to the subcommand

You were invoked as /devlens $ARGUMENTS. Take the first word ($0) as the subcommand and read the matching recipe file in full, then follow it exactly.

How to use the graph well (applies to every subcommand). These tools are a kit — the quality of your answer comes from orchestrating them, not from dumping the whole graph. Before writing any recipe's output, internalize the methodology in ${CLAUDE_SKILL_DIR}/reference.md → "How to use the graph well". In short:

• Orient cheap first with get_repo_overview (framework, route count, top central nodes). Let its exact counts anchor your output.
• Discover real modules from the graph, not from directory-name guesses: get_subgraph on central seed nodes returns the cohesive clusters that are the codebase's bounded contexts.
• Draw real connections with get_blast_radius (upstream) and get_khop (downstream) — never invent edges.
• Describe by meaning using get_summaries (business + technical) — label things by what they do, not by their names.
• Overlay health with list_cycles and get_security_issues.
• Be comprehensive through hierarchy, not omission. On a large repo, give a clean module-level answer that accounts for every route and every bounded node set — for JS/TS that's routes/stores/hooks; for Python/Java/Go/Rust it's routes + classes/methods/structs/traits/functions — and represents long tails explicitly (e.g. "+N more"), with drill-down offered — rather than enumerating raw node lists you never synthesized. Cite the exact counts from get_repo_overview. A thorough, well-structured answer is the goal; a brute-force node dump is not.
• Scope to the question. A scoped ask ("how does streaming work", a path) is not a whole-repo tour — seed from the named subsystem's cluster (get_subgraph) and stay there. Reserve the full sweep for genuinely whole-repo requests; over-traversing a scoped question drains the budget the write-up needs.
• Output discipline — the data is wasted if the write-up is garbled. (1) Lead with the exclusives a raw LLM can't produce: in-scope security severity flags are a mandatory call-out, describe relationships by their edge type, and rank by centrality. (2) No hand-drawn ASCII diagrams — they break and truncate; use Markdown tables or Mermaid blocks, or defer to /devlens diagram. (3) Protect the synthesis budget: collect efficiently (batch get_summaries, don't over-traverse), then write deliberately — a few sections written cleanly beats every section truncated.

Routing table:

• No argument (bare /devlens): briefly list the subcommands above with one line each, and point to ${CLAUDE_SKILL_DIR}/reference.md for the full tool catalog and when to use each. Do not run analysis.
• Unknown argument: say so and show the subcommand list.
• When auto-invoked (the user didn't type /devlens), pick the subcommand that matches their request (e.g. "is this secure?" → security-analysis; "draw the architecture" → diagram).

Every tool accepts graphId (default to the graph for the cwd) and an optional commitHash. Default to the cwd graph's latest commit unless the user specifies otherwise.