What the agent does
The agent reads how the server is wired before it changes the adapter. In a chat server like socketio/chat-example, index.js is one file: the primary process calls availableParallelism() from node:os, forks one worker per core with cluster.fork({ PORT: 3000 + i }) and calls setupPrimary() from @socket.io/cluster-adapter; each worker opens chat.db with sqlite and sqlite3, creates a messages table with a client_offset TEXT UNIQUE column, and builds new Server(server, { connectionStateRecovery: {}, adapter: createAdapter() }). The chat message handler inserts the message, treats SQLite error 19 as a duplicate and acknowledges it, then calls io.emit('chat message', msg, result.lastID). A reconnecting client that was not recovered replays rows above socket.handshake.auth.serverOffset. package.json has socket.io at ^4.7.2, express at ^4.18.2, @socket.io/cluster-adapter at ^0.2.2, type: module, a single start script and no test script; package-lock.json pins socket.io 4.7.2, and .codesandbox/Dockerfile is FROM node:20.
The cluster adapter relays packets through the primary process over IPC, so it only ever reaches workers on the same machine. The agent replaces it with @socket.io/redis-adapter and the redis client: it creates pubClient from createClient({ url: process.env.REDIS_URL }), derives subClient with pubClient.duplicate(), awaits Promise.all([pubClient.connect(), subClient.connect()]) before the server starts listening, and passes adapter: createAdapter(pubClient, subClient) to new Server. setupPrimary() and the @socket.io/cluster-adapter import go; the cluster fork loop can stay, since each worker now owns its own pair of Redis connections, and the agent asks in the description whether you would rather run one process per container and let the platform scale. REDIS_URL is read from the environment and documented in the README next to npm start.
Two things in this file do not become multi-host on their own, and the agent says so instead of hiding them. The chat.db SQLite file is per machine, so the message history a reconnecting client replays depends on which host it lands on; the pull request names that and offers a follow-up that moves messages to Postgres or to Redis itself. And the browser client in index.html connects with the default transports, so with more than one host the load balancer needs sticky sessions, or the client needs transports: ['websocket']; the agent adds the one-line client option behind a comment and leaves the choice to you.
To prove the change it installs redis-server with apt-get in its sandbox, starts it, runs two copies of the server on different ports with the same REDIS_URL, connects a socket.io-client to each, emits chat message on one and asserts the other receives it with the same serverOffset. The same script is committed as test/broadcast.test.js under a new test script using node:test, so the check runs again on every change. npm start still works with the cluster forks, and the agent includes the commands it ran and their output in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace the Socket.IO cluster adapter in this repository with the Redis adapter so that broadcasts reach every process on every host. Read index.js, index.html and package.json first. Use @socket.io/redis-adapter with the redis client: a pub client from REDIS_URL, a duplicated sub client, both connected before the server listens. Remove the cluster adapter and setupPrimary, keep the per-core forking unless it no longer makes sense, and document REDIS_URL in the README. Point out anything that is still per-host after this change, such as a local SQLite file or the lack of sticky sessions, and propose the next step rather than silently changing it. Install a Redis server in the sandbox, run two server processes against it and prove a message emitted on one arrives on the other; commit that check as a test. Include the commands and output in the pull request description. Open a pull request.",
"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 index.js (the Redis pub and sub clients, createAdapter(pubClient, subClient), no setupPrimary), package.json and package-lock.json (@socket.io/redis-adapter and redis added, @socket.io/cluster-adapter removed, a test script), the README (REDIS_URL), a commented client transport option in index.html, and a new test/broadcast.test.js that starts two servers and checks a cross-process broadcast.
The description quotes the output of the two-server check and lists what stays single-host: the SQLite history file and the transport upgrade without sticky sessions, each with the proposed follow-up. Every command the agent ran, with its output, is in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer confirms REDIS_URL is set in each deployment environment, decides whether the cluster forking stays, and picks between sticky sessions and websocket-only transport for the load balancer. A follow-up message to the same session can move the message table out of SQLite.
Run it on every Socket.IO service you scale past one host
A team with several realtime services starts one run per repository with one POST /o/{org}/sessions each, the repository in resources and this prompt as input. Each run reads its own server file and adapter setup, so a service that already uses a message store gets a shorter pull request and one that still writes to a local file gets the same warning this page describes.
Send a request_id, a UUID v5 of the repository's full name, so a retried call returns the run it already started instead of a second one. The key's webhook_url reports when each run the key starts finishes, with the run's final answer in result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The adapter swap is a few lines; knowing it works needs a Redis server and at least two server processes talking through it, which is exactly what a laptop session skips. The agent installs Redis in its own sandbox, runs the two processes and keeps the output, so the pull request carries the cross-process proof rather than a promise.
Several services can be converted at once, each in its own sandbox with its own pull request, and each description names what is still per-host for that service. A reviewer reads the test and the warnings instead of reconstructing the behaviour of io.emit under a load balancer.
Frequently asked questions
Does the Redis adapter replace the cluster module?
No. The cluster module forks processes; the adapter decides how those processes share broadcasts. The cluster adapter only works between workers of one primary on one machine, while the Redis adapter works across any number of processes and hosts that reach the same Redis. The agent keeps the forking by default and asks whether you want to drop it.
Will connection state recovery still work?
connectionStateRecovery keeps working with the Redis adapter for the packets the adapter saw. The example's own replay of rows above serverOffset reads the local SQLite file, which is why the agent flags that file as per-host rather than claiming recovery is complete across machines.
Why does the agent mention sticky sessions?
The browser client connects with the default transports, which start with HTTP long-polling and upgrade to WebSocket. With several hosts behind a load balancer, polling requests from one client must reach the same host, or the session breaks. The adapter does not change that; sticky sessions or transports: ['websocket'] on the client do.
What if we already run Redis Streams?
Say so in the prompt. @socket.io/redis-streams-adapter uses a single client and streams instead of pub/sub, and the agent wires that one instead; the two-process check is the same.