What the agent does
The agent clones the repository into its own cloud sandbox and reads how the processes are wired before it writes a query. In electron-react-boilerplate/electron-react-boilerplate, src/main/main.ts creates the window with a preload at ../preload/preload.js, registers one ipcMain.on('ipc-example') handler and starts the auto updater, src/main/preload.ts exposes electron.ipcRenderer with sendMessage, on and once over a Channels type that allows only ipc-example, and src/renderer/App.tsx renders a Hello route inside a MemoryRouter. package.json pins Electron ^44.4.0, electron-vite ^5, Vite 7, React 19, Jest 30 with jsdom and TypeScript 7, and its postinstall runs electron-builder install-app-deps; release/app/package.json has an empty dependencies, which the README says is where native modules belong, and electron.vite.config.ts marks everything listed there as external for the main and preload bundles.
That decides the storage choice. Electron 44 bundles Node 24, which ships the node:sqlite module, so the agent checks process.versions.node from the installed Electron and uses DatabaseSync from node:sqlite in the main process: no native module to rebuild for Electron's ABI, nothing to add to release/app/package.json, and the same module loads under the Node 24 that devEngines requires for Jest. It adds src/main/db.ts, which opens app.db under app.getPath('userData'), turns on WAL, and applies schema migrations keyed on the user_version pragma, with the first migration creating a notes table; src/main/notes.ts registers ipcMain.handle for notes:list, notes:add and notes:delete with prepared statements.
The preload grows an invoke wrapper and Channels widens to the three note channels, so the renderer calls window.electron.ipcRenderer.invoke('notes:add', text) with types that follow from src/renderer/preload.d.ts. A small Notes component on the home route lists and adds notes through those calls. The database opens in app.whenReady() before createWindow, and closes on will-quit, with log from electron-log recording the path and any migration it ran.
Tests follow the pattern in src/__tests__/updates.test.ts, which already runs with /** @jest-environment node */ and jest.mock('electron'): a db.test.ts mocks app.getPath to a temporary directory, opens the database, runs the migrations twice to show they are idempotent, inserts and lists a note, and checks user_version. The agent runs the CI sequence from test.yml: npm run package, npm run lint, npm exec tsc -- --noEmit, npm test, and the Linux smoke test under xvfb-run, and opens a pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a local SQLite database to this Electron app. Read package.json, release/app/package.json, electron.vite.config.ts, every file under src/main and src/renderer, jest.config.js and .github/workflows/test.yml first, and check which Node version the installed Electron bundles. Prefer the node:sqlite module from that Node when it is available, otherwise use better-sqlite3 declared in release/app/package.json so it is rebuilt for Electron. Open the database under the app's userData path in the main process, apply versioned schema migrations, expose list, add and delete operations for a notes table through ipcMain.handle and a typed invoke in the preload, and show them on the home route. Add a Jest test in the node environment that runs the migrations against a temporary directory. Run the package, lint, type check, test and smoke-test steps CI runs, and 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 on its own branch. The diff adds src/main/db.ts, src/main/notes.ts and src/__tests__/db.test.ts, extends src/main/preload.ts and src/renderer/preload.d.ts, wires the handlers in src/main/main.ts and adds a Notes component to the renderer. release/app/package.json is unchanged when node:sqlite is used, and the description says which path the agent took and why.
The run's record keeps the npm run package, lint, tsc and jest output and the smoke test's result under xvfb-run, so a reviewer can see the main bundle build with the new module external and the migration test pass without rebuilding the app locally.
Before merging, a reviewer checks that the database path is right for each platform's userData, that the migration list only ever appends, and that every IPC handler validates its arguments, since the renderer is a web page and the main process should not trust it.
Run it on every new Electron app
A team that ships several Electron apps from this boilerplate starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. Each run reads its own Electron version and decides between node:sqlite and a rebuilt native module on that basis, and each opens its own pull request.
A request_id in the body makes a retry safe, and the API key's webhook posts run.completed or run.failed with the session_url when each turn ends, so a script can collect the pull request links and the test output.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Whether a storage module loads inside Electron, inside Jest and inside the packaged app are three different questions, and the boilerplate's postinstall, rebuild script and bundler externals all take part in the answer. The sandbox runs the whole CI sequence, including electron-builder packaging and the smoke start under a virtual display, and keeps the output, so the pull request shows the answer rather than asserting it.
The change crosses the main process, the preload boundary, the renderer and the tests. One run returns all of it with its log, and the same prompt runs against several Electron apps at once, each in its own sandbox with its own Electron version.
Frequently asked questions
Why node:sqlite instead of better-sqlite3?
Electron 44 bundles Node 24, and node:sqlite comes with it, so there is no native binary to rebuild for Electron's ABI and nothing to unpack from the asar. The agent checks the bundled Node version first; on an older Electron it falls back to better-sqlite3 in release/app/package.json, where electron-builder install-app-deps rebuilds it.
Can the renderer query the database directly?
No. The database stays in the main process, and the renderer reaches it only through the invoke calls the preload exposes, with Channels limiting the names. That keeps Node out of the web page, as the boilerplate's context isolation intends.
How are schema changes handled later?
Migrations are an ordered list in db.ts applied when user_version is below their index, inside a transaction. Adding a column is one new entry; the test runs the list twice to prove it is safe to rerun.
Where does the file live?
At app.db inside app.getPath('userData'), which is the per-user application directory on macOS, Windows and Linux. The path is logged through electron-log at startup so support can find it.
More Electron jobs
More jobs like this: Hand off a long task
- Add Log Rotation to a Docker Compose Stack (Docker Compose)
- Add Log Rotation to a Winston Logger (Winston)
- Add Logging to a Tauri App with tauri-plugin-log (Tauri)