What the agent does
The agent starts by writing down what the current setup enforces, which is often less than the dependency list suggests. In a TypeScript library like adobe/lit-mobx, package.json carries nine devDependencies for linting and formatting, yet .eslintrc.json does two things. It extends plugin:prettier/recommended, which reports formatting differences as lint errors, and it enables one rule, notice/notice, that requires each file to start with the Adobe copyright header from license.js. The lint script is eslint -f pretty 'src/**/*.ts', and .eslintignore skips declaration files, lib, node_modules and every .js file. Formatting lives in .prettierrc.yaml: eight keys, including four-space indentation, single quotes and trailingComma: es5.
It checks where those tools run. In this repository neither CI system lints: the CircleCI config runs npm i and npm run test, and the GitHub workflows publish. Lint and format run only in a husky pre-commit hook defined in package.json, as pretty-quick --staged && npm run lint. So the migration has to replace a hook, not a CI job, and the agent says that adding a CI check would be new behaviour for you to accept.
Then it runs the two migrate commands and reads their output instead of trusting it. biome migrate eslint --write succeeds and prints the rules it has no equivalent for, with notice/notice and prettier/prettier among them; the generated biome.json turns the linter on with no rule preset and translates the ignore file into includes patterns. biome migrate prettier --write fails with Biome couldn't find a Prettier configuration file, because the config is YAML. The agent ports the eight keys by hand into formatter and javascript.formatter: line width 80, indent width 4 with spaces, single quotes, trailingCommas: es5, semicolons always, arrow parentheses always.
Next it measures the formatting difference before anything is rewritten. biome format over src, demo and test reports two files it would change. One is demo/public-property-example.ts, where an expression inside an html template literal is broken across lines differently. The other is demo/tsconfig.json, which has Windows line endings. The agent applies those in a separate commit, so the tooling change and the reformat can be reviewed apart. Last, it replaces the header rule with a short script that checks the first lines of each source file against the same pattern, and wires it and biome check into the lint script and the hook.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this repository from ESLint and Prettier to Biome. Before changing anything, report what the current setup enforces: read the ESLint config, its ignore file, the Prettier config and ignore file, the lint and format scripts, git hooks and every CI workflow, and say which rules are on, which files are covered, and where lint and format run today. Run the existing lint and format checks and record that they pass. Install @biomejs/biome pinned to an exact version. Run biome migrate eslint --write and biome migrate prettier --write, quote their output, and list every rule or option they could not carry over. If the Prettier migration cannot read the config format, port each option by hand and show the mapping. For each ESLint rule with no Biome equivalent, either keep the check another way (a small script run by the lint command) or say it is dropped and why; do not silently lose a check. Do not enable Biome's recommended rules as part of this change: run them once and report what they would flag as a separate list. Run biome format without writing and list the files it would change; apply the reformat in its own commit, separate from the tooling commit. Replace the lint and format scripts and the git hook with Biome equivalents that cover the same files. Remove the ESLint and Prettier packages and config files that nothing uses any more. Run the build and tests. Open a pull request that lists removed packages, dropped or replaced rules, and reformatted files.",
"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 with a tooling commit and a formatting commit. The tooling commit adds biome.json and the header-check script, rewrites the lint script and the pre-commit hook, deletes .eslintrc.json, .eslintignore and .prettierrc.yaml, and removes the packages nothing imports any more: eslint, the two @typescript-eslint packages, three ESLint plugins and configs, the formatter, prettier and pretty-quick. The formatting commit touches the two files Biome formats differently and nothing else.
The description is organised around what could have been lost. It lists each rule the ESLint migration reported as unsupported and what happened to it: prettier/prettier is replaced by Biome's formatter, and notice/notice by the script. It shows the mapping from the eight Prettier keys to Biome options. And it gives the count of diagnostics Biome's recommended rules would raise if enabled, as information for a follow-up, since turning on a new rule set is a separate decision from changing tools.
A reviewer checks coverage first. The old lint command looked at src/**/*.ts only and ignored .js files, and the new one should match that unless the description says it was widened on purpose. They then read the formatting commit, which in this repository is small enough to read in full, and confirm the header check fails on a file with the header removed.
Run it on every repository in your organisation
A tooling migration is usually decided once and then repeated across every package a team owns. Start one run per repository from your own machine, each with this request and that repository's URL in resources. From an MCP client connected to Rush's MCP server, create_session returns at once with the session, and wait_for_sessions then waits up to 50 seconds per call for one or several of them to settle, so a single terminal session can hand off a dozen repositories and collect the results.
Runs started with an API key beyond that key's max_concurrent limit, 4 unless you changed it, are accepted as queued and begin as earlier ones finish. Each repository has a different ESLint config, so read the first two or three pull requests before starting the rest. When the same unsupported plugin keeps appearing, add a sentence about it to the prompt and the remaining runs handle it the same way.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The migrate commands make this look like a two-line job, and in a repository with a JSON Prettier config and stock rules it nearly is. The failures are quiet ones: a config format the tool does not read, a plugin rule with no counterpart, a formatter that agrees with the old one everywhere except template literals. Finding them means running the old tools, the new tools and the test suite against the real repository, and the run does that in its own sandbox with every command and its output kept in the transcript.
It also separates decisions from mechanics. Which rules to enforce after the move is yours to decide; installing packages, mapping options and counting differences is not worth an afternoon. Handing the mechanics off from a terminal and getting back a pull request that states exactly what was dropped lets the people who own the code spend their time on the one or two real choices.
Frequently asked questions
Does Biome format code exactly like Prettier?
Close, not identical. In adobe/lit-mobx, with the options ported, Biome changes one of the ten TypeScript files, in how it breaks an expression inside a tagged template literal. The agent lists every file that would change before rewriting any, and puts the reformat in its own commit.
What happens to ESLint plugin rules Biome does not have?
The migrate command prints them, and the agent treats each as a decision to record. A check that matters, such as a licence header rule, is kept as a small script that the lint command runs. One that only existed to connect ESLint to Prettier is dropped, since Biome's own formatter covers it. Nothing is removed without a line in the pull request saying so.
My Prettier config is YAML. Is that a problem?
For the automatic step, yes: Biome 2.6 answers biome migrate prettier with a message that it cannot find a configuration file when the only one is .prettierrc.yaml. The options still map one to one, so the agent ports them by hand and shows the mapping in the description.
Will it turn on Biome's recommended lint rules?
Not as part of the migration. Enabling a new rule set changes what the build rejects, which deserves its own review. The agent runs the recommended rules once, reports how many diagnostics they would raise and in which files, and leaves the switch to a follow-up.