dep-regret

README

🪶 dep-regret

Do you actually need that dependency?

dep-regret stops your AI agent (or you) from importing a 40 MB library for a 3-line job. For any package it shows the install size, how many dependencies it drags in, and whether a standard-library or native feature already does the job — then hands you a one-key, agent-ready prompt to inline it instead.

---

Try it in one line — no signup, no API key, no install:

go run github.com/agenticraptor/dep-regret/cmd/dep-regret@latest check moment

Or cd into any npm / Python / Rust / Go project and just run dep-regret.

dep-regret · ~/code/my-app
npm · 12

  REGRET      left-pad (npm)         10 KB  ▸ String.prototype.padStart()
  RECONSIDER  request (npm)         209 KB  ▸ fetch() or undici
  RECONSIDER  node-fetch (npm)      107 KB  ▸ global fetch()
  RECONSIDER  uuid (npm)             70 KB  ▸ crypto.randomUUID()
  RECONSIDER  is-odd (npm)            7 KB  ▸ n % 2 === 1
  REVIEW      moment (npm)          4.4 MB  ▸ Intl.DateTimeFormat, Temporal, date-fns…
  REVIEW      lodash (npm)          1.4 MB  ▸ native ES methods or single-method imports
  KEEP        express (npm)          75 KB  ▸ looks reasonable
  KEEP        react (npm)           172 KB  ▸ looks reasonable

  ────────────────────────────────────────────────────
  You could save ~6.5 MB and 26 dependencies
  by inlining 10 of 12 dependencies.

  Run `dep-regret inline left-pad` for an agent-ready prompt to remove it.

Why

AI coding agents add dependencies the way other people add browser tabs. A prompt says "parse this date" and suddenly moment (4.4 MB) is in your package.json. "Pad a string" pulls in left-pad. "Make a UUID" adds a package for something crypto.randomUUID() has done natively for years. This is a named, documented AI-tech-debt smell: dependency churn and 50 MB transitive trees for one-line problems.

dep-regret is the gut-check that fits between "I want X" and "X is now a permanent part of my supply chain":

• It quantifies the cost. Real install size (all four ecosystems) and direct-dependency count (npm and PyPI), pulled live from the registry — with an offline estimate when there's no network.
• It knows when a built-in already does it. A curated, human-reviewed knowledge base maps commonly-regretted packages to their standard-library or native replacement — left-pad → padStart, pytz → zoneinfo, lazy_static → LazyLock, github.com/pkg/errors → fmt.Errorf("%w").
• It offers a way out. dep-regret inline <pkg> prints a precise, copy-paste prompt that tells your coding agent exactly how to remove the dependency and replace it with native code.

And yes — dep-regret itself has zero third-party dependencies. It would be a little awkward otherwise. The whole tool is one small static binary built from the Go standard library. Run dep-regret on its own repo and watch it report nothing to regret.

Features

• 🔎 scan any project and rank every dependency by a 0–100 regret score, with a quotable headline: "save ~6.5 MB and 26 dependencies."
• 🧪 check <pkg> a single package before you add it — settle the "do I really need this?" argument in one command.
• 🧠 Curated knowledge base of 70+ commonly-regretted packages across npm, PyPI, Cargo, and Go, each mapped to its native/stdlib replacement with a line-count estimate and a fair, nuanced note.
• 🤖 inline <pkg> generates an agent-ready prompt to vendor/replace the dep (works offline, no key). With --apply and an API key it drafts the replacement itself (Anthropic, OpenAI, or a local Ollama).
• 🛡️ guard installs shell hooks so npm install / pip install / cargo add / go get run a check — and ask for confirmation — before a flagged package lands.
• 🪫 Works with zero config and zero network. No registry access? You still get a verdict from the embedded knowledge base and size estimates.
• 📦 One tiny static binary. Zero dependencies. Naturally.

Install

go install

go install github.com/agenticraptor/dep-regret/cmd/dep-regret@latest

Pre-built binaries

Grab a binary for your OS/arch from the Releases page.

Homebrew (macOS / Linux)

brew install agenticraptor/tap/dep-regret

Available once the Homebrew tap is published — see the note in .goreleaser.yaml to enable it.

From source

git clone https://github.com/agenticraptor/dep-regret
cd dep-regret
make install

Quickstart

# 1. Scan the project in the current directory (works with zero setup)
cd ~/code/my-app
dep-regret

# 2. Should I add this package? Check before you commit to it.
dep-regret check moment
dep-regret check left-pad@1.3.0          # a specific version
dep-regret check pytz -e pypi            # pick the ecosystem explicitly

# 3. Get an agent-ready prompt to remove a dependency
dep-regret inline lodash                 # prints a prompt; pipe it to your agent
dep-regret inline lodash | pbcopy        # …or straight to the clipboard

# 4. Guard your package managers (asks before adding a flagged dep)
dep-regret guard --install               # adds a hook to your shell rc

# 5. Export a report for a PR or a teammate
dep-regret scan -f markdown -o dep-regret.md

Usage

dep-regret [path]                Scan a project and rank deps by regret (default)
dep-regret check <pkg>[@version] Analyze a single package before you add it
dep-regret inline <pkg>          Print an agent-ready prompt to inline a dep
dep-regret guard                 Install/print package-manager confirmation hooks
dep-regret doctor                Check your environment and registry access
dep-regret version

Common flags:

Flag	Description
-e, --ecosystem	npm · pypi · cargo · go (auto-detected for scan)
-f, --format	term · markdown · json · plain (default: term)
--offline	Skip registry lookups; use only the embedded knowledge base
--flagged	(scan) show only flagged dependencies
--top N	(scan) show only the N most-regretted dependencies
--apply	(inline) draft the replacement with a configured LLM
--color	auto · always · never
-o, --output <file>	Write the report to a file

How the regret score works

The score is deterministic and explainable — no model, no magic. Given the same inputs it always produces the same number, which is what makes the headline ("save ~6.5 MB") trustworthy. Each dependency starts at 0 and accrues points:

Signal	Points
A standard-library / native feature does the job (has_stdlib)	+55
It's a trivially-replaceable micro-package (micro)	+60
It's deprecated or unmaintained (deprecated)	+45
It's a heavyweight often used for a fraction of its surface (heavyweight)	+25
Registry reports it as deprecated	+40
Install size	+3 / MB (max +30)
Direct dependency count (npm / PyPI)	+1 / dep (max +15)

The total maps to a verdict:

Score	Verdict	Meaning
0–24	KEEP	Looks reasonable.
25–44	REVIEW	Worth a look.
45–69	RECONSIDER	You probably have a lighter option.
70–100	REGRET	You almost certainly don't need this.

Heavyweight, genuinely-useful libraries (axios, requests, testify) are scored gently on purpose — dep-regret flags them for a second look, not a witch hunt. See docs/scoring.md for the full rationale.

The knowledge base

The "a built-in already does this" judgments come from a curated, human-reviewed dataset (internal/knowledge/data/replacements.json), embedded into the binary so it works offline. A few examples:

Ecosystem	Package	Replace with	Since
npm	left-pad	String.prototype.padStart()	ES2017
npm	uuid	crypto.randomUUID()	Node 14.17
npm	node-fetch	global fetch()	Node 18
PyPI	pytz	zoneinfo	Python 3.9
PyPI	six	(write Python 3)	—
Cargo	lazy_static	std::sync::LazyLock	Rust 1.80
Cargo	num_cpus	std::thread::available_parallelism()	Rust 1.59
Go	github.com/pkg/errors	fmt.Errorf("%w", …)	Go 1.13
Go	github.com/sirupsen/logrus	log/slog	Go 1.21

Contributions to the knowledge base are the most valuable kind. Know a package that a built-in now replaces? Add an entry — it's one JSON object.

Guard your package managers

dep-regret guard --install        # writes a hook into ~/.zshrc or ~/.bashrc
# (or `dep-regret guard --print` to see the snippet and add it yourself)

After that, adding a flagged package pauses for confirmation:

$ npm install moment

moment (npm)
  Verdict   REVIEW  (regret score 38/100)
  Size      4.4 MB
  Replace   Intl.DateTimeFormat, Temporal, date-fns, or day.js

Add this dependency anyway? [y/N]

Remove it any time with dep-regret guard --uninstall.

Privacy

dep-regret runs entirely on your machine. By default it makes read-only requests to public package registries (npmjs.org, pypi.org, crates.io, proxy.golang.org) to look up real install sizes — that's the only network it touches. Pass --offline and it makes zero network calls, falling back to the embedded knowledge base and size estimates. The optional inline --apply feature is the only thing that contacts an LLM, and only when you ask it to.

How it works

manifest (package.json / requirements.txt / Cargo.toml / go.mod)
   │
   ├─► parse dependencies ─┐
   │                       │
registry lookup ───────────┼─► analyze ──► regret score + verdict ──► render
(size, dep count,          │   (knowledge base + size + deps)          (term / md / json)
 deprecation; optional) ───┘                       │
                                                   └─► inline ──► agent-ready prompt
                                                                  (+ optional LLM draft)

Contributing

Contributions are very welcome — see CONTRIBUTING.md. The highest-leverage contributions are new knowledge-base entries and support for more ecosystems (Ruby gems, Maven, NuGet…). Please also read our Code of Conduct.

License

MIT © 2026 agenticraptor and dep-regret contributors.