GhostDeps

GhostDeps reads your manifests, lockfiles and source code and tells you which declared dependencies your code does not actually need, with the evidence and confidence behind every claim. It runs as a check on your pull requests (GitHub App or Action) and as a local CLI, and it never executes your code.

Status

Early development. JavaScript/TypeScript, Python, Rust and Go are wired end to end; findings are advisory, and unused confidence and severity stay capped at medium pending 14 consecutive green nightly corpus runs. GhostDeps says what it could not verify instead of guessing - see Interpreting results before acting on a finding.

Use it as a GitHub Action

name: ghostdeps
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read # actions/checkout
  checks: write # create the ghostdeps check run
  pull-requests: read # added-line lookup for PR annotations

jobs:
  ghostdeps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: rowkavdev/ghostdeps/packages/action@main
        with:
          path: "."
          # fail-on: high   # opt in to gating; advisory by default

The action runs the analysis inside your job; there is no external service to install. It reports through GitHub: a ghostdeps check run on your own branches, or workflow annotations and the job summary on fork pull requests, where GITHUB_TOKEN is read-only. @main follows the latest main - pin a full commit SHA (rowkavdev/ghostdeps/packages/action@<sha>) for production workflows. Full input list and the known trade-offs versus the App: GitHub Action.

Use the CLI

The CLI is on npm as ghost-deps (Node 22+):

npx ghost-deps scan .
# or install it: npm install --global ghost-deps && ghostdeps scan .

Or build from source (pnpm via corepack):

git clone https://github.com/rowkavdev/ghostdeps.git
cd ghostdeps
corepack enable && pnpm install && pnpm build
node packages/cli/dist/main.js scan .

scan prints findings with evidence and confidence. --json emits the schema-versioned result; --fail-on high opts into a non-zero exit for CI gating. Commands, flags and exit codes: CLI.

What the check looks like

Findings land on a ghostdeps check run with an advisory conclusion: success (quiet) or neutral, never a blocking failure. Annotations appear only on high-confidence findings whose evidence points at a line the PR added. Every finding carries its evidence, a confidence level and stated limitations, and an incomplete scan says what it could not verify rather than calling packages unused. How to read verdict kinds, confidence levels and notes: Interpreting results.

Documentation

Use GhostDeps

• GitHub App and self-hosting it
• GitHub Action
• CLI and output formats
• Interpreting results

How it works

• Architecture and analysis engine
• Recommendation policy
• Security model - static analysis only, untrusted input, no code execution

Build and contribute

• Development and contributing adapters
• Decisions (ADRs)
• Contributing

License

MIT