Uptide
Migrations you can merge.
Uptide finds what a dependency upgrade breaks in your code, migrates it, and proves it with
your compiler and tests.
Quickstart
No account, no config. Node 20 or newer. check works on npm, pnpm, Yarn and bun (text
lockfile); fix on npm, pnpm and Yarn with the node-modules linker. In your repository:
npx uptide list # fast discovery; no install or compilation
npx uptide check zod # analyze one or more named dependencies (install first)
npx uptide fix zod # migrate on a new branch, verified; nothing is pushed
npx uptide pr --branch uptide/zod-4.6.5 # prints the plan; add --yes to push and open a draft PR
npx uptide with no command shows where zod and stripe stand: installed, latest, majors behind. fix
preserves workspace and companion ranges that already accept the target, reports them as already
compatible, and widens rejecting peer ranges without dropping existing alternatives. What the target
requires moves within its major, else is a blocker; a deprecated @types stub is removed, not
upgraded. Lockfile, target and companions must match the planned versions, or fix and verify fail. fix discovers a unique nested project with its own lockfile when the root does not declare the dependency, and scopes installation, verification and migration to it. If several projects match, select one with --cwd frontend.
Draft PR runs update conflicting root Yarn resolutions and npm/pnpm overrides and put them under Root pins changed: review. Set updatePins: false in uptide.yml to opt out. Local runs require --update-pins; unrelated pins stay unchanged. npm pins use Corepack when needed, or local npm 9+ with a v3 lockfile and a report note; frozen installs must leave the lockfile unchanged. Everything else: getting started.
Why Uptide
- Renovate and Dependabot bump the version. Uptide says what the bump breaks in your code,
fixes it on a branch, and verifies the result with your compiler and your tests.
- Breaking findings require compiler, runtime, or pack confirmation. Everything else is possible impact.
Compiler errors outside your tsconfig projects never count; pack rules still apply. Without a tsconfig, importer-based
compilation is used and reported.
- A migration is a pull request you can read: rule-based edits first, assisted edits only
where a rule cannot, each kept only if its compiler error disappears and no new one
appears, and a report that says what was verified and what was not. Accepted agent edits
include a representative diff and affected files; choices from migration guides appear
under Decisions for you with their reasoning and alternatives. Large PR descriptions trim changelog detail before review evidence.
- Runs locally, no account. Code leaves your machine only for assisted fixes in
fix, which
runs them with the Claude Agent SDK and your own Anthropic API key.
Verified packs
A pack is everything Uptide knows about one upgrade: rules, a guide for the agent, behavior
checks, and ground truth from public repositories it is scored against. Precision is breaking findings
on a ground-truth site; the Found columns are shares of every breaking site scored, by any finding and by a
breaking one (definitions). Verified: two or more public repositories, five real sites, no false positive.
See the pack compatibility matrix and the migration pack contract.
| Package | From → to | Rules | Precision | Found, any severity | Found as breaking | Breaking sites | Ground-truth repositories | Status |
|---|
ai | 6 → 7 | 12 | 100% | 82% | 82% | 11 | vercel/chatbot, miurla/morphic | verified |
express | 4 → 5 | 8 | 100% | 86% | 86% | 86 | netlify/cli, bcgov/tenant-management-system, amiantos/lurker, openhab/openhab-cloud | verified |
lucide-react | 0 → 1 | 5 | 100% | 100% | 100% | 11 | tradeblocks-org/tradeblocks, spizeck/SFPCA, cubicsteak/keep | verified |
next | 15 → 16 | 9 | 100% | 88% | 88% | 34 | sambecker/exif-photo-blog, stoczec/wortkarte, benshabbat/GamesForMyKids, HiroshiIgarash/koremina | verified |
react | 18 → 19 | 8 | 100% | 95% | 95% | 130 | excalidraw/excalidraw, tldraw/tldraw | verified |
react-router | 6 → 7 | 13 | 100% | 89% | 78% | 18 | Arize-ai/phoenix, getlago/lago-front | verified |
redis | 4.x/5.x → 5.x/6.x | 14 | 100% | 85% | 75% | 20 | deanmoses/tacocat-gallery-sam, swoofer/mcp-coordinator, UNN-Devotek/FCM-Fallout-Chat-Mod, tearingItUp786/blog |
4 more in validation: see the compatibility matrix.
Any other dependency gets the same analysis without a pack, and fix migrates it with the
agent alone (concepts).
Before and after
fixtures/repos/storefront is a small pnpm workspace in this
repository, written to exercise Uptide: two packages on zod 3 and stripe 14, with a few
tests. Everything below is real output from it.
Before: check. What breaks, where, and who can fix it:
$ npx uptide check zod
uptide check · storefront · pnpm · 26s
zod 3.25.76 → 4.6.5 major · latest on npm verified ✗ 28 breaking in 7 files 24 auto-fixable · 4 need the agent (LLM)
zod 28 breaking · compiled against 4.6.5: 28 new type errors
compiled 8 of 8 files in 2 workspaces with the repo's TypeScript 5.9.3
✗ New error API (required_error → error) 24 sites auto-fixable
✗ ZodTypeDef removed 1 fix, 3 errors needs the agent (LLM)
✗ .ip() removed monitoring.ts:6 needs the agent (LLM)
! 15 deprecated calls (.uuid, .datetime, .email, ...) 8 auto-fixable
Next
npx uptide fix zod migrate on a new branch, verify, no push
npx uptide check zod --details every site and reason
After: fix, on its own verified branch:
$ npx uptide fix zod
uptide fix · zod 3.25.76 → 4.6.5 (latest on npm) · verification passed · 36s
Risk Medium: request validation in webhooks
Changes 29 sites in 8 files · 25 auto-fixed · 4 fixed by the agent (LLM)
Types ✅ the upgrade broke 28 · Uptide left 0 (1 pre-existing, not counted)
Behavior ✅ 9 schemas identical · 2 not checked · 21/21 custom-message assertions
Tests ✅ 5 tests in 3 files passed
No compiler sees this one: zod 4 words its default messages differently, and a test that
asserted the old wording failed after the migration. Uptide updated it and says so in the
pull request, so you can check that nothing else reads that text:
- expect(parsed.error?.issues[0]?.message).toBe('Required');
+ expect(parsed.error?.issues[0]?.message).toBe('Invalid input: expected string, received undefined');
The stripe run from the same fixture, and what each step of fix does, are in
npx uptide fix.
Privacy
Analysis runs locally, with no account and no Uptide server. Code leaves your machine only
for assisted fixes in npx uptide fix, which runs them with the Claude Agent SDK and your
own ANTHROPIC_API_KEY. check loads your installed typescript to compile with and runs none of
your scripts. Anonymous telemetry is off by default and collects no IP, code, paths or repo names.
| Where it runs | What leaves your machine |
|---|
list, plan | locally | package names/versions requested from your npm registry, and list sends public packages' names and installed versions to npm's advisory endpoint; metadata only, no source code |
check | locally | nothing of yours; it downloads package tarballs from your npm registry. No LLM call. It loads your installed typescript package to compile with, and runs no script or other code of yours. |
fix, rules and verification | locally, in a temporary clone | nothing of yours |
fix, assisted fixes | Anthropic's API, with your ANTHROPIC_API_KEY, through the Claude Agent SDK | findings, enclosing code, compiler-linked declarations and errors, files read throughout the clone and output from its checks |
pr, fix --pr | GitHub, through your own gh | the branch and the pull request, when you say so |
The full statement and the isolation model: privacy and SECURITY.md.
Documentation
- Getting started, concepts and
troubleshooting
- Commands:
list, check,
plan, fix, pr,
telemetry, init and
uptide.yml
- Models, CI with the GitHub Action, FAQ
- Architecture, decisions and the rest of the
Contributing
CONTRIBUTING.md covers setup, safety, pack authoring and sign-off. Smoke-test packs with check --allow-candidate or fix --allow-candidate: reports say “candidate pack, not verified”.
The flag is local only: the Action, --pr and --yes reject it. Security problems: SECURITY.md.
License
Apache-2.0. Releases up to and including 0.3.0 were published under the MIT
license; 0.4.0 and later are Apache-2.0.
