What the agent does
The agent clones the repository into its own cloud sandbox and reads how each sample reloads code today before it writes a develop block. In a collection shaped like docker/awesome-compose, no compose.yaml has a develop: section yet. react-express-mysql/compose.yaml gets live reload the old way: the backend service bind-mounts ./backend/src:/code/src:ro, package.json and package-lock.json into /code, runs npm run start-watch (which backend/package.json defines as nodemon src/index.js --inspect=0.0.0.0:9229) and hides the container's node_modules behind a named volume called back-notused. The frontend service mounts ./frontend/src:/code/src and an anonymous /code/node_modules volume so react-scripts start picks up edits.
Those mounts are what Compose Watch replaces. For backend the agent adds develop.watch with one sync rule from ./backend/src to /code/src, so nodemon inside the container still sees every save, and one rebuild rule on ./backend/package.json and package-lock.json, because a dependency change has to re-run the npm ci layer in backend/Dockerfile rather than copy a lockfile over a container that already installed the old one. The frontend service gets a sync rule from ./frontend/src to /code/src with node_modules in its ignore list, and a rebuild rule on its package.json. The volumes that only existed to shadow node_modules go away along with the bind mounts; db-data and the db-password secret stay as they are.
nginx-golang is the other shape in the repository: a backend service built from backend/Dockerfile with target: builder, where the dev-envs stage ends in go run main.go and the compiled binary is copied into a scratch image. A synced file does nothing for a compiled Go server, so the agent writes a rebuild rule on ./backend for it, and a sync+restart rule for the proxy service's ./proxy/nginx.conf, which is mounted read-only today and only takes effect after nginx restarts. Each sample's README.md gets a short section showing docker compose watch next to the existing docker compose up -d instructions.
Then it proves the rules do what the file says. In the sandbox it runs docker compose watch for each changed sample, edits a file that a sync rule covers, confirms from the service log that nodemon or react-scripts restarted, touches a file under a rebuild rule and confirms Compose rebuilt the image. The last step is a docker compose config on every file it touched, so a YAML mistake is caught before a reviewer sees it, and a pull request with the diff and the watch logs.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Compose Watch to the Compose files in this repository that currently use bind mounts for live reload. For each such service, replace the source bind mounts with a develop.watch section: sync rules for source directories that the running process reloads on its own, sync+restart for config files, and rebuild rules for files that change the image such as package.json and lockfiles. Remove volumes that only existed to hide node_modules. Run docker compose config on every file you change, start each changed stack with docker compose watch, make one edit per rule and confirm from the logs that it synced, restarted or rebuilt. Update each sample's README with the watch command. Open a pull request that lists each service and the rules it got.",
"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 on its own branch. Its diff touches the compose.yaml of each sample that used bind mounts for reload, removes the volumes: entries that pointed at src directories or shadowed node_modules, and adds a develop: block under each affected service with watch: rules. The description lists every service with its rules in a table: the path, the container target, the action and, for sync rules, what the ignore list leaves out. The README changes sit beside them.
The run's record holds the proof. For each sample it keeps docker compose config output showing the merged file parsed cleanly, the docker compose watch session with the lines Compose prints when it syncs a file or rebuilds a service, and the log line from the service showing nodemon or react-scripts picked the change up. Nothing is pushed to a registry and no image tag changes.
Before merging, a reviewer checks three things: that no rebuild rule was turned into a sync rule for a compiled service, where a copied file changes nothing; that every path a sync rule covers is one the Dockerfile also copies, so a fresh build and a synced edit produce the same container; and that the secrets and database volumes the samples depend on were left alone.
Run it on every new Compose sample
In the console, an automation with a github trigger on pull_request.opened and pull_request.synchronize starts one run per pull request that adds or changes a compose.yaml, with the pull request as its context, in the Project that has the repository. The run reviews the new file for bind mounts used as reload and proposes the equivalent develop.watch rules as a review comment or as a commit on the pull request's branch, as the prompt says.
From your own server, the same work is one POST /o/{org}/sessions per repository, with the repository in resources. A webhook on the API key posts run.completed or run.failed when the turn finishes, with the session_url to read the pull request link and the watch logs.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Compose Watch rules are only right once you have seen them fire. The sandbox has Docker, so the agent runs docker compose watch, makes the edit, and reads the sync and rebuild lines Compose prints. On a laptop that means pulling every base image and starting every database in the repository; here it happens in a disposable machine whose log is kept with the run.
A repository with many samples is many small, independent changes. One run per sample, or one run that walks all of them, each produce a pull request a reviewer can read file by file, with the docker compose config output that shows each file still parses and the watch session that shows each rule did what its action says.
Frequently asked questions
Does the stack still work with plain docker compose up?
Yes. develop.watch only takes effect under docker compose watch or docker compose up --watch. A plain up ignores the section and runs the image as built, which is why the rules have to cover what the bind mounts used to provide and nothing else.
Why rebuild on package.json instead of syncing it?
The dependency install happens in an image layer, npm ci in backend/Dockerfile in the React, Express and MySQL sample. Copying a changed package.json into a running container leaves node_modules as it was. A rebuild rule rebuilds the image and recreates the container, so the new dependency is installed.
What about the volume that hid node_modules?
It existed because a bind mount of the whole source tree would have shadowed the container's installed node_modules with the host's. Once the bind mount is gone the volume has no job, so the agent removes it. If a sample mounts the entire project directory, the agent uses ignore on the sync rule instead of keeping the volume.
Which Compose version do I need?
Compose Watch is part of Docker Compose v2 and ships with current Docker Desktop and the docker-compose-plugin package. The agent runs docker compose version at the start of the run and notes the version it tested with in the pull request, so you can compare it with what your team runs.
Will it change samples that already reload correctly without mounts?
No. A service with no bind mount for source code, such as a database image or a static nginx proxy with nothing mounted, gets no develop section. The pull request only lists services whose reload path it changed.