What Is a Lockfile and Why AI Agents Change It
A lockfile records the exact version of every package your app uses. Here is what that means, why AI agents keep touching it, and how to review the change.
A lockfile is a file that records the exact version of every package your app depends on, including the packages those packages depend on, so that every install produces the same result. In a JavaScript project it is usually package-lock.json, yarn.lock or pnpm-lock.yaml. AI coding agents change it constantly, as a side effect of installing or updating packages, and a surprising lockfile diff is one of the first signs that an agent did more than you asked.
What a lockfile does
Your package.json says what you want in general terms: "any version of this library from 4.2 up to, but not including, 5.0". A lockfile says what you actually got: version 4.2.7, with this exact set of sub-packages beneath it. The next person to install, or your hosting platform, uses the lockfile and gets the same tree. Without it, two installs a week apart can pull different versions and behave differently.
Other ecosystems have the same idea under other names: poetry.lock for Python's Poetry, Gemfile.lock for Ruby, Cargo.lock for Rust, composer.lock for PHP. The npm documentation describes package-lock.json and what it records in detail.
Why AI agents change it
Most of the time, for a boring reason. Commands that agents run to make code work, such as npm install some-package, update the lockfile as a side effect. A few other triggers:
The agent adds a dependency to solve a problem. Fine if you wanted it, a problem if you did not, which is why some teams stop agents adding dependencies without asking.
The agent runs a general update, which can move many packages at once. See whether an agent should upgrade your dependencies.
The agent deletes the lockfile and reinstalls to fix a confusing error. This regenerates the whole tree and can shift dozens of versions at once.
Different tool versions on the agent's machine and yours format or resolve the file differently.
Reading the diff: expected, suspicious, wrong
A lockfile diff can be thousands of lines, so do not read it line by line. Start with the summary:
git diff --stat -- package.json package-lock.json
git diff package.jsonThe package.json diff is short and tells you what the agent intended. The lockfile should then change only in ways that follow from it.
Category | What you see | What to do |
|---|---|---|
Expected | One new package in | Accept, if you wanted the package |
Suspicious | Lockfile changes but | Ask why. Likely a regenerated tree or a tool version difference |
Wrong | Dozens of unrelated packages change version, or an existing package is swapped for a different one | Revert the lockfile and redo the change with a narrower command |
To revert only the lockfile and keep your code changes:
git checkout -- package-lock.jsonInstall from the lockfile, not around it
In npm projects, npm install can update the lockfile, while npm ci installs exactly what the lockfile says and stops with an error if it does not match package.json. The npm documentation for npm ci describes it as intended for automated environments such as test platforms and deployment pipelines. That makes it a good choice for builds, and a good instruction to give an agent that only needs to run the existing code.
Rules worth writing down
If you use an AI coding agent regularly, put rules in the file it reads at the start of a session, so it does not guess:
Do not delete or regenerate the lockfile to fix an error. Report the error instead.
Do not change dependencies unless the task says so, and list any new package with a reason.
Commit lockfile changes together with the
package.jsonchange that caused them.
How to write those instructions is covered in writing an AGENTS.md file that agents follow, and the broader question of what an agent should leave alone is in files your AI coding agent should never write.
Why this matters for security
A package added or bumped without anyone noticing is a way for bad code to enter a project. Models also sometimes suggest package names that do not exist, which an attacker can register, as described in when AI hallucinates a package that does not exist. Reviewing the lockfile diff is a cheap defense. Treat a new package from an unknown publisher the way you would treat any other unfamiliar code you are about to run.
For a wider look at working safely with these tools, our guide to AI coding tools is a good place to continue.
FAQ
Should I commit my lockfile to git?
For applications, yes. It is what makes installs repeatable across your machine, your teammates and your host. Libraries that other projects install have different conventions, so check the guidance for your ecosystem.
Why is my lockfile so big?
It lists every package, including packages that your packages need, with versions and checksums. Large trees are normal.
Can I just delete the lockfile and regenerate it?
You can, but doing so can change many versions at once. Do it deliberately, run the tests, and review the diff, instead of as a quick fix to an error.
What is the difference between package.json and package-lock.json?
The first states which versions are acceptable. The second records which versions were installed.
How did this land?
About the author
Senior Editor, AI & Product
Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.
