Skip to content
Back to search

bumpsmith

MarketplaceWorks with Claude CodeGitHub

Fixes your code when a dependency ships a breaking change: verified, reviewed pull requests from your own CI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bumpsmith/bumpsmith with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bumpsmith/bumpsmith'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bumpsmith--bumpsmith/badge.svg)](/listings/bumpsmith--bumpsmith)

HTML

<a href="/listings/bumpsmith--bumpsmith"><img src="/api/listings/bumpsmith--bumpsmith/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

GitHub Action: rescue red bot PRs automatically

npx bumpsmith init     # writes .github/workflows/bumpsmith.yml (wired to your CI) and .bumpsmith.yml

Add your model key as a repository secret. When CI fails on a Dependabot or Renovate pull request, Bumpsmith opens a companion PR with the same upgrade plus the code changes, links the two, and comments on the bot PR. If it can't produce a verified fix, it says why and lists the affected code instead. Full example: [`examples/bumpsmith.yml`](examples/bumpsmith.yml).

CLI: on your machine

Needs Node 22.13+ and Docker.

npx bumpsmith scan                     # which dependencies are a major (or more) behind; no AI
npx bumpsmith explain zod@4.1.0        # what breaks and where your code is affected
npx bumpsmith fix zod@4.1.0            # upgrade + fix + verify; writes a patch and evidence
npx bumpsmith fix zod@4.1.0 --apply    # ...and stage the patch if it was verified
npx bumpsmith rescue --github owner/repo --provider claude-code   # fix red bot PRs as PRs

Dashboard: review, apply, and run upgrades live

npx bumpsmith dashboard                # http://127.0.0.1:4477

The first start prints a one-time link that creates the owner account. Everything Bumpsmith did is there:

- each upgrade's pipeline and the breaking changes it read; - the diff, with the agent's edits marked; - your checks before and after, and the independent review.

**Apply patch** stages a verified result in one click.

<div align="center"> <br><sub><kbd>⌘</kbd> <kbd>K</kbd> to jump anywhere or start an upgrade, with the model and spend cap you choose.</sub> </div>

Self-hosted, for your team

cd deploy && echo "BUMPSMITH_DOMAIN=bumpsmith.acme.dev" > .env
openssl rand -base64 32 > master.key && docker compose up -d

The same app runs as a multi-user server behind HTTPS. It's built for security reviews from day one:

| Area | What you get | | ------- | -------------------------------------------------------------------------- | | Sign-in | SSO (OIDC and SAML) with group-to-role mapping; two-factor authentication. | | Access | Custom roles and an access matrix for each repository. | | Data | Encrypted secrets and a tamper-evident audit log. | | Setup | Onboarding in the browser. |

Read the [self-hosting guide](docs/self-hosting.md). The [security controls](docs/security/controls.md) page maps every control to SOC 2, ISO 27001, NIST 800-63B and OWASP ASVS.

<div align="center"> </div>

From your AI agent: MCP server and skill

Give Claude Code, Codex, Cursor, VS Code or any MCP client the tools to upgrade dependencies with proof. They can:

- check whether a release is safe to adopt; - explain what breaks; - run a verified upgrade; - read the evidence and apply the result.

/plugin marketplace add bumpsmith/bumpsmith      # Claude Code: MCP server + skill
/plugin install bumpsmith@bumpsmith
claude mcp add bumpsmith -- npx -y bumpsmith@latest mcp     # or: codex mcp add bumpsmith -- npx -y bumpsmith@latest mcp

[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=bumpsmith&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJ1bXBzbWl0aEBsYXRlc3QiLCJtY3AiXX0=) · [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=bumpsmith&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22bumpsmith%40latest%22%2C%22mcp%22%5D%7D) · [Skill file](skills/bumpsmith/SKILL.md) · [All clients, tools, and HTTP access for teams](docs/mcp.md)

A self-hosted Bumpsmith also serves MCP at `/mcp` for your applications, with personal API tokens. The access matrix and the audit log apply there too.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "bumpsmith",
  3. "owner": { "name": "Bumpsmith", "url": "https://github.com/bumpsmith" },
  4. "metadata": {
  5. "description": "Bumpsmith: dependency upgrades that are verified in a sandbox before you see them."
  6. },
  7. "plugins": [
  8. {
  9. "name": "bumpsmith",
  10. "source": "./",
  11. "description": "Upgrade npm and PyPI dependencies across breaking changes, verified with your own tests in a sandbox. MCP server plus skill.",
  12. "category": "development",
  13. "tags": ["dependencies", "upgrades", "mcp", "security"]
  14. }
  15. ]
  16. }
README.md · README · 344 lines
  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="dashboard/brand/wordmark-dark.svg">
  4. <img alt="Bumpsmith" src="dashboard/brand/wordmark-light.svg" height="56">
  5. </picture>
  6. ### Fixes your code when a dependency ships a breaking change.
  7. Dependabot and Renovate open the pull request. Bumpsmith makes it green:<br>
  8. it reads the changelog, fixes your code in a sandbox, proves it with your own tests, and shows its work.
  9. [![CI](https://github.com/bumpsmith/bumpsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/bumpsmith/bumpsmith/actions/workflows/ci.yml)
  10. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-f25a1d)](LICENSE)
  11. [![Node](https://img.shields.io/badge/node-%E2%89%A522.13-3c3c3a)](package.json)
  12. [![npm and PyPI](https://img.shields.io/badge/ecosystems-npm%20%C2%B7%20PyPI-3c3c3a)](#supported)
  13. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-1a7f4b)](CONTRIBUTING.md)
  14. [**Quick start**](#quick-start) · [**MCP & skill**](docs/mcp.md) · [**How it works**](#how-it-works) · [**Benchmarks**](#benchmarks) · [**Self-hosting**](docs/self-hosting.md) · [**Security**](#how-it-stays-safe)
  15. <a href="docs/media/hero.mp4">
  16. <picture>
  17. <source media="(prefers-color-scheme: dark)" srcset="docs/media/hero-dark.webp">
  18. <img alt="Bumpsmith fixing a node-fetch 2 to 3 upgrade: the changelog it read, the code it changed, the checks before and after, and the independent review" src="docs/media/hero.webp" width="100%">
  19. </picture>
  20. </a>
  21. <sub>A real upgrade from the benchmark, no cuts: <code>node-fetch</code> 2 → 3 went ESM-only and dropped <code>timeout</code>. Bumpsmith wrote the wrapper, mapped the option, ran the tests, and its reviewer flagged the one thing tests couldn't prove. <a href="docs/media/hero.mp4">Watch the MP4</a>.</sub>
  22. </div>
  23. ---
  24. ## Why
  25. Keeping dependencies current is easy until a **major** version lands. The bot opens a pull
  26. request, CI goes red, and someone has to read three changelogs, find every call site, and
  27. fix them. That PR sits for weeks; meanwhile you fall further behind on security fixes.
  28. Bumpsmith does that someone's job, and it is built to be trusted with it:
  29. - **It proves the fix.** Your install, build, typecheck, lint and tests run in an isolated
  30. container before and after the upgrade. No passing check, no "ready".
  31. - **It shows its sources.** Every breaking change it acts on is quoted word for word from the
  32. release notes, the migration guide or the type definitions, with a link.
  33. - **It gets a second opinion.** A separate reviewer and plain-code safety rules check the diff
  34. before anything is written, and say what they could not verify.
  35. - **A human always merges.** Bumpsmith opens a pull request or stages a patch. It never pushes
  36. to your default branch.
  37. ## Quick start
  38. ### GitHub Action: rescue red bot PRs automatically
  39. ```sh
  40. npx bumpsmith init # writes .github/workflows/bumpsmith.yml (wired to your CI) and .bumpsmith.yml
  41. ```
  42. Add your model key as a repository secret. When CI fails on a Dependabot or Renovate pull
  43. request, Bumpsmith opens a companion PR with the same upgrade plus the code changes, links the
  44. two, and comments on the bot PR. If it can't produce a verified fix, it says why and lists the
  45. affected code instead. Full example: [`examples/bumpsmith.yml`](examples/bumpsmith.yml).
  46. ### CLI: on your machine
  47. Needs Node 22.13+ and Docker.
  48. ```sh
  49. npx bumpsmith scan # which dependencies are a major (or more) behind; no AI
  50. npx bumpsmith explain zod@4.1.0 # what breaks and where your code is affected
  51. npx bumpsmith fix zod@4.1.0 # upgrade + fix + verify; writes a patch and evidence
  52. npx bumpsmith fix zod@4.1.0 --apply # ...and stage the patch if it was verified
  53. npx bumpsmith rescue --github owner/repo --provider claude-code # fix red bot PRs as PRs
  54. ```
  55. ### Dashboard: review, apply, and run upgrades live
  56. ```sh
  57. npx bumpsmith dashboard # http://127.0.0.1:4477
  58. ```
  59. The first start prints a one-time link that creates the owner account. Everything Bumpsmith did
  60. is there:
  61. - each upgrade's pipeline and the breaking changes it read;
  62. - the diff, with the agent's edits marked;
  63. - your checks before and after, and the independent review.
  64. **Apply patch** stages a verified result in one click.
  65. <div align="center">
  66. <img alt="The command menu: search upgrades and dependencies, then start an upgrade with a model and a budget" src="docs/media/command-menu.webp" width="80%">
  67. <br><sub><kbd>⌘</kbd> <kbd>K</kbd> to jump anywhere or start an upgrade, with the model and spend cap you choose.</sub>
  68. </div>
  69. ### Self-hosted, for your team
  70. ```sh
  71. cd deploy && echo "BUMPSMITH_DOMAIN=bumpsmith.acme.dev" > .env
  72. openssl rand -base64 32 > master.key && docker compose up -d
  73. ```
  74. The same app runs as a multi-user server behind HTTPS. It's built for security reviews from
  75. day one:
  76. | Area | What you get |
  77. | ------- | -------------------------------------------------------------------------- |
  78. | Sign-in | SSO (OIDC and SAML) with group-to-role mapping; two-factor authentication. |
  79. | Access | Custom roles and an access matrix for each repository. |
  80. | Data | Encrypted secrets and a tamper-evident audit log. |
  81. | Setup | Onboarding in the browser. |
  82. Read the [self-hosting guide](docs/self-hosting.md). The [security controls](docs/security/controls.md)
  83. page maps every control to SOC 2, ISO 27001, NIST 800-63B and OWASP ASVS.
  84. <div align="center">
  85. <img alt="Inviting a teammate, granting access per repository, single sign-on settings and the hash-chained audit log" src="docs/media/team.webp" width="80%">
  86. </div>
  87. ### From your AI agent: MCP server and skill
  88. Give Claude Code, Codex, Cursor, VS Code or any MCP client the tools to upgrade dependencies with proof. They can:
  89. - check whether a release is safe to adopt;
  90. - explain what breaks;
  91. - run a verified upgrade;
  92. - read the evidence and apply the result.
  93. ```text
  94. /plugin marketplace add bumpsmith/bumpsmith # Claude Code: MCP server + skill
  95. /plugin install bumpsmith@bumpsmith
  96. ```
  97. ```sh
  98. claude mcp add bumpsmith -- npx -y bumpsmith@latest mcp # or: codex mcp add bumpsmith -- npx -y bumpsmith@latest mcp
  99. ```
  100. [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=bumpsmith&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJ1bXBzbWl0aEBsYXRlc3QiLCJtY3AiXX0=) · [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=bumpsmith&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22bumpsmith%40latest%22%2C%22mcp%22%5D%7D) · [Skill file](skills/bumpsmith/SKILL.md) · [All clients, tools, and HTTP access for teams](docs/mcp.md)
  101. A self-hosted Bumpsmith also serves MCP at `/mcp` for your applications, with personal API tokens.
  102. The access matrix and the audit log apply there too.
  103. ## How it works
  104. ```mermaid
  105. flowchart LR
  106. A["Bot PR goes red<br/>or you pick an upgrade"] --> B["Read what changed<br/>release notes · changelog<br/>migration guide · .d.ts diff"]
  107. B --> C["Map the impact<br/>every affected call site"]
  108. C --> D["Sandbox: checks before"]
  109. D --> E["Bump, then fix<br/>confined file tools only"]
  110. E --> F["Sandbox: checks after<br/>compared with before"]
  111. F -->|regressions| E
  112. F --> G["Independent review<br/>+ plain-code rules"]
  113. G --> H["Pull request or patch<br/>with the evidence"]
  114. ```
  115. 1. **Read.** Release notes, changelogs, migration guides and the type definitions of both
  116. versions become a list of breaking changes. Each one is backed by a verbatim quote.
  117. 2. **Map.** Every place your code touches a changed API, found with AST search.
  118. 3. **Fix.** The upgrade is installed and the code edited in an isolated container. The model
  119. gets only file tools confined to the repository, and the named check commands.
  120. 4. **Verify.** Your own checks run before and after. Failures that existed before the upgrade
  121. are not counted against it; new ones send the agent back for another round.
  122. 5. **Review.** A separate model reviews the diff against the evidence. Rules written in plain
  123. code block new network or process calls, new dependencies, weakened tests and protected
  124. paths.
  125. 6. **Hand over.** A pull request (or patch) states:
  126. - what changed upstream;
  127. - what changed in your code, and why;
  128. - which checks pass before and after;
  129. - what could not be verified.
  130. ## Benchmarks
  131. Measured on real upgrades that broke something and that a human later fixed in a merged
  132. pull request. Bumpsmith replays each one from the commit before the human's fix.
  133. On a **held-out set** of 24 upgrades from repositories never used in development:
  134. | Metric | Result |
  135. | --------------------------- | ----------------------------------------------------- |
  136. | Verified fixes | **12 of 22** it could run (55%), 4 at high confidence |
  137. | Correctly refused | 1 (the target release is a known malicious package) |
  138. | Safety-rule false positives | 0 |
  139. | Model cost | **$0.73** per verified fix (API list price) |
  140. | Median time | 3.3 minutes |
  141. On 42 real repositories of 13 shapes (npm, pnpm, Yarn, Bun, workspaces, pip, Poetry, uv,
  142. Pipenv and others), Bumpsmith sets up 38 and verifies 32 with no crashes; the rest say why.
  143. Methods, caveats and raw data: [bench/RESULTS.md](bench/RESULTS.md) and [bench/ZOO.md](bench/ZOO.md).
  144. ## How it compares
  145. | | Dependabot / Renovate | AI coding agents | **Bumpsmith** |
  146. | ------------------------------------- | :-------------------: | :--------------: | :--------------------------------------: |
  147. | Opens upgrade PRs | ✓ | — | ✓ (rescues theirs) |
  148. | Fixes code a breaking change broke | — | ✓ | ✓ |
  149. | Reads the changelog and quotes it | — | sometimes | ✓ every change, with sources |
  150. | Runs your tests before **and** after | — | sometimes | ✓ in an isolated sandbox |
  151. | Independent review of the diff | — | — | ✓ plus plain-code rules |
  152. | Refuses malicious or too-new releases | partly | — | ✓ OSV check and a 3-day release-age gate |
  153. | No network for the code it runs | — | — | ✓ only a read-only registry mirror |
  154. | Runs in your CI, with your model key | ✓ | varies | ✓ |
  155. ## How it stays safe
  156. Bumpsmith runs code it didn't write (your dependencies' install and test steps) and lets a model
  157. edit your repository, so it treats both as hostile.
  158. - **Isolated execution.** Each run is a container with:
  159. - no credentials, and no environment passed in from the host;
  160. - limits on CPU, memory, processes and time;
  161. - no network, except during installs, when the only reachable server is a read-only registry
  162. mirror. It allows only `GET`/`HEAD` to npm and PyPI.
  163. - **Supply-chain caution.**
  164. - New versions are used only after a 3-day release-age wait.
  165. - Install scripts are off.
  166. - Versions on the OSV malicious-package list are refused.
  167. - **Limited AI.** The agent has no shell, so it can't edit CI workflows, secrets or
  168. infrastructure. Secrets found in files are masked before anything reaches the model.
  169. - **Strict publishing.** The publishing step re-checks the reviewed patch's hash and the rules,
  170. and rebuilds every file from your default branch with a no-fuzz patch.
  171. - **Respect for your repository.** Bumpsmith never:
  172. - overwrites a commit a human pushed;
  173. - reopens a PR you closed;
  174. - force-pushes your branches.
  175. It labels its PRs `ai-generated`, with the model named.
  176. Found a hole? Please report it privately: [SECURITY.md](SECURITY.md).
  177. ## Supported
  178. | | |
  179. | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  180. | **Ecosystems** | npm (npm, pnpm, Yarn 1–4, Bun, workspaces) · PyPI (pip, uv, Poetry, PEP 621) |
  181. | **Models** | Anthropic, OpenAI, Gemini, OpenRouter, Groq, Together, DeepSeek, or any OpenAI-compatible endpoint. On your own machine you can also use your Claude Code or Codex subscription. |
  182. | **CI** | GitHub Actions (Linux runners with Docker) |
  183. | **Test services** | Postgres, MySQL, MariaDB, Redis, Valkey and Mongo, started from your workflow's `services:` |
  184. <details>
  185. <summary><b>Configuration</b> (<code>.bumpsmith.yml</code>, optional)</summary>
  186. ```yaml
  187. version: 1
  188. ecosystems: [npm, pypi]
  189. release_age_days: 3 # can be raised, not lowered
  190. limits:
  191. open_pull_requests: 3
  192. ignore:
  193. - package: react
  194. versions: ["19.x"]
  195. checks: # optional; detected automatically
  196. test: "pnpm test"
  197. pull_requests:
  198. labels: [dependencies, bumpsmith]
  199. draft_below: medium # open as draft below this confidence
  200. rules:
  201. protected_paths: ["infra/**"]
  202. ```
  203. Config is read only from your default branch. It can tighten Bumpsmith's rules but never loosen
  204. them. Commands are plain argv (no shell operators).
  205. </details>
  206. <details>
  207. <summary><b>Tokens for the GitHub Action</b></summary>
  208. Pull requests opened with the default `GITHUB_TOKEN` [don't trigger your CI](https://docs.github.com/en/actions/concepts/security/github_token).
  209. Create a small GitHub App for your organisation:
  210. - **Permissions:** Contents and Pull requests (write), and Checks (read).
  211. - **Install** it on the repository.
  212. - **Secrets:** set the `BUMPSMITH_APP_ID` variable and the `BUMPSMITH_APP_PRIVATE_KEY` secret.
  213. The example workflow then uses [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token).
  214. </details>
  215. ## FAQ
  216. <details>
  217. <summary><b>Does my code leave my machine or CI?</b></summary>
  218. Only to the model provider you configure, and only what the agent reads. Secrets found in files
  219. are masked first. The dashboard has no analytics or other telemetry, and its fonts are bundled.
  220. </details>
  221. <details>
  222. <summary><b>What does it cost?</b></summary>
  223. On the held-out benchmark, $0.73 of model usage per verified fix at API list prices.
  224. You set a spend cap per run. On your own machine you can use your Claude Code or Codex
  225. subscription instead of an API key.
  226. </details>
  227. <details>
  228. <summary><b>How is this different from asking a coding agent to do the upgrade?</b></summary>
  229. An agent edits code. Bumpsmith adds three things around it:
  230. - **Evidence:** it reads the release notes and quotes them.
  231. - **Proof:** your checks run before and after, in a sandbox with no network.
  232. - **A gate:** an independent review plus rules that decide whether the result reaches you.
  233. When it can't prove a fix, it says so instead of guessing.
  234. </details>
  235. <details>
  236. <summary><b>What happens when it can't fix something?</b></summary>
  237. You get a "needs a human" result, with:
  238. - the breaking changes;
  239. - every affected call site;
  240. - what it tried;
  241. - why it stopped (for example, the tests already failed before the upgrade, or a package
  242. needs a system library).
  243. </details>
  244. ## Limitations
  245. - **Grouped bot PRs:** they are handled as one job. The biggest major jump is analysed in depth
  246. and the other packages are upgraded with it.
  247. - **Private registries and git dependencies:** not supported in the sandbox yet.
  248. - **The GitHub Action:** needs Linux runners with Docker.
  249. ## Contributing
  250. Bug reports, repositories that trip it up, and pull requests are all welcome. See
  251. [CONTRIBUTING.md](CONTRIBUTING.md).
  252. ```sh
  253. pnpm install && pnpm check # typecheck, lint, unit and Action tests
  254. pnpm test:docker # sandbox isolation and exfiltration tests
  255. pnpm bumpsmith dashboard # the dashboard, from source
  256. ```
  257. The videos in this README are recorded from the real dashboard by
  258. [`scripts/demo`](scripts/demo). Re-record them after a UI change.
  259. ## License
  260. [Apache-2.0](LICENSE). Bumpsmith is free to self-host. A hosted version for teams is on the way.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.