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 [email protected] 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 [email protected] init

For machine-readable CI proof:

npx [email protected] demo --json

---

🚀 One-Command Setup

npx [email protected] init

This single command creates:

File	Purpose
.pkgdietrc.json	Repository dependency policy
.github/workflows/pkgdiet.yml	GitHub Actions CI gate
.cursor/mcp.json	Cursor MCP server
.cursor/rules/pkgdiet.mdc	Cursor always-applied enforcement rule
.cursorrules	Cursor advisory rule (legacy)
.windsurfrules	Windsurf advisory rule
cline_mcp_settings.json	Cline MCP server
.github/mcp.json	GitHub Copilot MCP
CLAUDE.md	Claude Code advisory rule
.claude/settings.json	Claude Code PreToolUse hook registration
.claude/hooks/pkgdiet-install-guard.sh	Claude Code bash install guard
.codex/hooks.json	Codex PreToolUse hook registration
.codex/hooks/pkgdiet-install-guard.mjs	Codex Node.js install guard

---

🛡️ Enforcement by Agent

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

Agent	Enforcement Mechanism	What it blocks
Claude Code	PreToolUse bash hook (.claude/hooks/)	npm/pnpm/yarn install before execution
Codex (OpenAI)	PreToolUse Node.js hook (.codex/hooks/)	npm/pnpm/yarn install before execution
Cursor	MDC alwaysApply rule + MCP check_dependency	Prevents AI from writing install commands
Windsurf	.windsurfrules + MCP check_dependency	Prevents AI from writing install commands
Cline	MCP check_dependency	Blocks before install via tool call
GitHub Copilot	MCP check_dependency	Blocks before install via tool call
CI (GitHub Actions)	pkgdiet ci gate	Blocks PR merge if any new package fails policy

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