ghostimport

Stops your AI coding agent from installing npm packages that don't exist.

How the attack works →

Your agent invents a package name. It doesn't exist on npm yet. Someone is watching for exactly that, and the moment they register it, npm install runs their postinstall script on your machine.

This is slopsquatting. Most dependency scanners inspect packages after they are installed; ghostimport checks names before they are — against the live registry, at the moment your agent writes or installs them.

$ 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
    ↳ has postinstall script — runs code on npm install
    created 2019-08-29 · 1245/week · 1 version

  2 problems found.

Install in Claude Code

One command installs the blocking hooks and the MCP server together:

/plugin install ghostimport --marketplace FGuerreir0/ghostimport

On Claude Code older than 2.1.275, add the marketplace first: /plugin marketplace add FGuerreir0/ghostimport, then /plugin install ghostimport@ghostimport.

The plugin runs the CLI bundled in the npm package — no global install, no npx on every edit. If you already wired the hooks into .claude/settings.json by hand, remove them when you install the plugin, or every command is checked twice. Node.js 22+. Zero runtime dependencies: the published package uses only Node built-ins.

For the CLI, CI, or another agent:

npm install -g ghostimport     # or: npx ghostimport

What it does in the agent loop

This is the part that matters. A CI check tells you about a bad package after it's in your repo; these stop it at the moment it's written.

Hooks — the enforcing one

The plugin installs these. To set them up by hand instead, install ghostimport globally (npm install -g ghostimport, since the hook runs ghostimport directly) and add to .claude/settings.json:

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

• PreToolUse on Bash and PowerShell (PowerShell is Claude Code's shell on Windows) — reads any install command, and any command that downloads and runs a package on the spot (npx, npm exec, npm create, pnpm dlx, yarn dlx, bunx), and denies the tool call if it would fetch a package that doesn't exist, is a typosquat, or runs an install script with no track record behind it. Established packages that ship one (esbuild, puppeteer) go through. This is the one that stops a real attack.
• PostToolUse on edits — checks imports the agent just wrote, or dependencies it just added to a package.json, and tells it to fix them.

npx <name> deserves the attention: it runs the package's code immediately, no postinstall needed, and agents copy npx commands out of READMEs and skill files without checking them. An npx of a bin your project already has installed (npx tsc) runs the local copy and isn't checked.

The agent sees why it was stopped:

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.

It fails open. Registry unreachable, malformed payload, or a check exceeding its 20-second budget → exits 0 and stays out of the way. A security tool that wedges your agent when you're offline gets uninstalled by Friday.

MCP — the self-service one

Lets the model verify a name before it writes the import. Hooks are mandatory; MCP tools are offered — use both.

claude mcp add ghostimport -- npx -y ghostimport mcp     # included in the plugin

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

CLI

ghostimport              # scan the current directory
ghostimport ./src        # scan a folder
ghostimport --json       # machine-readable
ghostimport --watch      # re-scan on change

Exits 1 if any imported package doesn't exist, so it works as a CI gate as-is.

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

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

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

API

import { verifyPackages, scan } from 'ghostimport'

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

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

status is 'ok' | 'missing' | 'suspicious' | 'unknown'. 'unknown' means the registry was unreachable — never treat it as a failure.

interface ScanResult {
  scanned: number
  packages: number
  missing: { pkg: string; files: string[]; claimable: boolean | null }[]
                                                  // don't exist on npm; claimable is false
                                                  // inside a scope someone already owns
  undeclared: { pkg: string; files: string[] }[]  // exist, but not in package.json
  risks: RiskEntry[]                              // supply-chain findings
  errors: { pkg: string; error: string; files: string[] }[]
  cacheHits: number
}

type RiskEntry =
  | { pkg: string; files: string[]; type: 'unregistered'; typosquatOf: string | null }
  | { pkg: string; files: string[]; type: 'suspicious'
      risk: 'medium' | 'high'; flags: string[]; installScripts: string[]
      typosquatOf: string | null; maintainers: number
      created: string; downloads: number | null; versions: number }

Contributing

Development setup, the source layout, and how the site in docs/ is built and deployed all live in CONTRIBUTING.md.

Support

ghostimport is free, MIT licensed and has no runtime dependencies — and it stays that way. If it caught something for you, you can buy me a coffee.

License

MIT