What the agent does
ESLint 9 made flat config the default and stopped reading .eslintrc.* files. The first eslint . after the upgrade prints its apology line, the version, and ESLint couldn't find an eslint.config.* file. From ESLint v9.0.0, the default configuration file is now eslint.config.*. If you are using a .eslintrc.* file, please follow the migration guide, then exits 2 without linting a line. The current release, 10.14.0, prints the same text, and the ESLINT_USE_FLAT_CONFIG=false escape hatch that ESLint 9 still honoured no longer brings the old format back. The set of files to lint changes hands too: under flat config each entry names its own files patterns, so an --ext .ts,.vue,.tsx list in the lint script, which the current release still accepts as additional extensions, belongs in the config rather than on the command line.
nandi95/vue-toastify, a Vue 3 toast library built with Vite and TypeScript, has a typical pre-9 setup. package.json lists eslint ^8.24.0 with @typescript-eslint/eslint-plugin and @typescript-eslint/parser at ^8.5.0, eslint-plugin-vue ^9.5.1, @vue/eslint-config-typescript ^13.0.0, @stylistic/eslint-plugin-ts ^2.8.0 and eslint-plugin-import ^2.22.1, and its lint script is eslint . --fix --ext .ts,.vue,.tsx. .eslintrc.cjs is 165 lines: root: true, a node env, five extends entries including plugin:@typescript-eslint/recommended-requiring-type-checking and plugin:vue/vue3-recommended, the vue and @stylistic/ts plugins, ignorePatterns for node_modules and *.js, parserOptions with parser: '@typescript-eslint/parser', project: './tsconfig.json', tsconfigRootDir: __dirname and extraFileExtensions: ['.vue'], and around sixty rules, among them a multi-entry @typescript-eslint/naming-convention and a block of vue/ rules. The package is "type": "module", which is why the config is a .cjs file. The only workflow, publish.yml, runs npm ci and build:lib and never lints, so nothing in CI noticed the upgrade.
The agent reproduces the failure by installing the current ESLint in a clean copy and running the repository's own lint script, keeping the exit code and the message. Then it writes eslint.config.js by hand rather than through a compatibility shim where it can: the extends entries become the plugins' own flat exports, typescript-eslint's recommendedTypeChecked, eslint-plugin-vue's flat/recommended and @vue/eslint-config-typescript's vueTsConfigs among them, the parser block becomes a languageOptions entry with parserOptions.project and extraFileExtensions, ignorePatterns becomes a global ignores entry, and the --ext list becomes files: ['**/*.ts', '**/*.vue', '**/*.tsx']. The rules object is copied with one rename: @stylistic/eslint-plugin-ts is deprecated in favour of @stylistic/eslint-plugin, so its @stylistic/ts/ rule keys become @stylistic/ keys with the same options. Where a preset has no flat export, the agent wraps that one entry with FlatCompat from @eslint/eslintrc and says so in the pull request, so the shim covers one line rather than the whole file.
The proof is a comparison, not a green run. The agent runs the old configuration on ESLint 8 and the new one on the current release across the same files, both without --fix, and diffs the two reports: the same rule ids on the same lines. A rule that fires on one side only is a translation mistake or a plugin that changed its default, and each one is listed with its cause. It then updates the lint script, moves the eslint, typescript-eslint and plugin pins to the versions it tested, deletes .eslintrc.cjs, and adds a lint step to the publish workflow so the next upgrade cannot pass unnoticed.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Our lint script fails after an ESLint upgrade with ESLint couldn't find an eslint.config.* file. Read package.json, the lint script, every .eslintrc file and any .eslintignore, and report the ESLint version, each plugin and shared config with its version, the parser settings and the number of rules. Reproduce the failure by running the repository's own lint script on the installed release and keep its output. Then write eslint.config.js (or .mjs or .cjs as the package type requires) that keeps every setting: translate each extends entry to the plugin's own flat export where one exists, the parser and parserOptions to languageOptions, ignorePatterns and .eslintignore to a global ignores entry, and the --ext list to files patterns; copy the rules unchanged. Use FlatCompat from @eslint/eslintrc only for a preset with no flat export, and name each such entry in the pull request. Raise the eslint, typescript-eslint and plugin versions to releases that support flat config and the installed ESLint major. Then prove the translation: run the old configuration on the old ESLint and the new one on the new release over the same files, both without --fix, and diff the reports by rule id and line; list every difference with its cause and fix the translation until the only differences are ones a plugin's new defaults explain. Update the lint script, delete the old config files, and add a lint step to CI if none runs. Do not change source files to satisfy rules and do not run --fix. Open a pull request that lists the versions before and after, the FlatCompat entries if any, the report diff, and anything you could not verify.",
"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 adds eslint.config.js, deletes the old .eslintrc file, changes the lint script and the dependency pins in package.json and the lockfile, and adds a lint job to the workflow. Its description opens with the failing run of the old script on the new release, then a table of the old config's parts, extends, plugins, parser, ignores, rules, each with the flat-config entry it became and whether it needed FlatCompat.
Below that is the comparison that makes the change reviewable: the old and new reports over the same files, matched by rule id and line, with the differences and their causes. A reviewer reads that table rather than the new config, because a flat config that runs without error can still have silently dropped a parser option and with it every type-aware rule. The source files are untouched, so the diff is config and dependencies only.
What the run cannot prove is listed last. Editor integrations read the new file on their own schedule, so a developer whose editor still shows old-config errors restarts the ESLint server, and a rule a plugin changed its default for is left at the new default with a note, not reverted.
Run it on every dependency update pull request
An ESLint major arrives as a dependency update pull request, and in a repository whose CI never lints it merges green and breaks the next developer's editor. Create an automation on the repository's Project with the prompt above and a github trigger on pull_request.opened and pull_request.synchronize, with a prompt that tells the agent to stop with a one-line answer when the pull request does not touch package.json. The pull request's title and description follow the prompt as event text, so the agent sees which package moved, and it opens its own pull request with the translated config instead of pushing to that branch. A pull request a bot opens fires no github trigger, so for Dependabot or Renovate bumps give the same automation a schedule trigger with a weekly cron and a prompt that tells the agent to check the open dependency pull requests.
For a monorepo or an organisation with many packages on the same .eslintrc, send the request above once per repository with an API key and read each result from its session, or let the key's webhook report every run.completed.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
Translating a config is the easy half; knowing it still enforces the same rules is the half nobody does, because it means running two ESLint versions over the same tree and comparing reports by hand. The agent does exactly that in a sandbox, with the old and new releases installed side by side, and keeps both reports and the diff in the session, so the pull request shows which rules moved rather than claiming none did.
The sandbox also keeps the migration honest about shims. FlatCompat can wrap a whole legacy file and make the error disappear, at the cost of carrying the old format forever. The agent is asked to translate by hand and to use the shim for a single entry only when a preset has no flat export, naming it in the description, so the reviewer sees exactly how much of the old format survives.
Frequently asked questions
Can I set ESLINT_USE_FLAT_CONFIG=false and keep my .eslintrc?
On ESLint 9 that still read the old file. On the current release, 10.14.0 in the run, the variable no longer helps and the command fails the same way, so the translation is due. Pinning ESLint 8 buys time at the cost of plugin releases that have moved on.
Where does --ext go?
Into the config. Each flat-config entry names the files it applies to with files patterns, so --ext .ts,.vue,.tsx becomes files: ['**/*.ts', '**/*.vue', '**/*.tsx'] and the lint script is just eslint .. The flag still exists on the current release as a way to add extensions, but the agent lets the config own the file set so editors and CI agree.
Do my plugins support flat config?
The ones in the example do: typescript-eslint and eslint-plugin-vue publish flat exports, and @vue/eslint-config-typescript 14 exports vueTsConfigs. One package is replaced rather than translated: @stylistic/eslint-plugin-ts is deprecated in favour of @stylistic/eslint-plugin, which the agent installs, renaming the @stylistic/ts/ rule keys. FlatCompat is used only for a preset with none of these, and listed in the pull request.
How do I know the new config enforces the same rules?
From the report diff in the pull request. The agent lints the same files with the old config on ESLint 8 and the new config on the new release, without --fix, and matches the findings by rule id and line. Any difference is listed with its cause.
Will the agent fix lint errors while it is there?
No. The request forbids --fix and source changes, because a fix would hide a rule that fires differently after the translation. Cleaning up findings is a separate request once the config is merged.