/jscpd

name: jscpd
description: Copy-paste detector for 220+ languages. Detect exact, renamed and near-miss duplicated code, measure duplication percentages, and find refactoring hotspots with the codebase summary.

jscpd

Copy-paste detector for programming source code, supports 220+ languages. Use this skill to run jscpd and understand its output.

Quick Start

# Run with ai reporter (compact output optimized for agents)
npx jscpd --reporters ai <path>

# With ignore patterns
npx jscpd --reporters ai --ignore "**/node_modules/**,**/dist/**" <path>

# Scope to specific formats
npx jscpd --reporters ai --format "javascript,typescript" <path>

# Second pass, noisier: copies that only differ in names and values (Type-2, "renamed").
# Review each hit before acting on it.
npx jscpd --reporters ai --ignore-identifiers --min-tokens 70 <path>

# Third pass, noisier still: copies with a few edited lines or the same function
# structure (Type-3, "similar"). Keep the settings tight.
npx jscpd --reporters ai --max-gap-lines 1 --similarity <path>

# Where to refactor first: clone list plus a hotspot summary
npx jscpd --reporters ai --summary <path>

# Most complex files only, without clone detection
npx jscpd --complexity --reporters ai <path>

AI Reporter Output Format

The `ai` reporter produces compact, token-efficient output designed for agent consumption:

Clones:
src/ foo.ts:10-25 ~ bar.ts:42-57
src/utils/helpers.ts:100-120 ~ src/utils/other.ts:5-25
src/cart/ basket.js:1-9 ~ cart.js:1-9 (renamed)
src/api/ save-account.js:1-12 ~ save-user.js:1-11 [~0.91 gap]
src/billing/ orders.ts:1-14 ~ refunds.ts:1-15 [~0.85 ast]
---
5 clones · 4.2% duplication

Each line represents one clone pair:

• **Same file**: `path/file.ts 10-25 ~ 45-60` (shared path shown once)
• **Same directory**: `shared/prefix/ file-a.ts:10-25 ~ file-b.ts:42-57` (common prefix factored out)
• **Different paths**: `path/a.ts:10-25 ~ path/b.ts:42-57`

A suffix tells the **kind** of clone; no suffix means an exact copy:

• `(renamed)`: the two blocks differ only in identifier names, literal values or annotations (Type-2). Only appears with `--ignore-identifiers`, `--ignore-literals` or `--ignore-annotations`.
• `[~0.91 gap]`: two exact clones merged across up to `--max-gap-lines` unmatched lines (Type-3). The number is matched tokens over the merged span.
• `[~0.85 ast]`: two functions whose normalized syntax trees share at least `--similarity` of their subtrees (Type-3). The number is that share. The names of called functions and methods and the operators count, local names and literal values do not, so a renamed copy with other constants scores 1 and a copy that calls other methods scores lower. A name still has to stand for one name on the other side: a copy that swaps the roles of two names scores lower.

Options

| Option | Description | |--------|-------------| | `--reporters ai` | Use the AI-optimized reporter (compact clone list for agents) | | `--reporters html` | Generate HTML report | | `--reporters json` | Output JSON report | | `--min-tokens N` | Minimum tokens to consider a duplication (default: 50) | | `--min-lines N` | Minimum lines to consider a duplication (default: 5) | | `--threshold N` | Exit with error if duplication % exceeds N | | `--ignore "glob"` | Ignore patterns (comma-separated) | | `--format "list"` | Limit to specific languages (e.g. `typescript,javascript`) | | `--cross-formats "groups"` | Detect clones across related formats (e.g. `javascript,typescript` or the `js-ts` preset) | | `--ignore-identifiers` | Treat all identifiers as equal, so blocks that differ only in variable, function or type names match (Type-2, reported as `renamed`); a name must stand for one name on the other side, so look-alikes with another data flow stay out, while a field and a local of one text are two names, so `this.url = url` still matches `this.url = link` (`--ignore-identifiers=blind` matches any names) | | `--ignore-literals` | Treat all string literals as equal and all numeric literals as equal (Type-2) | | `--ignore-annotations` | Drop `@Name` / `@Name(...)` annotations and decorators before matching, in languages where `@` means one (Type-2) | | `--max-gap-lines N` | Merge clones of one file pair separated by at most N unmatched lines into one `similar` clone (Type-3, default: 0 = off) | | `--similarity [RATIO]` | Report pairs of functions whose normalized syntax trees share at least RATIO of their subtrees, in `(0, 1]`, as `similar` clones (Type-3, 0.8 without a value). JavaScript, TypeScript, Python, Java, Kotlin, Scala, C#, Go, Rust, C, C++, PHP, Ruby, Swift and Clojure; test files are left out | | `--min-nodes N` | The fewest nodes of a normalized syntax tree a function needs for `--similarity` (default: 20) | | `--summary` | Append a codebase summary: top files/folders by tokens, lines, size, complexity, with duplication share | | `--summary-top N` | Number of entries in each summary top list (default: 10) | | `--summary-by metric` | Summary ranking metric: `tokens`, `lines`, `size`, `complexity` (default: `tokens`) | | `--kind list` | Report only these clone kinds: `exact`, `renamed`, `similar`, `gap`, `ast` (never enables a detector) | | `--complexity` | Complexity tables only, without clone detection (reporters: console, ai, json) | | `--dead-code` | Find unused files, exports, module-private declarations and imports — JavaScript, TypeScript, JSX, TSX, Vue, Svelte, Astro, Python. Each finding carries a 0-100 confidence score | | `--dead-code-categories list` | Limit `--dead-code`/`--dashboard` to categories: `unused-file`, `unused-export`, `unused-symbol`, `unused-import` | | `--min-confidence N` | Floor for `--dead-code`/`--dashboard` findings, 0-100 (default: 60) | | `--entry "glob"` | Extra entry points for dead-code analysis, beyond what's inferred from `package.json`/`pyproject.toml`/framework conventions | | `--include-tests` | Count test-only usage as "used" for dead-code