deadcode

intent

deadcode scans source code for dead code, unused exports, orphan files, and code cruft across JavaScript, TypeScript, Python, Go, Java, and CSS. run it when you want a one-time audit of your codebase, or hook it into git pre-commit workflows to catch dead code before it lands. the tool uses regex pattern matching (60+ patterns), auto-detects languages, and produces actionable reports. free tier scans up to 5 files per run; pro and team tiers unlock git hooks, markdown reports, orphan detection, ignore rules, and SARIF output for CI/CD.

inputs

required

• SKILL_DIR: path to this skill's root directory (where scripts/ lives). passed automatically by Implexa.
• target path: file or directory to scan. defaults to current working directory (.). can be a single file or recursive directory.
• bash, git, python3, jq: command-line tools. must be in PATH. check with which bash && which git && which python3 && which jq.

optional (pro / team tiers)

• DEADCODE_LICENSE_KEY: environment variable or entry in ~/.openclaw/openclaw.json. required for pro tier (hooks, report, orphans) and team tier (ignore, sarif). get one at https://deadcode.pages.dev. offline validation only, no network calls to check expiry.
• ~/.openclaw/openclaw.json: JSON config file. supports per-skill overrides:

  {
    "skills": {
      "entries": {
        "deadcode": {
          "enabled": true,
          "apiKey": "YOUR_LICENSE_KEY_HERE",
          "config": {
            "severityThreshold": "high",
            "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.spec.*"],
            "ignoreChecks": [],
            "reportFormat": "markdown"
          }
        }
      }
    }
  }
  

external connections

• lefthook: git hooks manager. installed via brew install lefthook (macOS) or platform-specific package manager. required only for hooks install command (pro tier). if not present when user tries hooks install, skill prompts installation with platform-specific command.

procedure

free tier: one-shot scan

command: bash "<SKILL_DIR>/scripts/deadcode.sh" scan [target]

1. input: target path (file or directory). if omitted, default to . (current directory).
2. validate tools: ensure bash, git, python3, jq are in PATH. fail with clear message if any missing.
3. detect languages: crawl target. identify JavaScript, TypeScript, Python, Go, Java, CSS, SCSS files by extension and shebang.
4. file limit check (free tier only): count source files. if count > 5, emit warning and process only first 5 files encountered.
5. load patterns: read 60+ dead code regex patterns from bundled pattern library (one per language type).
6. scan each file: for each source file, run all patterns for that language. capture line number, check ID, severity (critical / high / medium / low), description, and recommendation.
7. file-level checks: detect orphan files (never imported), large comment blocks (>20 consecutive lines), high TODO/FIXME density (>10 per 100 lines), debug markers (debugger, console.log, pdb.set_trace()).
8. calculate score: per-file dead code score (0 to 100, where 100 is clean). score = 100 - (critical_count * 20 + high_count * 10 + medium_count * 5 + low_count * 2), floored at 0. overall score = mean of all file scores.
9. output findings: write to stdout in machine-readable format (JSON or table). include file, line number, check ID, severity, description, recommendation.
10. set exit code: exit 0 if overall score >= 70 (code quality acceptable). exit 1 if overall score < 70 (too much dead code).

pro tier: git hooks

command: bash "<SKILL_DIR>/scripts/deadcode.sh" hooks install

1. input: project directory (implicit: current working directory where .git/ exists).
2. validate license: check DEADCODE_LICENSE_KEY env var or ~/.openclaw/openclaw.json. fail if missing or invalid. show link to https://deadcode.pages.dev/renew if expired.
3. check lefthook: verify lefthook --version works. if not, prompt: lefthook not found. install with: brew install lefthook (or platform-specific equivalent).
4. copy config: copy bundled lefthook config to project root as .lefthook.yaml or update existing config with deadcode pre-commit hook.
5. run lefthook install: execute lefthook install to register git hook.
6. output: confirm "git hooks installed. deadcode will scan staged files before every commit."

command: bash "<SKILL_DIR>/scripts/deadcode.sh" hooks uninstall

1. input: project directory.
2. validate license: optional (uninstall doesn't strictly need license, but keep consistent).
3. remove hook: delete deadcode pre-commit hook from .git/hooks/ or update .lefthook.yaml to disable deadcode entry.
4. output: confirm "git hooks removed."

pro tier: markdown report

command: bash "<SKILL_DIR>/scripts/deadcode.sh" report [directory]

1. input: directory to report on. default to current directory.
2. validate license: check DEADCODE_LICENSE_KEY. fail if missing or invalid.
3. run full scan: execute full deadcode scan (no file limit).
4. aggregate findings: group by file, calculate per-file scores and severity breakdown.
5. render markdown: use built-in template. sections: summary, severity histogram, per-file breakdowns with line-by-line findings, cleanup priority list, recommendations.
6. output: write to stdout or file (e.g., deadcode-report.md in target directory). suitable for pull request comments, wiki, or tech debt tracking.

pro tier: orphan detection

command: bash "<SKILL_DIR>/scripts/deadcode.sh" orphans [directory]

1. input: directory to scan.
2. validate license: check DEADCODE_LICENSE_KEY.
3. build import graph: crawl all source files. extract import statements (require, import, from, include, etc. per language). build directed graph of file dependencies.
4. identify orphans: find files with in-degree 0 (never imported or required).
5. exclude entry points: filter out index.js, main.go, init.py, main.py, setup.py, package.json, config files (.config.js, .json in root), test files (**/.test., **/.spec.).
6. confidence scoring: assign confidence level per orphan based on import patterns, naming conventions, and proximity to entry points.
7. output: list orphans with confidence (low / medium / high). include path, confidence, and suggested action (delete / review).

team tier: ignore rules

command: bash "<SKILL_DIR>/scripts/deadcode.sh" ignore [add|remove|list] [pattern]

1. input: subcommand (add, remove, list) and pattern (file glob or check ID).
2. validate license: check DEADCODE_LICENSE_KEY for team tier.
3. read config: load ~/.openclaw/openclaw.json.
4. add pattern: append pattern to skills.entries.deadcode.config.ignorePatterns array. persist to file.
5. remove pattern: delete pattern from array. persist.
6. list patterns: print all current ignore rules.
7. output: confirm change or print list.

team tier: SARIF output

command: bash "<SKILL_DIR>/scripts/deadcode.sh" sarif [directory]

1. input: directory to scan.
2. validate license: check DEADCODE_LICENSE_KEY for team tier.
3. run full scan: execute full deadcode scan.
4. format SARIF: map findings to SARIF v2.1.0 schema. include rule definitions (per check ID, with description, help text, severity level), locations (file, line, column), and result messages.
5. output: write JSON to stdout or file (e.g., deadcode-results.sarif). compatible with GitHub Code Scanning, Azure DevOps, GitLab SAST, etc.

utility: status

command: bash "<SKILL_DIR>/scripts/deadcode.sh" status

1. check license: read DEADCODE_LICENSE_KEY env var or ~/.openclaw/openclaw.json.
2. validate offline: verify license format and (if applicable) expiry date. no network calls.
3. output: tier (free / pro / team), expiry date, enabled status, current config overrides, list of installed git hooks.

decision points

• if file count > 5 (free tier): emit warning and process only first 5 files. paid tiers process all files.
• if DEADCODE_LICENSE_KEY missing and user invokes pro/team command (hooks install, report, orphans, ignore, sarif): fail with "license required. get one at https://deadcode.pages.dev. set DEADCODE_LICENSE_KEY env var or add to ~/.openclaw/openclaw.json".
• if license invalid or expired: show "license invalid or expired. renew at https://deadcode.pages.dev/renew".
• if lefthook not installed and user runs hooks install: prompt "lefthook not found. install with: [platform-specific command]". ask user to rerun command after install.
• if no source files found in target: report "no source files detected in target. scan clean." (exit 0). this is not an error, it's an edge case.
• if target is a single binary file: skip silently (no warning). continue scanning other files if target is a directory.
• if language type cannot be determined: skip file gracefully with no warning.
• if scan encounters network timeout or external API call (should not happen, all local): retry once. if persistent, fail with "network error. check internet connection or firewall."
• if .git/ not found and user runs hooks install: fail with "not a git repository. change directory to repo root and try again."
• if .lefthook.yaml already exists and conflicts with deadcode config: prompt user to manually merge or backup, then fail gracefully with instructions.

output contract

scan command

• format: JSON lines (one JSON object per finding) or machine-readable table (TSV).
• fields per finding: file (relative path), line_number (integer), check_id (string, e.g. "js-unused-export-001"), severity (critical / high / medium / low), description (string), recommendation (string).
• summary line: "scanned N files. found M critical, H high, D medium, L low severity issues. overall score: S%."
• exit code: 0 if score >= 70. 1 if score < 70.
• location: stdout. can be piped or redirected to file.

report command (pro)

• format: markdown (.md).
• sections: heading (title, date, target), executive summary (score, severity breakdown), per-file breakdowns (file path, score, findings list with line numbers and recommendations), cleanup priority (sorted by impact), final recommendations.
• file location: stdout or deadcode-report.md in target directory (or directory specified in config).
• links: include link to https://deadcode.pages.dev for docs.

orphans command (pro)

• format: JSON or markdown list.
• fields: file_path (string), confidence (low / medium / high), reason (string, why it's orphaned).
• location: stdout or deadcode-orphans.md.

sarif command (team)

• format: JSON (SARIF v2.1.0).
• schema: includes version, runs (array of run objects), each run contains tool info, rules, and results.
• location: stdout or deadcode-results.sarif.
• compatibility: GitHub Code Scanning, Azure DevOps, GitLab, other SARIF consumers.

status command

• format: key-value pairs or JSON.
• fields: license_tier (free / pro / team), license_key (first 8 chars + "..."), expiry_date (YYYY-MM-DD or "never" for lifetime), enabled (boolean), config (current overrides if any), git_hooks_installed (boolean).
• location: stdout.

outcome signal

• scan command: user sees list of dead code findings with line numbers and recommendations. if exit code 0, terminal prompt returns cleanly. if exit code 1, terminal shows non-zero exit (user knows there's work to do). user can copy findings into editor or issue tracker.
• hooks install: user commits code. before commit completes, deadcode scans staged files. if critical or high severity findings, commit is blocked. user sees findings and can fix or add to ignore rules. if clean, commit proceeds.
• report command: user receives markdown file. user can share with team, paste into wiki, or track in project board.
• orphans command: user gets list of candidate dead files. user can review each one, delete, or whitelist.
• ignore command: user adds pattern (e.g., "**/*.test.js" or check ID "js-console-log-001"). subsequent scans skip matching files or checks.
• sarif command: user copies JSON to CI/CD pipeline. CI/CD tool (GitHub Actions, GitLab CI, etc.) ingests results and displays in UI. developer sees dead code warnings alongside other code quality checks.
• status command: user sees license tier and expiry. if license will expire soon, user is prompted to renew.