What the agent does
The agent reads what the project already has. In a Filament application laid out like filamentphp/demo, composer.json requires filament/filament 5 on Laravel 12 and PHP 8.1 or later, and lists rector/rector 2.1 under require-dev beside Larastan, Pint and Pest. rector.php at the root configures it: withImportNames(), withPaths() over app, config, database, routes and tests, and the three rule sets withTypeCoverageLevel, withDeadCodeLevel and withCodeQualityLevel all at level 0. The scripts block defines cs and pint for formatting, test:pest as pest --parallel, test:phpstan as phpstan analyse, and a test alias that runs both. Rector has no script and no job: the tool is installed and configured, and nothing runs it.
CI is four workflows under .github/workflows/. tests.yml and phpstan.yml run on every push and pull request on PHP 8.4 with a Composer cache keyed on composer.lock, copy .env.example, generate an app key and call the matching composer script; tests.yml also starts a Postgres 16 service, builds assets with Node 20, and runs the schema reset test against pgsql. format.yml runs only on pushes to the 5.x branch, calls composer cs and commits the result with a maintainer token. zizmor.yml lints the workflows themselves, and every action is pinned to a commit SHA with its version in a comment, which the Dependabot configuration for github-actions keeps current weekly.
The agent adds a test:rector script, rector process --dry-run, folds it into the test alias after test:phpstan, and writes rector.yml in the shape of phpstan.yml: the same triggers, the same concurrency group, the same pinned actions/checkout, actions/cache and shivammathur/setup-php steps with coverage: none, composer install --no-interaction --prefer-dist, then composer test:rector. Rector needs the Composer autoloader and nothing else, so the job copies no .env and generates no key, and it runs in parallel with PHPStan and Pest rather than inside them. The --dry-run flag makes Rector exit non-zero whenever a rule would change a file, and print the diff, which is what a CI check needs.
Before opening the pull request the agent runs the dry run itself in its sandbox with PHP 8.4 and the locked dependencies. At level 0 of each set the report is short by design, so the agent also runs it with each level raised by one, writes the diffs those levels would make to the pull request description, and leaves rector.php as it is: which level the team wants is their decision, and the job exists so that decision is enforced from then on. If the current code fails at level 0, the agent applies that output with rector process, runs composer cs so Pint reformats what Rector touched, and runs composer test:pest and composer test:phpstan against the result.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a Rector dry-run check to CI for this Filament application. Read composer.json, rector.php, phpstan.neon, pint.json and every workflow under .github/workflows first. Add a test:rector composer script that runs rector process --dry-run and include it in the test alias. Write .github/workflows/rector.yml in the same shape as phpstan.yml: same triggers, concurrency group, pinned actions with version comments, PHP 8.4, Composer cache, and composer test:rector; it needs no .env and no app key. Run the dry run in the sandbox; if it reports changes at the configured levels, apply them with rector process, run composer cs, then composer test:pest and composer test:phpstan. Do not change the levels in rector.php; run the dry run once more with each level raised by one and put those diffs in the pull request description for the maintainers to choose from. Run actionlint and zizmor over the new workflow, then open a pull request that describes every file Rector changed and why.",
"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 adds .github/workflows/rector.yml, adds the test:rector script to composer.json and extends the test alias, and changes PHP files under app, config, database, routes or tests only where the configured levels demanded it. Its description shows the dry-run output at the configured levels, the Pint, Pest and PHPStan results after any change, and, in a separate section, the diffs each next level up would produce so the maintainers can raise a level with a one-line edit to rector.php.
The new job appears as a check on the pull request itself, beside phpstan and tests, which proves the workflow runs green on the branch that introduces it. Because format.yml only reacts to pushes on the default branch, a Rector change that Pint would restyle is already formatted in the branch, so the auto-commit workflow has nothing to do after the merge.
Before merging, a reviewer reads the Rector diff for a rewrite that changes behaviour rather than form, confirms that the Pest suite of 61 files still passes with the parallel runner, and decides which of the proposed levels to turn on first.
Run it on every pull request
A team with several Laravel and Filament applications sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own rector.php and workflows: a project that already has a rector.php with higher levels gets the job at those levels, and one without Rector installed gets it added to require-dev with a starting configuration and the same job.
Once the job runs, an automation on the Project with a github trigger on workflow_run.failure and the prompt "if the rector job failed on this branch, read its diff and comment on the pull request with the files it wants to change and a one-line reason per file; push nothing" starts one run per failed workflow. The trigger adds the event after the prompt, and the runs only read the repository and comment, so a failing Rector check is explained in the pull request within minutes.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Turning on a refactoring tool in CI is easy to write and hard to judge: the first dry run on a 180-file application reports changes nobody has read, and the question is which of them the team wants enforced. The agent runs the tool at the configured levels and the next ones in a sandbox with the exact locked dependencies, applies only what the configuration already demands, and puts the rest in front of the maintainers as diffs rather than opinions.
The dry-run output, the Pint run and the Pest and PHPStan results all stay with the run, so a reviewer sees what the workflow will enforce before it does. A team with many applications runs the same request across all of them at once, each in its own sandbox, and gets one pull request per repository with that repository's own report.
Frequently asked questions
Will Rector change my code in CI?
No. The job runs rector process --dry-run, which prints the diff it would make and exits non-zero, and never writes to the checkout. Applying changes stays a local or agent-run step that goes through a pull request like any other change.
Does the job need the database or an app key like the test workflow?
No. Rector reads PHP files through the Composer autoloader and the paths in rector.php, so the job installs dependencies and runs; it copies no .env, generates no key and starts no Postgres service, which is why it finishes well before the Pest job does.
Why keep the levels at zero instead of raising them?
Each level enables more rules, and a jump across many of them rewrites files throughout the application in one pull request nobody can review. The agent shows what each next level would change and leaves the choice in rector.php to the maintainers; once chosen, the job holds the line.
Will Rector and Pint fight over formatting?
Rector rewrites code but does not follow pint.json, so the agent runs composer cs after any rector process and commits both together. In CI the two checks are independent: the Rector job only compares against its rules, and the format workflow only runs on the default branch.