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 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 init

For machine-readable CI proof:

npx pkgdiet demo --json

---

🚀 One-Command Setup

npx pkgdiet 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 (exit code 2 for Claude Code), the agent sees the denial reason and aborts the install — the command never runs.

Claude Code Plugin

PkgDiet is packaged as a Claude Code plugin featuring bundled MCP tools, slash commands (/pkgdiet:check, /pkgdiet:audit), skill definitions, and PreToolUse execution hooks:

/plugin install github:om-tajne/pkgdiet

*(Or /plugin install pkgdiet@claude-plugins-official once listed in the official directory)*

---

🔄 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

---

⚙️ 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" }, "staging": { "minHealthScore": 70, "failOn": "BLOCK", "securityMode": "fail-open" } } }

---

🤖 MCP Integration

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

When your AI coding agent connects to PkgDiet, it gains access to 5 read-only tools:

• check_dependency: Evaluates an npm package against your local .pkgdietrc.json policy and returns structured ALLOW, WARN, or BLOCK verdicts with evidence.
• check_dependencies: Bounded batch evaluation of up to 50 dependencies in a single tool call.
• suggest_alternative: Queries PkgDiet's curated dataset to find modern, lighter, and maintained alternatives for blocked packages.
• get_policy: Retrieves the active repository dependency policy rules and thresholds.
• explain_verdict: Detailed breakdown of package scoring, maintenance signals, and diagnostic codes.

Built-in Verification (all free, zero paid API keys):

• OSV vulnerability database — checks known CVEs via the public OSV advisory API
• npm registry provenance — verifies signed npm attestations
• Typosquat detection — edit-distance checks against popular package namespaces
• Lockfile pinning validation — enforces deterministic package resolution
• Dependency confusion detection — blocks internal-prefix packages found on public registries

---

💻 Requirements & Runtime Controls

• Node.js: Requires Node.js 20 or later (Node.js >=20).
• PKGDIET_NO_NETWORK=1: Runs completely offline using cached metadata; never contacts the external registry.
• PKGDIET_TELEMETRY_DISABLED=1: Disables local telemetry and metrics collection.
• PKGDIET_REGISTRY_URL: Overrides the default npm registry with a custom or private enterprise registry endpoint.
• .pkgdiet-cache.json: Local cache file storing validated package metadata and advisory results.
• .pkgdiet-metrics.json: Local metrics file for tracking audit performance and check history.

---

📦 Monorepo Architecture

---

⚖️ Legal, Privacy & Trademark Notice

• Advisory Tooling: PkgDiet is open-source software provided under the MIT License. It evaluates publicly available npm metadata and local project configurations according to user-defined policy. It provides advisory analysis only and does no