Depradar

/depradar

> Scan your project's dependencies for breaking changes, find which files in YOUR codebase will break, and surface community reports from GitHub, Stack Overflow, Reddit, and Hacker News — all in one command.

---

What This Skill Does

/depradar is a dependency intelligence tool that goes far beyond npm outdated or pip list --outdated. When you run it:

1. Reads your dependency files — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, pom.xml, and more
2. Checks every registry — npm, PyPI, GitHub Releases, crates.io, Maven Central — for new versions
3. Extracts breaking changes — parses release notes and CHANGELOGs using section-header detection, Conventional Commits (feat!:, BREAKING CHANGE:), and keyword heuristics
4. Scans YOUR codebase — Python: full AST analysis (high confidence). JS/TS: import-tracking regex with package context (medium confidence) + optional true AST via Node.js if available (high confidence). Other languages: grep fallback
5. Searches the community — GitHub Issues, Stack Overflow, Reddit, and Hacker News for migration pain reports
6. Scores and ranks — severity × recency × codebase impact × community pain (0-100 scale)
7. Delivers an actionable report — tells you what broke, where it broke in your code, and what others did to fix it

---

Invocation

/depradar                           # Scan current project, all production deps
/depradar stripe openai             # Check only these specific packages
/depradar --all                     # Include devDependencies / dev extras
/depradar --quick                   # 60s timeout, top 5 packages by severity
/depradar --deep                    # 300s, exhaustive community search
/depradar --days=7                  # Changes in last 7 days (default: 30)
/depradar --refresh                 # Bypass 6-hour cache, force fresh data
/depradar --emit=json               # Output: compact (default) | json | md | context
/depradar --emit=md                 # Save full markdown report to ~/Documents/DepRadar/
/depradar --diagnose                # Show API key status + test validity
/depradar --mock                    # Use fixtures (testing, no network calls)
/depradar --no-scan                 # Skip codebase impact scan (faster)
/depradar --no-community            # Skip community signal search
/depradar --save                    # Auto-save markdown report
/depradar --save-dir=PATH           # Save report to custom directory
/depradar --path=PATH               # Scan a different project directory
/depradar --verbose                 # Show detailed per-step progress
/depradar --fail-on-breaking        # Exit code 1 if breaking changes found (CI/CD)
/depradar --min-score=N             # Only show packages with score >= N (default: 0)
/depradar --notify=slack://WEBHOOK  # Send report to Slack webhook
/depradar --notify=file:///PATH     # Write JSON report to file
/depradar --show-ignored            # Show packages suppressed by .depradar-ignore
/depradar --version                 # Show version

---

Step-by-Step Instructions for Claude

This section describes exactly how Claude should execute this skill. Follow each step in order.

---

Step 0: Understand What the User Wants

Before running anything, parse the invocation to understand:

Package filtering: If the user named specific packages (e.g., /depradar stripe openai), note these. The script will filter to only those packages.

Flag mapping:

• --quick → --depth=quick (60s timeout, top 5 packages)
• --deep → --depth=deep (300s timeout, exhaustive)
• --days=N → look back N days for new releases (default: 30)
• --refresh → bypass cache
• --no-scan → skip codebase impact scan
• --no-community → skip community signal search
• --emit=FORMAT → output format (compact, json, md, context)
• --save → save markdown to ~/Documents/DepRadar/
• --diagnose → show config status and exit
• --mock → use fixture data, no network calls

User intent signals: If the user says "check if openai is broken" — that means /depradar openai. If they say "what needs updating in this project" — that's /depradar. If they say "why is my stripe code failing after update" — that's /depradar stripe --deep.

---

Step 1: Locate the Script

The skill's main Python script is at:

{SKILL_ROOT}/scripts/depradar.py

Where {SKILL_ROOT} is the directory containing this SKILL.md file.

To find SKILL_ROOT dynamically:

SKILL_ROOT="$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}")")"

If Claude is running this directly (not via bash), find the skill root by looking for the directory that contains both SKILL.md and scripts/depradar.py.

The typical installed locations are:

• ~/.claude/skills/depradar-skill/ (Claude Code)
• ~/.codex/skills/depradar-skill/ (OpenAI Codex)
• ~/.agents/skills/depradar-skill/ (generic)

---

Step 2: Check Prerequisites

Before running, verify Python 3.8+ is available:

python3 --version

If Python is not available, tell the user: > "Python 3.8+ is required. Please install it from python.org or via your package manager."

No external pip packages are required — the skill uses only Python stdlib.

---

Step 3: Run the Script

Basic invocation:

cd "{PROJECT_ROOT}" && python3 "{SKILL_ROOT}/scripts/depradar.py" {ARGS}

Important: Always cd to the project root first. The script uses the current working directory to find dependency files and scan the codebase.

Examples:

Run with default settings:

cd /path/to/project && python3 ~/.claude/skills/depradar-skill/scripts/depradar.py

Check specific packages only:

cd /path/to/project && python3 ~/.claude/skills/depradar-skill/scripts/depradar.py stripe openai

Quick scan with JSON output:

cd /path/to/project && python3 ~/.claude/skills/depradar-skill/scripts/depradar.py --quick --emit=json

Show config status:

python3 ~/.claude/skills/depradar-skill/scripts/depradar.py --diagnose

Test with mock data (no network):

cd /path/to/project && python3 ~/.claude/skills/depradar-skill/scripts/depradar.py --mock

---

Step 4: Parse the Output

The script outputs to stdout. The output format depends on --emit:

compact (default): Human-readable terminal output. Parse it by looking for:

• Lines starting with ### → package name + version bump
• Lines containing **Impact:** → codebase impact count
• Lines starting with - under **Impact:** → file:line references
• Lines starting with N. under **Breaking changes:** → individual breaking changes
• Lines under **Community signals:** → external reports

json: Full machine-readable JSON. The structure is DepRadarReport:

{
  "project_path": "/path/to/project",
  "packages_scanned": 23,
  "packages_with_breaking_changes": [
    {
      "id": "P1",
      "package": "stripe",
      "current_version": "7.0.0",
      "latest_version": "8.0.0",
      "semver_type": "major",
      "has_breaking_changes": true,
      "score": 87,
      "breaking_changes": [...],
      "impact_locations": [...],
      "impact_confidence": "high"
    }
  ],
  "packages_with_minor_updates": [...],
  "packages_current": ["axios", "lodash", ...],
  "github_issues": [...],
  "stackoverflow": [...],
  "reddit": [...],
  "hackernews": [...],
  "from_cache": false,
  "cache_age_hours": null,
  "depth": "default",
  "days_window": 30
}

context: Minimal snippet for passing to other skills or continuing a conversation.

md: Full markdown — best for saving to file.

---

Step 5: Synthesize and Present to the User

After the script completes, Claude should present the findings in a clear, actionable way. Follow these principles:

Lead with the action items. The user needs to know: "Do I need to update anything? Will it break my code? How hard is the migration?"

Structure your response:

1. One-line summary — "Found 2 packages with breaking changes affecting 7 files in your codebase."

1. For each breaking package (in score order):

• Package name, current → latest version, days since release
• Files in their codebase that will break (from impact_locations)
• What specifically changed (from breaking_changes)
• Migration guidance (from migration_note fields or community signals)
• Community pain level (how many others hit this)

1. Minor updates table — brief, just show what's available

1. Follow-up offers — see Step 6

What to emphasize:

• Impact locations in THEIR code (most actionable)
• Packages with score > 70 (high priority)
• Migration notes from the release notes
• StackOverflow questions that are ANSWERED (solved problems)
• GitHub issues that are CLOSED (resolved)

What to de-emphasize:

• Packages not found in registry (usually private packages)
• Community signals for packages with score "No dependency files found in {PROJECT_ROOT}. Make sure you're in your project root directory. Supported files: package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, pom.xml."

All packages up to date: > "All {N} dependencies are up to date — no action needed."

GitHub rate limit (60/hour without token): > "GitHub API rate limit reached. Add GITHUB_TOKEN to ~/.config/depradar/.env for 5,000 requests/hour. Run /depradar --diagnose to check your config."

Script not found: > "Could not find depradar.py. Make sure the skill is installed: copy the depradar-skill/ directory to ~/.claude/skills/. Run bash ~/.claude/skills/depradar-skill/scripts/sync.sh to install."

Python not found: > "Python 3.8+ is required. Install from python.org or via: brew install python3 (Mac) / sudo apt install python3 (Linux)."

Cache is stale: > "Using cached results from {N} hours ago. Run /depradar --refresh to fetch fresh data."

---

Configuration

/depradar works out of the box with no configuration. API keys unlock additional sources and higher rate limits.

Config File Location

Create either of:

• .claude/depradar.env — project-level (check this into .gitignore)
• ~/.config/depradar/.env — global (applies to all projects)

API Keys Reference

| Key | Purpose | Without Key | With Key | |-----|---------|------------|---------| | GITHUB_TOKEN | GitHub Releases + Issues | 60 req/hr | 5,000 req/hr | | SCRAPECREATORS_API_KEY | Reddit search | ❌ disabled | ✅ enabled | | XAI_API_KEY | X/Twitter via Grok | ❌ disabled | ✅ enabled | | AUTH_TOKEN + CT0 | X/Twitter via cookies | ❌ disabled | ✅ enabled | | STACKOVERFLOW_API_KEY | Stack Overflow | 300/day | 10,000/day |

Example Config File

# ~/.config/depradar/.env

# Strongly recommended — free at github.com/settings/tokens
# Scopes needed: (none — public repos only)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# From scrapecreators.com — enables Reddit community signals
SCRAPECREATORS_API_KEY=sc_xxxxxxxxxxxx

# From x.ai — enables X/Twitter signals
XAI_API_KEY=xai_xxxxxxxxxxxx

# From stackapps.com — 33x rate limit increase for Stack Overflow
STACKOVERFLOW_API_KEY=xxxxxxxxxxxx

Suppressing Known-Safe Breaking Changes

Create a .depradar-ignore file in your project root to suppress evaluated breaking changes:

# .depradar-ignore
# Format: package[@version]  # optional reason comment
chalk@5          # ESM-only, evaluated 2026-03-27 — only used in CLI output
dotenv@17        # uses config() only, unchanged API
stripe           # all versions suppressed (use with care)

• chalk@5 — suppresses chalk at any 5.x.x version
• chalk@5.3.0 — exact version only
• chalk — suppress all versions (use carefully)

A global ignore file at ~/.config/depradar/ignore applies to all projects. Run --show-ignored to see what's being suppressed.

---

Zero-Config Coverage

Without any API keys, /depradar still covers:

• ✅ All dependency file parsing (local, no network)
• ✅ npm Registry (no auth required, very high rate limits)
• ✅ PyPI API (no auth required)
• ✅ crates.io API (no auth required)
• ✅ Maven Central (no auth required)
• ✅ GitHub Releases (60 req/hr — enough for 10-15 packages)
• ✅ GitHub Issues search (60 req/hr shared with above)
• ✅ Stack Overflow (300/day — limited but functional)
• ✅ Hacker News (historical data, no auth)
• ❌ Reddit (requires SCRAPECREATORSAPIKEY)
• ❌ X/Twitter (requires XAIAPIKEY or cookies)

Zero-config covers ~80% of the skill's value.

---

Dependency File Support

| File | Ecosystem | Notes | |------|-----------|-------| | package.json | npm | Production deps; add --all for devDependencies | | package-lock.json | npm | Exact locked versions (v2/v3 format) | | yarn.lock | npm | Exact locked versions (v1 format) | | pnpm-lock.yaml | npm | Exact locked versions (v5/v6/v8 format) | | requirements.txt | PyPI | Handles ==, >=, ~=, != specifiers | | pyproject.toml | PyPI | PEP 621 [project].dependencies | | Pipfile | PyPI | Pipenv format | | setup.cfg | PyPI | Legacy install_requires and extras_require | | go.mod | Go | Standard Go modules | | Cargo.toml | Rust/crates.io | Standard Cargo format | | Gemfile | Ruby/rubygems | Handles gem directives | | pom.xml | Java/Maven | `` elements |

The script searches from the current directory upward to the git root, collecting all dep files found.

---

Scoring System

Every package and community signal is scored 0-100.

Package Score (Breaking Changes)

score = 0.35 × severity + 0.25 × recency + 0.30 × impact + 0.10 × community

Severity (based on change_type): | Change Type | Score | |-------------|-------| | removed | 100 | | renamed | 80 | | signature_changed | 70 | | behavior_changed | 60 | | type_changed | 50 | | deprecated | 40 | | other | 30 |

Recency (days since release): | Age | Score | |-----|-------| | 0-7 days | 100 | | 8-14 days | 85 | | 15-30 days | 65 | | 31-60 days | 40 | | 61-90 days | 25 | | 91+ days | 10 |

Impact (YOUR codebase): | Detection | Score | |-----------|-------| | High-confidence (AST) | 100 | | Med-confidence (grep) | 70 | | Low-confidence | 40 | | Not scanned | 50 | | Not found after scan | 10 |

Community pain:

community = min(100, log1p(weighted_pain_signals) × 12)

Where weighted_pain_signals sums quality_weight for each signal (closed+answered=2.0, closed=1.5, open+no comments=0.8). Only signals mentioning the same major version are counted (version-range filtered).

Two-phase scoring: Community signals (GitHub Issues, SO, Reddit, HN) are fetched in parallel AFTER the initial registry scan. The final score is calculated once all signals are available. Minor/patch releases are also checked for breaking changes — if found, they are flagged with a SEMVER VIOLATION badge.

Staleness bonus: If a breaking change has been available >30 days and you haven't upgraded, the urgency score increases (0-40 bonus points). Packages with 90+ day-old unaddressed breaking changes get a ⚡ STALE badge.

Interpreting Scores

| Score | Meaning | |-------|---------| | 80-100 | 🔴 Critical — breaking change directly hits your code, recently released, widely reported | | 60-79 | 🟠 High — significant breaking change, likely affects your code | | 40-59 | 🟡 Medium — breaking change in this major, but impact uncertain | | 20-39 | 🟢 Low — older or obscure breaking change | | 0-19 | ⚪ Minimal — very minor or unconfirmed |

---

Output Formats

compact (default)

Best for reading in the terminal. Shows:

• Package summary header with scan stats
• Breaking packages section with full details
• Minor updates table (capped at 10)
• Up-to-date count
• Registry errors

json

Full machine-readable JSON dump of the DepRadarReport dataclass. Use this when:

• Passing results to another script or tool

-

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tarun-khatri
• Source: tarun-khatri/depradar-skill
• License: MIT

Install and usage instructions live in the source repository linked above.