What the agent does
The agent clones the repository into its own cloud sandbox and reads how linting is wired today before it touches a config file. In a library like tqdm/tqdm, .pre-commit-config.yaml runs flake8 7.3.0 with -j8 and six plugins (flake8-broken-line, flake8-bugbear, flake8-comprehensions, flake8-debugger, flake8-isort, flake8-pyproject), then pyupgrade with --py38-plus, then isort 9.0.1, beside hooks that must stay: the pre-commit-hooks set, nbstripout, and local hooks that regenerate README.rst, tqdm/completion.sh and run a quick pytest. pyproject.toml holds [tool.flake8] with max_line_length = 99 and an exclude list, [tool.isort] with line_length = 99, multi_line_output = 4 and known_first_party = ["tqdm", "tests"], and a [tool.yapf] block the agent leaves alone because formatting is not the job. The Makefile has a flake8 target that runs pre-commit run -a flake8 and nbstripout, and the pre-commit.ci block sets autoupdate_schedule: monthly.
It writes a [tool.ruff] section with line-length = 99, target-version = "py38" to match requires-python = ">=3.8", and the flake8 exclude list as extend-exclude. Under [tool.ruff.lint] it selects the rule families that stand in for each plugin: E, F and W for pycodestyle and pyflakes, B for bugbear, C4 for comprehensions, T10 for debugger, I for isort and UP for pyupgrade. flake8-broken-line has no Ruff equivalent, so its single rule is named in the pull request as dropped rather than silently lost. [tool.ruff.lint.isort] gets known-first-party = ["tqdm", "tests"]; isort's multi_line_output = 4 has no exact counterpart, so the agent runs ruff check --select I --diff first and shows which import blocks would be rewrapped before deciding whether to accept that diff or keep the old wrapping with a per-file ignore.
Then it runs ruff check . and reads every finding against what flake8 accepted. Rules in the new families that flake8 never ran, such as UP modernisations beyond what pyupgrade --py38-plus already applied, are either fixed with ruff check --fix when the fix is safe or added to ignore with a comment saying why. The handful of # noqa comments in tqdm/std.py, tqdm/utils.py, tqdm/asyncio.py and tqdm/notebook.py carry codes like F401, BLE001 and B042; the agent checks each against Ruff's rule list, keeps the ones Ruff knows and removes codes it does not, so RUF100 stays clean if a maintainer enables it later.
Finally it replaces the flake8, isort and pyupgrade entries in .pre-commit-config.yaml with the ruff-pre-commit hook running ruff with --fix, keeps every other hook in place, renames the Makefile target, deletes [tool.flake8] and [tool.isort] from pyproject.toml, and runs pre-commit run -a and pytest -k "not slow" in the sandbox so the quick-test hook that pre-commit already defines still passes with coverage above its --cov-fail-under=70 floor.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace flake8, isort and pyupgrade with Ruff in this Python project. Read .pre-commit-config.yaml, pyproject.toml and the Makefile first and list every flake8 plugin and setting in use. Add a [tool.ruff] configuration that keeps the same line length, target Python version and excludes, select the Ruff rule families that cover each plugin, and name any plugin that has no Ruff equivalent in the pull request instead of dropping it quietly. Carry over the isort first-party setting. Run ruff check and fix or explicitly ignore each new finding, keeping existing noqa comments only where Ruff knows the code. Swap the pre-commit hooks for ruff-pre-commit, keep every other hook, update the Makefile lint target, remove the old flake8 and isort config, then run pre-commit on all files and the quick test suite before opening a pull request with the rule mapping in its description.",
"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
What comes back is a pull request that changes pyproject.toml, .pre-commit-config.yaml and the Makefile, plus whichever source files ruff check --fix touched, mostly import ordering and a few noqa codes. Its description is a table: each flake8 plugin on the left, the Ruff rule family that replaces it on the right, and a row for any plugin left behind, so a maintainer sees in one glance that nothing enforced before is quietly unenforced now.
The run's record keeps the ruff check output before and after the fixes, the --diff preview of import rewrapping, and the full pre-commit run -a and pytest output, so a reviewer does not need to reproduce the migration locally to trust it.
Before merging, a reviewer checks the dropped-rule row, decides whether the import wrapping diff is acceptable or should be pinned back, and confirms that pre-commit.ci will keep autoupdating the new hook on its monthly schedule as it did the old ones.
Run it on every Python repository in your org
A migration like this is a one-time change per repository, so the natural loop is over repositories, not over time. A script on your side reads GET /o/{org}/github for the repositories the Rush GitHub App reaches, filters the ones with a .pre-commit-config.yaml that mentions flake8, and sends one POST /o/{org}/sessions per repository with this body and that repository in resources. A request_id that is a UUID v5 of the repository name makes the script safe to rerun: a second request for the same repository returns the run already started instead of opening a second pull request.
Set a webhook URL on the API key and each run reports run.completed with its session_url when its pull request is up, so one dashboard shows which repositories are migrated, which are waiting on review, and which runs ended with a problem to look at.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The hard part of a linter migration is not writing the config, it is proving parity: that every rule the old setup enforced is still enforced, and that the new rules did not sneak in behaviour changes under the name of a fix. That needs the old and new linters run on the same tree, their outputs compared, and the tests run after the automatic fixes. The agent does all three in a sandbox that has the repository's own Python version and pre-commit cache, and the record shows exactly which command produced which finding.
Running it on Rush rather than a laptop also means the same migration can run across every Python repository at once, each in its own sandbox, each ending in its own pull request with its own mapping table, instead of one engineer repeating the exercise repository by repository over a quarter.
Frequently asked questions
Does this change code formatting too?
No. The job replaces the linters, not the formatter. In a project like tqdm the [tool.yapf] block stays untouched and ruff format is not introduced. The only source changes are the ones ruff check --fix makes for the selected rules, mostly import order, and each one is visible in the diff.
What happens to flake8 plugins Ruff does not implement?
They are named in the pull request as dropped, with the rule they enforced. flake8-broken-line, for example, has no Ruff counterpart. The agent never pretends a rule carried over, so the decision to live without it or to keep flake8 for that one plugin is yours.
Will Ruff flag things flake8 never did?
Often, because a rule family like UP or B in Ruff may cover more codes than the plugin version you ran. The agent handles each new finding one of two ways: a safe automatic fix, or an entry in ignore with a one-line reason. Nothing is left as a failing lint in the pull request.
Does pre-commit.ci keep working?
Yes. The ci: block in .pre-commit-config.yaml is left as it is, and ruff-pre-commit is a normal hook repository with tagged releases, so the monthly autoupdate bumps it the same way it bumped flake8 and isort.
Which Python version does Ruff target?
The one requires-python already declares. For tqdm that is py38, which keeps UP from suggesting syntax the oldest supported interpreter cannot run and matches the --py38-plus flag the pyupgrade hook used.