Set up ghostimport

Install

Requires Node.js 22 or newer. Zero runtime dependencies — the published package uses only Node built-ins.

# global — recommended if you'll use the hook
npm install -g ghostimport

# one-off, no install
npx ghostimport

# as a dev dependency
npm install --save-dev ghostimport

Quick start

Point it at a project. One mode, no flags to discover — the supply-chain analysis always runs.

$ ghostimport

  Scanned 142 files · 38 packages

  ✗ react-server-fetch  does not exist on npm
    ↳ src/data/loader.ts
    ↳ unregistered — anyone could claim this name with a malicious postinstall

  ✗ axois  high risk
    ↳ src/api/client.ts
    ↳ 1-2 chars from 'axios' — likely a typo
    ↳ single version published
    created 2019-08-29 · 1245/week · 1 version

  ⚠ not in package.json: zod

  2 problems found.

It exits 1 when an imported or declared package doesn't exist and 0 otherwise, so it works as a CI gate with no extra configuration.

Agent hooks

The enforcing integration. Hooks run on every matching tool call whether or not the model cooperates — unlike MCP tools, which the model has to choose to call.

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "ghostimport hook" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "ghostimport hook" }]
      }
    ]
  }
}

What each one does

• PreToolUse on Bash — parses any npm, pnpm, yarn or bun install command and denies the tool call if it would fetch a package that doesn't exist, is a typosquat, or ships an install script. This is the one that stops a real attack, because it fires before the postinstall could run.
• PostToolUse on edits — reads the file the agent just wrote, extracts its imports, and reports any that don't resolve. For a package.json, it checks the dependencies the edit added instead.

What the agent sees when it's blocked

ghostimport blocked this: the install command below would fetch packages
that are unsafe or do not exist.

  • 'axois' exists but is high risk: name is 1-2 chars from 'axios';
    single version published.

Do not retry this command as written. Remove the flagged packages, correct
the name if it was a typo, and tell the user what was flagged and why.

Results are cached for 24 hours in ~/.ghostimport/, so the steady state is zero network calls.

MCP server

Gives the model tools to check a name before it commits to writing the import. Use it alongside hooks, not instead of them — this one depends on the model choosing to call it.

claude mcp add ghostimport -- npx -y ghostimport mcp

For Cursor, Windsurf, Zed or any other MCP client, add to its config:

{
  "mcpServers": {
    "ghostimport": {
      "command": "npx",
      "args": ["-y", "ghostimport", "mcp"]
    }
  }
}

Tools it exposes

CLI

ghostimport [dir] [options]
ghostimport mcp | hook

Options

Commands

• ghostimport mcp — run as an MCP server over stdio
• ghostimport hook — run as an agent hook, reading a hook payload on stdin

JSON output

{
  "scanned": 142,
  "packages": 38,
  "missing":    [{ "pkg": "react-server-fetch", "files": [...], "claimable": true }],
  "undeclared": [{ "pkg": "zod", "files": [...] }],
  "risks":      [{ "pkg": "axois", "type": "suspicious", "risk": "high", ... }],
  "errors":     [],
  "cacheHits":  33
}

README badge

Run a scan with --badge and it prints ready-to-paste Markdown for your project's README, reflecting the result of that scan.

$ ghostimport --badge

  README badge:
  [![ghostimport](https://img.shields.io/badge/ghostimport-%E2%9C%93%20clean-brightgreen)](https://github.com/FGuerreir0/ghostimport)

The two states

Clean. Every imported package resolves on npm.

Ghosts found. The count is how many imported packages don't exist.

Copy the clean badge

Config file

Optional. Drop a .ghostimportrc.json in your project root.

{
  "ignore": ["@company/*", "internal-lib"],
  "includeUndeclared": true
}

Workspace packages in a monorepo and paths aliases from your tsconfig are detected automatically — you don't need to list them.

JavaScript API

Ships with TypeScript declarations. Seven exports, each with one job.

import { verifyPackages, scan } from 'ghostimport'

// check names directly
await verifyPackages(['axios', 'axois'], { deep: true })
// [ { pkg: 'axios', status: 'ok', typosquatOf: null },
//   { pkg: 'axois', status: 'suspicious', risk: 'high', typosquatOf: 'axios', ... } ]

// scan a directory
const { missing, undeclared, risks } = await scan('./src')

Verdict statuses

Exports

What gets scanned

Detected: import, require(), dynamic import(), export … from, scoped packages, and subpath imports (pkg/utils resolves to pkg).

Declared: every registry dependency in any package.json, whether or not anything imports it. workspace:, file:, link:, git and URL specs are skipped, and npm: aliases are followed to the real name.

Extensions: .js .jsx .ts .tsx .mjs .cjs .vue .svelte .astro

For .vue, .svelte and .astro, only <script> blocks and Astro frontmatter are read — markup is ignored, so a package name that appears in template text is never flagged.

Ignored:

• Node built-ins, including node: prefixed ones
• Relative imports (./, ../)
• Path aliases — @/, ~/, $lib/, and tsconfig paths
• URL and protocol imports, and virtual modules (virtual:, Vite internals)
• Workspace packages in a monorepo
• node_modules/, dist/, build/, .git/

Risk signals

A name that resolves isn't automatically safe. These signals are checked against packages that exist but aren't declared in your package.json.

Rated high if any critical signal fires or two medium ones do; only medium and high are reported.

CI

The CLI already exits non-zero on a missing package, so the simplest form is one line.

- name: Check for hallucinated packages
  run: npx ghostimport --quiet

Or use the action, which also writes a job summary and exposes counts as outputs:

- uses: FGuerreir0/ghostimport@v0.5.0
  with:
    path: '.'

For pre-commit, in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/FGuerreir0/ghostimport
    rev: v0.5.0
    hooks:
      - id: ghostimport