What the agent does
Flat config replaces a cascade of files with one array, so the agent first maps the cascade. In a package like forwardemail/supertest there are two files. .eslintrc at the root extends airbnb-base/legacy, sets the node and mocha environments and ecmaVersion: 6, and overrides seven rules, each with a comment giving the reason. test/.eslintrc relaxes three rules for the tests: it turns off no-unused-expressions for the assertion style, and loosens no-unused-vars and no-param-reassign. The lint script in package.json is eslint lib/**/*.js test/**/*.js index.js, and pretest runs it, so a lint error blocks npm test. Before touching anything the agent saves the resolved rules for one library file and one test file with eslint --print-config. That snapshot is what the migration is checked against.
It picks the target version from the facts. When this page was written ESLint 10 required Node ^20.19.0 || ^22.13.0 || >=24, and eslint-plugin-import, which the Airbnb config depends on, accepted ESLint up to 9. The workflow in .github/workflows/ci.yml still tests Node 18. ESLint 9 is the newest release that every job in that matrix can run, so that is the target. eslint-config-airbnb-base 15 declares a peer range that ends at ESLint 8, and npm installs ESLint 9 beside it with an ERESOLVE overriding peer dependency warning. Then the agent runs npx @eslint/migrate-config .eslintrc. The tool writes eslint.config.mjs, wraps the Airbnb config in FlatCompat, maps the two environments to globals, sets sourceType: "commonjs", and asks for three more packages.
The first lint on the generated file reports 46 problems where there were none, 43 errors and 3 warnings, and the agent sorts them by cause before fixing any. Forty errors come from one omission: the tool converts the file it is given and nothing else, so the three overrides in test/.eslintrc are gone. Adding a block with files: ["test/**/*.js"] removes them. Three errors are ESLint 9 itself: no-unused-vars now checks caught errors by default, and the linted files have an unused binding in three catch clauses, such as catch (_). The agent proves the cause by running ESLint 9 on the old config format, which reports the same lines, and restores the old behaviour with caughtErrors: "none". The three warnings are eslint-disable comments that suppress nothing, which ESLint 9 reports by default.
The last finding is about what was never checked. The lint script's globs are unquoted, so the shell expands lib/**/*.js before ESLint sees it, and without globstar that matches only lib/cookies/. lib/agent.js and lib/test.js have never been linted. Checked directly under the old setup, lib/test.js has three errors; under the new one the two files also hold three more unused catch bindings and two more stale directives. The agent keeps the script's file set as it is, so the migration stays a migration, and reports the gap with both counts. It ends by comparing --print-config again: 252 rules before and after, with the same severity on each.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this repository's ESLint setup from eslintrc files to flat config. First find every ESLint config: files named .eslintrc with any or no extension in every directory, an eslintConfig key in package.json, .eslintignore files, and inline eslint-env comments. Read package.json, the lockfile entries for eslint and each config and plugin, and .github/workflows. Run the lint script as it is and record the result. Save eslint --print-config for one source file and one test file. Choose the target ESLint major: read engines.node for the newest releases and the peer ranges of every shared config and plugin in use, compare them with every Node version in the workflow matrix, and pick the newest major that all of them allow; explain the choice. Run the official migration tool on the root config, then check what it left out: nested config files, ignore files and comments that explained rule choices. Bring nested configs over as blocks with a files pattern and keep the explanatory comments. Run lint and sort every new report by cause: a rule the migration dropped, a default that changed in the new major, or a file that was not being linted before. Prove a changed default by running the new ESLint against the old config format. Restore previous behaviour through configuration; do not edit source files to satisfy the linter and do not disable a rule that was on. If the lint script's file patterns skip files, do not change which files are linted; report the skipped files and what linting them would show. Compare --print-config before and after and list any rule whose severity differs. Delete the old config files. Open a pull request with the counts by cause and the open questions.",
"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.mjs, deletes both .eslintrc files, and changes package.json and the lockfile: ESLint 9 and the three packages the flat file imports. The config has two blocks, one for the whole package and one for test/, with the original comments about why each rule is overridden carried across. No file under lib/ or test/ is edited.
The description accounts for every report the first run produced. For a package like the one above: 40 from the dropped test overrides, 3 from the caught-error default and 3 unused directives, each with what was done. The lint script ends with no errors. The remaining warnings are the unused eslint-disable comments, which eslint --fix would delete; the agent leaves that one-line cleanup as a suggestion because it edits source. A reviewer checks the config comparison: the same 252 rules at the same severities for a library file and for a test file.
Two things are raised, not changed. The files the script's globs skip, with the errors they contain, since quoting the patterns would make npm test fail until those are fixed. And the Airbnb config, which has no flat export and runs through the compatibility layer with a peer range the new ESLint is outside of; replacing it is a style decision for the maintainers.
Run it on every repository still on .eslintrc
The trigger is a person deciding the old config format has to go, usually because a dependency update is blocked on it. A developer sends this body to POST /o/{org}/sessions from a terminal or an MCP client, with a request_id that is a UUID made once for the job. The pull request is on the session when the run completes, and a question the agent ends on is answered with a follow-up to POST /o/{org}/sessions/{id}/messages, which wakes the same sandbox.
For a group of packages that share a config, a script sends the body once per repository, each with a request_id that is a UUID v5 of the repository's full name, so running the script twice starts nothing new. The key queues what it cannot run at once, and its webhook_url receives run.completed for each run it started. Comparing the counts by cause across repositories shows which problems belong to the shared config and which to one package.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The work here is bookkeeping: a snapshot before, a tool run, a diff of several dozen reports, an experiment to prove which ones the new major introduced, and a snapshot after. Each step is a command whose output has to be kept and compared, and that is tedious enough to be skipped by hand. In the run's sandbox the agent installs two ESLint majors side by side, runs both, and every command with its output is in the transcript at GET /o/{org}/sessions/{id}/messages.
The result is checkable in a way a hand migration rarely is. The usual hand version ends with a commit that turns off whichever rules started failing. This one comes back with the rule set shown to be unchanged, each new report traced to a cause, and the problems the old setup was hiding written down for someone to decide on.
Frequently asked questions
Does the migration tool handle a config in a subdirectory?
No. @eslint/migrate-config converts the one file it is given. A second .eslintrc in a folder such as test/ has to become a block with a files pattern in the new config, and until it does, every rule it relaxed is back in force. The agent searches for nested configs before running the tool.
Why do I get new no-unused-vars errors on catch blocks?
ESLint 9 changed that rule's caughtErrors default from none to all, so an unused binding in catch (err) is reported. It is a change in ESLint 9, not in flat config. Setting caughtErrors: "none" restores the old behaviour; removing the unused bindings is the other fix, and it edits source.
Can I use eslint-config-airbnb-base with flat config?
Through FlatCompat from @eslint/eslintrc, yes, and that is what the migration tool generates. Version 15 of the config declares a peer range that ends at ESLint 8, so npm warns when it sits beside ESLint 9. In forwardemail/supertest the rules resolve the same way before and after.