devlens

DevLens — codebase intelligence via the devlens CLI

DevLens precomputes a structural graph of a repo: nodes (components, hooks, functions, routes, stores) joined by typed edges (CALLS, IMPORTS, READS_FROM, …), each carrying a technical summary, a business/functional summary, and a security assessment. Query it with the devlens CLI before opening files.

Why this saves tokens: a node summary is ~50 tokens; the underlying file is ~2000. Querying summaries, and using blast-radius/khop to fetch only the relevant slice, costs a fraction of reading files. Always pass --json. Reach for raw source (node-code) only as a last resort.

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

Step 1 — Ensure the CLI exists

Run devlens --version. If it is missing: npm install -g @devlensio/cli (corporate proxy? see the install note — set NODE_EXTRA_CA_CERTS).

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

Determine state:

• Current commit: git rev-parse HEAD
• Dirty? git status --porcelain (any output = uncommitted/untracked changes)
• Existing graphs: devlens status --json → find the entry whose repoPath is this repo; read its latestCommit and summarizedCommits.

Then apply, in order:

1. Worktree is dirty → re-analyze the working tree every run so structure matches disk: devlens analyze . --latest --json This replaces the stored graph with the latest uncommitted-worktree graph. Structure only — do NOT summarize. Existing summaries are inherited for unchanged nodes; new/changed nodes simply have none yet. Then proceed.
2. Clean worktree AND a graph for the current commit exists (latestCommit == git HEAD) → use it directly.
   • If the chosen subcommand needs summaries (architecture, explain, security-analysis, summary) and the graph has none for this commit (summarizedCommits is 0 / doesn't cover it), STOP and ask the user for permission to summarize before running devlens analyze . --summarize --json. If they decline, continue structure-only and say what's limited.
3. Clean worktree AND no graph for the current commit → create the structural graph first: devlens analyze . --json Then ask the user whether to summarize this commit (devlens analyze . --summarize --json). Proceed structure-only if they decline.

Golden rule: structural analyze may run automatically; --summarize 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.

Execution discipline (applies to every subcommand):

• Read the recipe before answering. The recipe files below contain the real instructions; the routing table is not enough on its own.
• Run every command the recipe marks mandatory before you write any output — do not stop after one or two calls. These graphs routinely have hundreds of nodes; your output must reflect that scale (enumerate routes/stores/hooks/modules; give exact counts; don't generalize from the top 10).
• Produce every section of the recipe's output template, fully. Do not abbreviate or skip sections. A two-line answer for a 600-node repo is wrong.

Routing table:

Subcommand	Recipe
init	${CLAUDE_SKILL_DIR}/commands/init.md
architecture	${CLAUDE_SKILL_DIR}/commands/architecture.md
diagram	${CLAUDE_SKILL_DIR}/commands/diagram.md
summary	${CLAUDE_SKILL_DIR}/commands/summary.md
security-analysis	${CLAUDE_SKILL_DIR}/commands/security-analysis.md
explain	${CLAUDE_SKILL_DIR}/commands/explain.md
tech-debt	${CLAUDE_SKILL_DIR}/commands/tech-debt.md
impact	${CLAUDE_SKILL_DIR}/commands/impact.md
find	${CLAUDE_SKILL_DIR}/commands/find.md
changes	${CLAUDE_SKILL_DIR}/commands/changes.md
guard	${CLAUDE_SKILL_DIR}/commands/guard.md

• No argument (bare /devlens): briefly list the subcommands above with one line each, and point to ${CLAUDE_SKILL_DIR}/reference.md for the full CLI catalog and when to use each command. 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 query command accepts -g <graphId> (defaults to the graph for the cwd) and -c <commit>. Default to the cwd graph unless the user specifies otherwise.