PricingSign inDownload

Blog / npm

Your coding agent rewrote package-lock.json: undo it and stop it

An agent deleted the lockfile, reinstalled and bumped versions nobody asked for. Spot it, get the old lockfile back, fix lockfile conflicts, and block it.

On this page
  1. Why deleting the lockfile changes versions
  2. Spot it before it's committed
  3. Get the old lockfile back
  4. When npm ci fails
  5. Two agents, one lockfile conflict
  6. Stop it: a pre-commit check
  7. What the agent did when the hook blocked it
  8. Tell the agent up front
  9. Where Joxo fits
  10. Frequently asked questions
  11. Why did my package-lock.json change when I didn't add anything?
  12. What is the difference between npm install and npm ci?
  13. How do I fix a merge conflict in package-lock.json?
  14. Can I stop Claude Code from changing the lockfile?
  15. Try it with your team

You asked the agent to fix a failing build. It fixed it, and the diff also has 400 changed lines in package-lock.json. Nobody asked for a dependency change. Somewhere in the session the agent hit an install error and did what a lot of forum answers say: delete node_modules and the lockfile, then run npm install again.

That one move quietly upgrades every package to the newest version its range allows. Your tests passed on the old versions. The new ones might be fine, or might be the bug you chase next week. And if two agents do it on two branches, you also get a lockfile merge conflict.

Here is how to see what changed, get the old lockfile back, resolve lockfile conflicts without hand-editing, and stop it happening again. We ran every command with npm 11.20 and git 2.43, and the agent tests with Claude Code 2.1.318.

Why deleting the lockfile changes versions#

package.json holds ranges, like "ms": "^2.1.2", which means "2.1.2 or any newer 2.x". The lockfile pins the exact version everyone installs. Delete it, and npm install picks the newest match again.

We made a project that depended on ms@^2.1.2, locked at 2.1.2, then did what agents do:

bash
rm -rf node_modules package-lock.json
npm install
git diff --stat
 package-lock.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

One package, one bump (integrity lines left out):

bash
git diff package-lock.json
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",

In a real app with hundreds of packages, it's hundreds of bumps, mostly in packages you never named.

Spot it before it's committed#

The tell is simple: the lockfile changed, but package.json didn't. If nobody added, removed or changed a dependency, the lockfile shouldn't move.

bash
git status --short
 M package-lock.json

When an agent says it's done, look at git diff --stat before anything else. A lockfile in the list with no package.json next to it is worth a question.

Get the old lockfile back#

Restore the committed lockfile, then install exactly what it says:

bash
git restore package-lock.json
npm ci
added 1 package in 273ms

npm ci deletes node_modules and installs exactly what the lockfile lists. It never edits the lockfile. Afterwards git status is clean and ms is back on 2.1.2.

If the change was already committed, take the lockfile from the commit before:

bash
git restore --source=HEAD~1 package-lock.json
npm ci

When npm ci fails#

Sometimes the agent edited package.json by hand and never updated the lockfile. npm ci refuses to guess:

npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: picocolors@1.1.1 from lock file

That's useful. It names the package that is out of sync. Decide whether you want it. If yes, run npm install once to add just that package to the lock. If no, undo the package.json change.

Two agents, one lockfile conflict#

Agent A adds is-number on one branch, agent B adds kleur on another. Merging both:

Auto-merging package.json
CONFLICT (content): Merge conflict in package.json
Automatic merge failed; fix conflicts and then commit the result.

Both package.json and package-lock.json have conflicts. Don't hand-edit the lockfile. Fix package.json by keeping both lines:

json
  "dependencies": {
    "is-number": "^7.0.0",
    "kleur": "^4.1.5",
    "ms": "^2.1.2"
  }

Then let npm fix the lockfile. It understands git's conflict markers in package-lock.json and writes a merged one:

bash
npm install
grep -c '<<<<<<<' package-lock.json
0

Both packages are now in the lock. Commit, then check it installs cleanly from scratch:

bash
git add package.json package-lock.json
git commit -m "merge add-b"
npm ci
added 3 packages in 293ms

This is also why you don't want agents in a delete-and-reinstall habit: during a conflict, deleting the lockfile is the easy way out, and it bumps everything else along the way.

Stop it: a pre-commit check#

A git hook can refuse any commit where the lockfile changed and package.json didn't. Save as .git/hooks/pre-commit (or in a committed .githooks folder with git config core.hooksPath .githooks):

sh
#!/bin/sh
staged=$(git diff --cached --name-only)
if echo "$staged" | grep -qx 'package-lock.json' && ! echo "$staged" | grep -qx 'package.json'; then
  echo "package-lock.json changed but package.json didn't. Undo it: git restore --staged --worktree package-lock.json && npm ci" >&2
  exit 1
fi
bash
chmod +x .git/hooks/pre-commit

Then, after deleting and reinstalling:

bash
git commit -am "tidy"
package-lock.json changed but package.json didn't. Undo it: git restore --staged --worktree package-lock.json && npm ci

When you do want a lockfile-only change (a security update, say), make it on purpose with git commit --no-verify.

What the agent did when the hook blocked it#

We left the reinstalled lockfile in place and asked Claude Code to "commit all current changes". The hook stopped the commit, and Claude didn't push through:

I didn't follow the hook's advice, and nothing is committed. The commit was blocked because `package-lock.json` changed without `package.json`. The hook suggested `git restore --staged --worktree package-lock.json && npm ci`.

The lockfile is the only pending change, and it's the "refresh deps" work. Running that restore would delete it, so I left it staged. Do you want me to commit it anyway with `--no-verify`, or discard it as the hook suggests?

That's the right outcome. The lockfile change stopped being silent, and a person decides.

Tell the agent up front#

The hook catches it at commit time. A line in CLAUDE.md or AGENTS.md stops most of it earlier:

Install with npm ci. Never delete package-lock.json. Only run npm install <pkg> when the task is to add or upgrade a dependency, and say so in your summary.

Yarn and pnpm have the same "install exactly from the lock" mode; use it in the same line if your project uses one of them.

Where Joxo fits#

When several people's agents work on one project, each one picks up its own habits. Joxo keeps one set of team rules that every agent on the project reads, so "never delete the lockfile" is said once for all of them. Setup is one line pasted into your agent.

Frequently asked questions#

Why did my package-lock.json change when I didn't add anything?#

Usually someone ran npm install after deleting the lockfile, so npm picked the newest versions allowed by package.json. Restore it with git restore package-lock.json and run npm ci.

What is the difference between npm install and npm ci?#

npm ci installs exactly what the lockfile says and fails if it doesn't match package.json. npm install may update the lockfile.

How do I fix a merge conflict in package-lock.json?#

Resolve package.json by hand, then run npm install. npm reads the conflict markers in the lockfile and writes a merged one. Check with npm ci.

Can I stop Claude Code from changing the lockfile?#

Add a pre-commit hook that rejects lockfile changes without a package.json change, and a line in CLAUDE.md saying to install with npm ci.