What the agent does
The agent reads how the first window appears before it puts one in front of it. In an app shaped like electron-react-boilerplate/electron-react-boilerplate, package.json pins electron ^44.4.0, electron-vite ^5, electron-builder ^26 and jest 30 with jsdom, and its scripts run electron-vite dev --watch for start, electron-vite build, electron-builder build --publish never for package, jest and node .erb/scripts/smoke-test.cjs. src/main/main.ts creates the BrowserWindow with show: false, 1024 by 728, the preload from ../preload/preload.js, shows it on ready-to-show unless START_MINIMIZED is set, builds the menu, sends external links to the browser, and loads resolveHtmlPath('index.html'), which src/main/util.ts resolves to ELECTRON_RENDERER_URL in development and a file: URL under ../renderer when packaged. app.whenReady() awaits createWindow() and then startAutoUpdates(), and reportWindowError destroys the window on failure. electron.vite.config.ts gives the renderer one Rollup input, src/renderer/index.html, and names its output renderer.js. src/renderer/index.html sets a Content-Security-Policy of script-src 'self' 'unsafe-inline'. assets/ holds icon.png and icon.svg, and extraResources copies ./assets/** into the package. .github/workflows/test.yml runs npm run package, npm run lint, tsc --noEmit, npm test and the smoke test on macOS, Windows and Linux.
The splash is a second, smaller window with no preload and no script. src/renderer/splash.html is a static page with the icon and the product name, styled inline, and electron.vite.config.ts lists it as a second Rollup input beside index.html, with entryFileNames changed to a per-entry name so the two bundles do not collide; in development the Vite server serves it at the same ELECTRON_RENDERER_URL. src/main/splash.ts exports createSplashWindow(): a BrowserWindow of 360 by 240, frame: false, resizable: false, alwaysOnTop: true, centred, with sandbox: true in its webPreferences, that loads resolveHtmlPath('splash.html'). createWindow in main.ts opens the splash first, then the main window as before; the ready-to-show handler closes the splash before it shows or minimises the main window, and reportWindowError closes it too, so a failed main window never leaves a splash on screen. No minimum display time is added: the splash lives exactly as long as the main window takes, and the pull request notes where a floor would go.
src/__tests__/updates.test.ts shows the project's main-process test style: jest.mock('electron', ...) with a small object, jest.resetModules() in beforeEach and a plain require of the module under test. The agent adds src/__tests__/splash.test.ts the same way, with a fake BrowserWindow class that records its options and its loadURL argument: one test asserts the options above and that the URL ends in splash.html, another emits ready-to-show on the fake main window and asserts the splash was closed before show was called. .erb/scripts/smoke-test.cjs starts npm start with a remote debugging port and looks the window up through /json/list, so the agent reads its target predicate and checks that a second page target does not change which one it picks. Then it runs npm run lint, npm exec tsc -- --noEmit, npm test, npm run package and xvfb-run --auto-servernum npm run test:smoke, the Linux steps of the workflow, and pastes the 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": "Add a splash screen to this Electron app and open a pull request. Read package.json, electron.vite.config.ts, src/main/main.ts, src/main/util.ts, src/main/preload.ts, src/renderer/index.html, src/__tests__/updates.test.ts, jest.config.js, .erb/scripts/smoke-test.cjs and .github/workflows/test.yml first. Add src/renderer/splash.html as a static page with the icon and product name and no script, and register it as a second renderer input in electron.vite.config.ts with per-entry output names. Add src/main/splash.ts exporting createSplashWindow(): a 360 by 240 frameless, non-resizable, always-on-top, centred BrowserWindow with sandbox enabled and no preload, loading resolveHtmlPath('splash.html'). In createWindow open the splash before the main window, close it in the ready-to-show handler before show or minimize, and close it in reportWindowError. Add src/__tests__/splash.test.ts in the style of updates.test.ts covering the window options, the loaded URL and the close on ready-to-show. Check the smoke test still finds the main window. Run npm run lint, npm exec tsc -- --noEmit, npm test, npm run package and the smoke test under xvfb-run, and paste the output in the pull request. Do not change the preload, the menu or the updater.",
"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 adds src/renderer/splash.html, src/main/splash.ts and src/__tests__/splash.test.ts, edits src/main/main.ts and electron.vite.config.ts, and leaves the preload, the menu and updates.ts alone. The description describes the window, lists its options and pastes the jest, tsc, lint, package and smoke-test output.
On a repository with the Test workflow, the pull request packages the app and runs the smoke test on macOS, Windows and Linux, so a splash that kept the main window from being found would fail on all three.
A reviewer checks that the splash closes on every path, ready-to-show, START_MINIMIZED and reportWindowError, that alwaysOnTop is acceptable on macOS where another app may be full screen, that the second renderer entry lands in release/app/dist/renderer, and that the splash page carries the same content security policy as index.html. Then they decide whether a minimum display time is wanted.
Run it on every Electron app with a slow first window
A team with several Electron apps sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own main.ts and bundler config, so an app on Webpack gets a second entry there and an app that already shows its window at once gets the splash wired to did-finish-load instead, and each run opens its own pull request.
Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request and the test output from.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A splash is only right when it closes on every path the main window can take, including the one where the window fails, and that is a main-process behaviour a browser test cannot see. In a Rush sandbox the agent runs the jest tests against a fake BrowserWindow, packages the app and starts the real binary under xvfb-run the way CI does, keeping the output in the run's record.
The change adds one static page, one module and one test and reuses resolveHtmlPath and the existing build, so there is no new dependency. The same request works on any electron-vite app with a single main window.
Frequently asked questions
Why does the splash have no preload and no script?
It has nothing to do but be visible. With sandbox: true, no preload and a static page, it cannot reach Node or IPC, and the content security policy from index.html holds without an unsafe-inline script. The main process decides when it closes.
What if the main window never becomes ready?
createWindow rejects, reportWindowError logs the error through electron-log, destroys the main window and closes the splash, and app.quit() runs as it does today. There is no timeout in this change; the pull request notes where one would go if the team wants it.
Does the splash show in development too?
Yes. resolveHtmlPath points at the Vite dev server when ELECTRON_RENDERER_URL is set and at the built file otherwise, and the second Rollup input makes splash.html available in both, so npm start and the packaged app behave the same.
Will the smoke test keep passing?
The smoke test lists page targets over the remote debugging port and picks the main window's. The agent reads that predicate and runs the smoke test under xvfb-run before it pushes, so a second target that changed the pick would show in the run.