What the agent does
The agent begins with what the hooks do today, which is not always what the files say. In a repository like hagopj13/node-express-boilerplate, package.json pins husky at exactly 7.0.4 and has "prepare": "husky install". The .husky directory holds three hooks: pre-commit runs yarn lint-staged, post-checkout runs yarn install and post-commit runs git status. Each starts with #!/bin/sh and the line that sources _/husky.sh. .lintstagedrc.json runs eslint on staged *.js files. git ls-files -s .husky shows all three hook files committed with mode 100644, so they are not executable.
That mode matters more than the version number. Husky 7 points core.hooksPath at .husky, and Git on Linux refuses to run a hook file without the executable bit. A commit in a fresh clone prints The '.husky/pre-commit' hook was ignored because it's not set as executable and goes through with no lint. Husky 9 points core.hooksPath at .husky/_, where it writes its own executable wrapper for every hook name, and each wrapper runs your file with sh -e. The bit stops mattering. So in this repository the upgrade does not just rename a command: it turns on three hooks that were silently off for anyone who cloned on Linux. After it, a staged file with an unused variable is stopped by lint-staged with ESLint's no-unused-vars error, and every branch switch runs yarn install.
The mechanical part follows the messages husky 9 prints. With version 9.1.7, the release current when this page was written, husky install still exits 0 but prints husky - install command is DEPRECATED, so prepare becomes husky. Hook files that keep the two header lines print a husky - DEPRECATED block on every commit and checkout, ending They WILL FAIL in v10.0.0. The agent deletes those lines from all three files and confirms the block is gone.
Then it checks the installs that have no Git directory or no dev dependencies, where upgrades of this package usually break. The Dockerfile copies package.json and yarn.lock and runs yarn install --pure-lockfile, and .dockerignore leaves .git out; there husky 9 prints .git can't be found and exits 0. With dev dependencies omitted the two package managers differ. Yarn 1.22.22 with --production does not run prepare and exits 0. npm 10.9.9 with --omit=dev runs it and fails with sh: 1: husky: not found, code 127. bin/createNodejsApp.js in this repository supports both, so the agent writes "prepare": "husky || true" and shows the npm install passing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade husky in this repository from the pinned 7.x release to the latest 9.x. Read package.json, yarn.lock, every file in .husky, .lintstagedrc.json, the Dockerfile, .dockerignore and bin/createNodejsApp.js first. Before changing anything, report the file modes of the hook files from git ls-files -s, make a commit in this clone and report whether each hook actually ran. Then upgrade husky, replace the deprecated install command in the prepare script, remove the deprecated header lines from each hook file, and run husky. Make a commit with a clean staged file, a commit with a staged lint error, and a branch switch, and record what each hook printed. Test the installs where husky is missing or there is no .git directory: copy package.json and the lockfile to an empty directory and run the Dockerfile's install command, a Yarn production install and an npm install with dev dependencies omitted, and make prepare safe for all three. Say in the pull request which hooks will start running for contributors who did not have them running before, and what husky 9 requires of Node. Do not change what the hooks do. Open a pull request with the output of every command.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes package.json, yarn.lock and the three files in .husky, each now a single command. The description has a before and after for one commit: under 7.0.4, Git's ignored because it's not set as executable hint and a commit that went through; under 9, the lint-staged task list and a second attempt blocked by an ESLint error. It includes the three install transcripts and states which package manager ran prepare in each.
What the reviewer weighs is behaviour, since the code change is small. Contributors will have yarn lint-staged run on every commit, possibly for the first time, and yarn install on every checkout, which is slow on a large tree and can be dropped in a follow-up. yarn lint on the unchanged repository already reports seven prettier/prettier errors in src/middlewares/auth.js, so the first person to stage that file will be blocked until it is formatted. Husky 9 declares node >=18 while engines.node here says >=12.0.0 and .travis.yml builds on Node 12; the description lists both and leaves the CI change to its own pull request unless asked.
Run it on every Monday morning
Dev-tool upgrades like this one fit a weekly pass. Add an automation on the Project with a schedule trigger, a cron of 0 7 * * 1 and your timezone, and a saved prompt that tells the agent to check the Git hook tooling and the packages around it (husky, lint-staged, the ESLint plugins) for a new major version, upgrade one per pull request, and prove each the way this page does: a real commit, a blocked commit, and the three installs.
The schedule's slot is added after the prompt as the event, and the saved prompt is the only instruction, so write the package list and the proof you expect into it. The automation's max runs per hour applies to it. A week with nothing to upgrade ends with an answer that says so and no pull request.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A hook upgrade is verified by making commits, and that needs a Git repository in a known state with nobody's personal configuration in the way. On a laptop, a global core.hooksPath, an old ~/.huskyrc or hooks that were made executable by hand long ago can each hide what a fresh clone does. The agent works in a sandbox that starts from a clean clone, so what it sees is what a new contributor or a CI machine sees, and here that included hooks that never ran.
The run also keeps every command and its output. The claim that npm fails with code 127 and Yarn does not, or that the deprecation block disappears once two lines are removed, comes with the transcript that shows it. A reviewer who doubts a line in the description can open the run and read the command that produced it.
Frequently asked questions
Why does husky install print a deprecation warning?
Version 9 replaced husky install with plain husky. The old command still works and exits 0, but prints husky - install command is DEPRECATED. Changing the prepare script to husky removes the message.
Do I have to make the hook files executable?
Not with husky 9. Git runs husky's own wrappers in .husky/_, and each wrapper runs your hook file with sh -e, so the file's mode is not consulted. With husky 7 the files themselves were the hooks, and Git skipped any that lacked the executable bit.
How do I stop the prepare script failing in production installs?
Use "prepare": "husky || true". An npm install that omits dev dependencies still runs prepare, finds no husky binary and fails with code 127 unless the script tolerates it. Setting HUSKY=0 is the other switch: husky then prints HUSKY=0 skip install and does nothing, which suits CI where the package is installed but hooks are unwanted.
Will my existing hook commands keep working?
Yes. The commands stay as they are; only the shebang and the line that sources _/husky.sh are removed. Husky 9 adds node_modules/.bin to PATH before it runs a hook, so a command like yarn lint-staged resolves as before.
More Husky jobs
More jobs like this: Upgrade dependencies weekly
- Upgrade a Quarkus App to Java 25 (Quarkus)
- Upgrade a Spring Boot App to Java 25 (Spring Boot)
- Upgrade Jest 29 to Jest 30 (Jest)
- Upgrade Knex 0.20 to Knex 3 in an Express API (Knex.js)
- Upgrade Retired Lambda Runtimes in an AWS CDK App (AWS CDK)