What the agent does
The agent reads the dependency graph before it bumps anything, because a plugin built from obsidianmd/obsidian-sample-plugin has only devDependencies and one of them constrains the rest. package.json lists ten: esbuild pinned exactly to 0.25.5, obsidian declared as latest, and caret ranges for typescript, eslint, @eslint/js, typescript-eslint, eslint-plugin-obsidianmd, globals, jiti and @types/node; package-lock.json at lockfile version 3 resolves obsidian to 1.12.3, typescript to 5.9.3, eslint to 9.39.4, typescript-eslint to 8.59.2 and esbuild to 0.25.5. There is no runtime dependency because esbuild.config.mjs marks obsidian, electron, every @codemirror and @lezer package and Node's built-ins as external and bundles src/main.ts into main.js in CommonJS for es2021. The build script runs tsc -noEmit -skipLibCheck and then esbuild in production mode, lint runs eslint . with eslint.config.mts, which jiti lets ESLint load, and AGENTS.md says npm and esbuild are required for this layout. .github/workflows/lint.yml runs npm ci, npm run build and npm run lint on Node 20, 22 and 24; release.yml builds on Node 24 on a pushed tag and attests main.js.
npm outdated is the start, and the registry's peer ranges decide the end. eslint-plugin-obsidianmd 0.4.2, the current release, declares peers of eslint >= 9.19.0, @eslint/js ^9.30.1, typescript-eslint ^8.35.1 and an exact obsidian version, so @eslint/js stays on its 9 line even though a 10 exists, and the agent keeps eslint on the 9 line beside it rather than mix a 10 core with a 9 config package. typescript-eslint 8.72.1 declares typescript >= 4.8.4 < 6.1.0, which rules out the TypeScript 7 the registry's latest tag now points at, so typescript stays on 5.9. esbuild can move from 0.25.5 to 0.28.2, and the agent reads the three minor release notes on the way: 0.26.0 changed nothing but how the package is published, 0.27.0 made the binary loader use Uint8Array.fromBase64 for targets that support it and raised the Go toolchain's minimum Linux kernel, and 0.28.0 made the install script verify binary hashes on its fallback path; none touches a CommonJS bundle targeting es2021 with no binary imports. obsidian moves to 1.14.4, and globals, @types/node, typescript-eslint and the lint plugin to their newest versions inside their ranges.
The agent edits package.json so the ranges say what was chosen, keeping esbuild an exact pin as the template does and replacing obsidian: latest with the resolved version, since latest in a manifest means a fresh clone can silently differ from the lock, then runs npm install to rewrite package-lock.json and npm ls, and explains the one peer mismatch it expects: the lint plugin pins obsidian to an exact older version, so the lock already disagrees with it today and the bump does not change that. It runs npm run build and npm run lint on Node 20, 22 and 24 with a version manager in its sandbox, the same three the workflow uses, and diffs the new main.js against the one built before the upgrade to show esbuild's output changed only in its banner and the minified body. src/main.ts and src/settings.ts, 114 and 38 lines, compile against the newer obsidian typings without an edit, which the tsc run proves.
The pull request groups the bumps the way a reviewer reads them: a table of package, old version, new version and the reason for any version held back, with the two held back on purpose, typescript and @eslint/js, explained by the peer range that holds them and the release that would lift it. manifest.json and versions.json are not touched, because minAppVersion describes the app the plugin runs in and a typings bump alone does not change which API it calls; the agent checks the diff of obsidian.d.ts between 1.12.3 and 1.14.4 for anything the two source files use and says what it found.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade this Obsidian plugin's npm dependencies. Read package.json, package-lock.json, esbuild.config.mjs, tsconfig.json, eslint.config.mts, manifest.json, versions.json, AGENTS.md and every workflow under .github/workflows first. Run npm outdated, then read the peerDependencies of eslint-plugin-obsidianmd and typescript-eslint on the registry and keep every package inside the ranges they declare, explaining each one you hold back. Read the release notes of every esbuild minor between the pinned version and the newest for breaking changes that affect a CommonJS bundle with externals. Replace the latest range on obsidian with the resolved version and keep esbuild pinned exactly. Update the lock file with npm install, show npm ls and explain every peer warning it prints, run npm run build and npm run lint on each Node version the lint workflow uses, diff the built main.js before and after, and check whether the new obsidian typings change anything the source files call. Leave manifest.json and versions.json unchanged unless the API used requires it. Open a pull request with a table of every bump, the reason for each hold, and the commands with their output.",
"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
The pull request changes package.json and package-lock.json. Its description holds the bump table with a reason per held-back package, the npm ls output with its peer warnings explained, npm run build and npm run lint output on Node 20, 22 and 24, the main.js diff summary, the lines of the esbuild release notes it judged relevant, and the result of the typings comparison. No source file, manifest or workflow changes.
A reviewer checks the two holds, whether the team wants to move ESLint to 10 by waiting for the lint plugin, and whether to keep obsidian as an exact version from now on. After merging, the lint workflow repeats the same three builds on the pull request's commit, and the next tag builds a release from the upgraded toolchain.
Run it on every Monday morning
An automation in the Project that holds the plugin takes a schedule trigger with cron set to Monday at 09:00 in the team's time zone and this prompt. Its runs are read-only, so each one reads npm outdated and the registry's peer ranges and writes the bump table and the holds as its answer, which the key's session read shows and which pushes nothing. When the table shows something worth taking, a handler on the team's own server starts the run that writes the pull request, sending this body with a request_id that is a UUID v5 of the week's date, so a second trigger in the same week returns the run already started.
A team that maintains several plugins runs one automation per repository's Project, each with its own cap on runs per hour.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A plugin's dependency set is small and tangled: one lint plugin pins the config package and the typings it was written against, the linter pins the TypeScript it can parse, and a bundler pinned exactly has three minor releases of notes between it and the newest. Reading the ranges and the notes, rather than running an upgrade tool and seeing what breaks, is the work, and the proof is the build and lint on each Node the workflow uses, run in the agent's own sandbox with every command and its output kept in the run's record.
It also keeps the template's conventions where they are deliberate, an exact esbuild pin and an untouched manifest, and fixes the one that is not, the latest range that let a clone and the lock disagree. Ten plugins with ten lock files get ten pull requests, each with that plugin's own table of bumps and holds.
Frequently asked questions
Why is TypeScript held back?
Because typescript-eslint declares a peer range of >= 4.8.4 < 6.1.0, so the 7 release the registry now marks latest would make npm ls warn and eslint . run against a parser that has not been tested with it. The pull request names the range and the package that owns it, so the hold is lifted the week that range changes.
Why not ESLint 10?
eslint-plugin-obsidianmd allows an ESLint core of 9.19 or newer but pins @eslint/js to the 9 line, and @eslint/js 10 requires an ESLint 10 core. Mixing a 10 core with a 9 config package is possible but untested by the plugin, so the agent keeps both on 9 and lists the plugin release to watch.
Does a new obsidian typings version change minAppVersion?
Not by itself. minAppVersion says which Obsidian the plugin runs in, and the plugin calls the same API after the bump as before, which the agent checks by diffing the typings for the names main.ts and settings.ts use. It changes only when the source starts calling an API added in a newer app.
Why replace latest with a version?
npm install on a fresh clone resolves latest to whatever the registry has that day, while npm ci uses the lock, so the two commands could install different typings. A version with a caret keeps the lock and the manifest in agreement and lets the weekly run move it on purpose.
Will the release workflow still attest the build?
Yes. release.yml runs npm ci and npm run build on Node 24 and attests main.js, and the agent ran that same build on Node 24. The workflow file does not change, and the upgraded lock is what it installs.
More Obsidian plugin jobs
The same job on other stacks
- Upgrade the npm Dependencies of a Pulumi Program (Pulumi)
- Upgrade npm Dependencies in a React Router App (React Router)
- Upgrade npm Dependencies in a SolidJS App (SolidJS)