om-tajne/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:
**Example output:**
For machine-readable CI proof:
---
🚀 One-Command Setup
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.