What the agent does
The agent reads where the upload has to land before it writes any of it. In an app like laravel/livewire-starter-kit, the profile page is a Livewire 4 single-file component at resources/views/pages/settings/profile.blade.php with two public properties, name and email, and one action, updateProfileInformation, whose rules come from the ProfileValidationRules trait. The users migration has no column for a photo. The User model names its fillable columns in a #[Fillable] attribute and has an initials() helper, and two templates draw the user from those initials: components/desktop-user-menu.blade.php and layouts/app/sidebar.blade.php.
Storage is the decision most uploads get wrong, so the agent reads config/filesystems.php and .env.example too. The default disk is local, rooted at storage/app/private. The public disk is rooted at storage/app/public and is reachable from the web only through the symlink that php artisan storage:link creates. A profile photo is shown to other people, so the agent stores it on public under avatars/, names the disk explicitly so a changed default does not move the files, and writes the storage:link step into the pull request for whoever deploys.
The change itself is small and spread over five places. A migration adds a nullable avatar_path to users. The component gains the WithFileUploads trait, a photo property validated as an image with a size limit, a preview from the temporary upload, and a save path that stores the new file, deletes the old one and writes the column directly, so avatar_path stays out of the fillable list and a request cannot set it to an arbitrary path. The account-deletion component removes the file with the user. The two templates pass the photo's URL to the Flux avatar and keep the initials as the fallback.
Then it proves it. The tests in tests/Feature/Settings/ProfileUpdateTest.php are PHPUnit classes using Livewire::test('pages::settings.profile'), so the agent adds cases there with Storage::fake('public') and UploadedFile::fake()->image(...): a valid photo is stored and the column set, a PDF and an oversized image are refused with an error on photo, a second upload deletes the first file, and deleting the account deletes the file. Generating a fake image needs PHP's GD extension, so the agent installs it alongside PHP 8.3, then runs composer test, which is Pint, PHPStan and the suite.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a profile photo upload to this Laravel Livewire app and open a pull request. Read composer.json, config/filesystems.php, .env.example, app/Models/User.php, app/Concerns/ProfileValidationRules.php, database/migrations, database/factories/UserFactory.php, resources/views/pages/settings/profile.blade.php, resources/views/pages/settings/delete-user-modal.blade.php, every template that renders the user's initials, tests/Feature/Settings/ProfileUpdateTest.php and .github/workflows/tests.yml first. Make sure PHP 8.3 with the GD and SQLite extensions, Composer and Node 22 are installed, run composer setup and run composer test once before changing anything. Add a migration for a nullable avatar_path column on users. In the profile component use Livewire's WithFileUploads trait with a photo property; put its rules next to the others in ProfileValidationRules: an image of type jpg, png or webp, at most 2 MB. Show a preview of the temporary upload and a remove button. On save, store the file on the public disk under avatars with a generated name, delete the previous file, and set avatar_path directly on the model; do not add it to the Fillable attribute. Delete the file when the account is deleted. Add an avatarUrl helper on User that returns the public URL or null, and pass it to the Flux avatar and profile components wherever initials are rendered, keeping initials as the fallback. Do not publish config/livewire.php or change the default filesystem disk. Add tests to ProfileUpdateTest with Storage::fake and UploadedFile::fake for: a valid upload, a wrong type, an oversized file, replacing a photo, removing a photo and account deletion. Run composer test until it passes. In the pull request, list each file changed and why, include the test output, and say what a deploy needs: the migration and php artisan storage:link.",
"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 touches a migration, the User model, the validation trait, the profile and delete-account components, the two templates that render initials and one test file. The description lists each with a sentence on why, then the output of composer test with the new cases in it. A short deploy note follows: run the migration, and run php artisan storage:link once on each server so files on the public disk have a URL.
It also states the limits it chose and where they live. The 2 MB cap and the allowed types are in ProfileValidationRules beside the name and email rules. Livewire applies its own, larger limit to the temporary upload before your rule runs; that one is set in config/livewire.php, which this app has not published, and the agent leaves it at the default and says so. If your app serves uploads from S3, the same code works once the disk name changes, and the note says which line.
A reviewer checks that avatar_path is absent from the fillable list, that the stored name is generated and not the client's file name, that the old file is deleted on replace and on account deletion, and that the tests assert on the fake disk and not only on the absence of errors. Opening the profile page on a preview deploy is still worth a minute, since the Flux avatar's look is the one thing the PHP tests cannot see.
Run it on every feature you would rather not sit through
This is a task to hand over from the editor you are already in. Connect Rush as an MCP server once, with claude mcp add --transport http rush https://api.phoenix.so/mcp and your API key in an Authorization header, or the equivalent entry in Cursor. Then ask your local agent to start it: the create_session tool sends this page's body and returns at once, and wait_for_sessions checks on it for up to 50 seconds per call while you keep working on something else. Nothing runs on your machine, so your local database and storage folder are untouched.
When the turn ends the sandbox parks with its disk and memory and costs nothing while parked. If the review asks for a crop step or a different size limit, send_session_message wakes the same sandbox with the branch and installed dependencies as they were, and the agent pushes another commit to the same pull request. The same body works from a script: send it to POST /o/{org}/sessions with a request_id that is a new UUID per run, so a retried request does not start a second one.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
An upload is one of those features that is done in twenty minutes and correct in two hours. The first version stores the file. The correct one also picks the right disk, refuses a renamed executable, keeps the path out of mass assignment, deletes what it replaces, cleans up with the account and has a test for each of those. Each is a short step that is easy to postpone when the happy path already works on your screen. The agent does all of them in one pass because the request lists them, and it runs the repository's full check script in a clean sandbox where a missing GD extension or an unlinked storage folder shows up instead of being masked by your local setup.
Handing it off also keeps your working tree free. The run has its own clone, its own in-memory test database and its own fake disk, so it does not compete with the branch you have checked out. The transcript keeps every command and its output, and the session lists the files it changed with their diff, so the pull request arrives with evidence you can read before you open the code.
Frequently asked questions
Does it work with S3 or another cloud disk?
Yes. The component stores through Laravel's Storage facade on a named disk, so pointing it at an s3 disk is a one-word change plus credentials in the environment. Tell the agent which disk in the prompt and it uses that name and skips the storage:link note. The tests are unchanged because they fake the disk by name.
Where do the temporary files go while the user is choosing a photo?
Livewire's WithFileUploads trait uploads the file to a temporary folder on the default disk as soon as it is selected, and the component moves it to its final place on save. The agent does not change that mechanism. If your default disk is remote, say so, because the temporary folder then needs its own lifecycle rule.
Can it add uploads to a component that is not the profile page?
Yes. Name the component and the model in the prompt. The steps are the same: read the component and its tests, add a column or a related table, validate, store on an explicit disk, delete on replace, and test with a fake disk. For several files per record the agent uses an array property and a related table instead of one column.
Why keep the path out of the fillable attribute?
The profile action saves with $user->fill($validated). Anything that is both validated and fillable can be set by the form, so a fillable avatar_path with a loose rule would let a request point the photo at any path on the disk. Setting the column directly after the file is stored removes that possibility.
More Livewire jobs
The same job on other stacks
- Add File Uploads to a React Router App (React Router)
- Add File Uploads to a Reflex Chat App (Reflex)
- Add File Uploads to a Vapor API (Vapor)
- Add File Uploads to an AdonisJS App (AdonisJS)