Analyze code complexity metrics (cyclomatic, cognitive, function length, coupling). Use when identifying refactoring targets, tracking codebase health, or reviewing large changes.
Analyze code complexity metrics (cyclomatic, cognitive, function length, coupling). Use when identifying refactoring targets, tracking codebase health, or reviewing large changes.
$1: Path to analyze (defaults to current directory)
--threshold: Complexity threshold for flagging (default: 10)
--format: Output format — summary (default), detailed, json
Metric Computation: Offload, Never Count By Hand
Complexity metrics (cyclomatic complexity, NLOC, parameter count, function
length, nesting depth) are computed by a tool, never by eyeballing function
boundaries or counting branches by hand. Hand-counting is token-hungry,
irreproducible run-to-run, and exactly the mechanical work that belongs in a
deterministic substrate.
Language-native fast paths (use when the project already has them
configured): radon for Python, cargo clippy for Rust, the ESLint
complexity rule for JS/TS when an ESLint config exists.
lizard — the uniform fallback for every language. One tool computes
cyclomatic complexity (CCN), NLOC, parameter count (PARAM), function length,
and nesting depth (ND) across JS/TS/Go/Python/Rust/C/C++/Java with
machine-readable output. It is the deterministic answer wherever a
language-native tool is absent — always the JS/TS and Go path when ESLint
complexity isn't configured.
Install lizard (tool-installation priority)
uv tool install lizard
Alternative: mise use -g pipx:lizard (mise pipx: backend, runs via uvx).
Execution
Execute this complexity analysis:
Step 1: Detect project language and available tools
Check for language-specific complexity tools, falling back to lizard:
JavaScript/TypeScript: use the ESLint complexity rule when an ESLint
config is present; otherwise use lizard.
Python: use radon (cyclomatic + maintainability index); lizard is a
fallback if radon is unavailable.
Rust: use cargo clippy cognitive-complexity warnings; lizard is a
fallback.
Go: use lizard.
Any other language / no native tool: use lizard.
Confirm lizard is installed (uv tool install lizard) before using the
fallback path.
Step 2: Measure function-level complexity
JavaScript/TypeScript (ESLint complexity rule, when configured):
JavaScript/TypeScript, Go, or any language without a native tool (lizard):
# Warnings only — one line per function exceeding the CCN threshold
lizard -C 10 --warnings_only .
# Full machine-readable metrics for every function (CSV)
lizard --csv .
lizard emits, per function: NLOC, CCN (cyclomatic complexity), token count,
PARAM (parameter count), length, and ND (nesting depth) — the complete metric
set, so no branch counting or line counting is done by hand. Restrict to a
language when needed with -l js, -l typescript, -l go, etc. The
--warnings_only run exits non-zero when any function exceeds the threshold.
radon cc ${1:-.} -s -a --min B
radon mi ${1:-.} -s
Rust:
cargo clippy -- -W clippy::cognitive_complexity
Step 3: Identify hotspots
Rank files and functions by complexity. Flag items exceeding the threshold:
Metric
Green
Yellow
Red
Cyclomatic complexity
1-5
6-10
11+
Cognitive complexity
1-8
9-15
16+
Function length (lines)
1-25
26-50
51+
Nesting depth
1-3
4
5+
Parameters per function
1-3
4-5
6+
Step 4: Calculate file-level metrics
For each source file:
Total functions/methods
Average complexity per function
Maximum complexity function
Lines of code vs lines of logic
Import/dependency count (coupling indicator)
The lizard default (non-CSV) run already prints per-file NLOC, average NLOC,
average CCN, average token count, and function count — use it for the file-level
roll-up.
Step 5: Report results
Complexity Report
=================
Files analyzed: N
Functions analyzed: N
Average complexity: X.X
Hotspots (complexity > threshold):
File | Function | CC | Lines | Depth
src/auth/handler.ts | validateToken | 15 | 82 | 6
src/api/router.ts | handleRequest | 12 | 64 | 5
Distribution:
Low (1-5): NN% of functions
Medium (6-10): NN% of functions
High (11+): NN% of functions
Recommendations:
1. [file:function] Extract nested conditions into helper functions
2. [file:function] Split into smaller focused functions
3. [file:function] Replace switch with strategy pattern
Post-Actions
If many high-complexity functions → suggest /code:refactor for the worst offenders
If complexity tools not installed → suggest uv tool install lizard (uniform, all languages) or pip install radon (Python)
If setting up complexity budgets → suggest adding ESLint complexity rule via /configure:linting
