io.github.om-tajne/pkgdiet

🥗 PkgDiet

Dependency policy for AI-assisted JavaScript and TypeScript development.
Put your node_modules on a diet.

The Problem: AI coding agents (Claude Code, Codex, Cursor, Windsurf, Cline) propose nonexistent, deprecated, vulnerable, or typosquatted packages. There is no built-in mechanism to stop them from running the install.

The Solution: PkgDiet intercepts every npm install / pnpm add / yarn add command your AI agent generates — using native agent hook APIs — and blocks unapproved installs before they execute.

🔒 Live Proof

Run this to see PkgDiet block real risky AI-generated dependencies in your terminal:

npx pkgdiet@2.0.1 demo

Example output:

🔒 PkgDiet — Live AI Dependency Enforcement Demo
   Simulating what happens when an AI agent tries to install these packages.

🟡  WARNING — moment
   Context:   AI suggested this for date formatting
   Score:     100/100
   Reason:    Efficiency Flag: Better alternatives exist for moment.
   Use this:  dayjs, date-fns

🔴  BLOCKED — request
   Context:   AI suggested this for HTTP requests
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  undici, native fetch
   CVEs:      GHSA-p8p7-x288-28g6

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🔴  BLOCKED — node-uuid
   Context:   AI suggested this for UUID generation
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  crypto.randomUUID(), uuid

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🟡  WARNING — lodash
   Context:   AI suggested this for array utilities
   Score:     80/100
   Reason:    Efficiency Flag: Better alternatives exist for lodash.
   Use this:  lodash-es, native JS

📊 Demo Summary: 2 blocked, 2 warned
   These checks run automatically before every npm install in your AI agent.
   Setup: npx pkgdiet@2.0.1 init

For machine-readable CI proof:

npx pkgdiet@2.0.1 demo --json

🚀 One-Command Setup

npx pkgdiet@2.0.1 init

This single command creates:

🛡️ Enforcement by Agent

PkgDiet uses each agent's native hook API to block installs — not just advisory rules:

How PreToolUse hooks work: When Claude Code or Codex generates a Bash tool call containing npm install, the registered hook script runs first. If PkgDiet returns a non-zero exit code, the agent sees the denial reason and aborts the install — the command never runs.

🔄 The 3-Phase Policy Loop

PkgDiet uses a shared core engine (@pkgdiet/core) so all interfaces apply the same evaluation logic.

1. Repository Policy: A single .pkgdietrc.json file dictates what is allowed, warned, or blocked for your project.
2. Agent Hook (Enforce): Native PreToolUse hooks for Claude Code and Codex intercept install commands before execution. MCP check_dependency instructs other agents before they write the command.
3. CI Gate (Fallback): npx pkgdiet ci runs in GitHub Actions, diffs package.json against the base commit, and fails the PR if any added package violates policy.

🛠️ CLI Commands

Commands:
  audit           Audit existing dependencies for policy, health, size, and unused-package signals
  check           Evaluate npm packages against this repository's dependency policy
  demo            Show live proof that PkgDiet blocks risky AI-generated dependencies before install
  mcp             Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
  ci              Enforce policy for dependency changes introduced by this branch
  init            Set up PkgDiet — creates policy, CI workflow, and all AI agent configs
  agent-setup     Configure PkgDiet for AI coding agents (codex, cursor, claude-code, ...)
  alternatives    Browse the PkgDiet alternatives dataset
  drift           Scan project for dependency health drift over time
  policy-check    Validate the repository's .pkgdietrc.json policy

⚙️ Configuration (.pkgdietrc.json)

{
  "minHealthScore": 70,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "blockKnownVulnerabilities": true,
  "blockTyposquats": false,
  "requirePinnedVersions": true,
  "maxPackageSizeBytes": 15728640,
  "failOn": "BLOCK",
  "securityMode": "fail-open",
  "blockedPackages": ["moment", "request"],
  "internalNamePrefixes": [],
  "environments": {
    "ci": { "minHealthScore": 80, "failOn": "BLOCK", "securityMode": "fail-closed" },
    "dev": { "minHealthScore": 60, "failOn": "BLOCK", "securityMode": "fail-open" }
  }
}

🤖 MCP Integration

PkgDiet acts as a local Model Context Protocol (MCP) server.

When your AI coding agent connects to PkgDiet, it gains access to:

• check_dependency: Evaluates an npm package against your local .pkgdietrc.json policy and returns structured ALLOW, WARN, or BLOCK verdicts with evidence.
• suggest_alternative: Queries PkgDiet's curated dataset to find modern, lighter, and maintained alternatives for blocked packages.

Intelligence included (all free, no paid services):

• OSV vulnerability database — checks known CVEs for the package version
• npm registry provenance — verifies signed npm attestations
• Typosquat detection — edit-distance check against 15+ popular package names
• Lockfile pinning validation — requires exact version pins in CI
• Dependency confusion detection — blocks internal-prefix packages found on public registry

🔗 Documentation & Support

• GitHub Repository: om-tajne/pkgdiet
• Report an Issue: Issue Tracker
• License: MIT