# Add a System Tray Icon to an Electron App

Yes. An agent adds a tray icon with a show, hide and quit menu to your Electron app, makes closing the window hide it to the tray, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-tray-icon/electron/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts in the main process. In an Electron app like `electron-react-boilerplate/electron-react-boilerplate`, `src/main/main.ts` creates one `BrowserWindow` of 1024 by 728 with `icon: getAssetPath('icon.png')`, where `getAssetPath` resolves under `process.resourcesPath/assets` when `app.isPackaged` and under `app.getAppPath()/assets` otherwise. The window shows on `ready-to-show` unless `START_MINIMIZED` is set, sets `mainWindow = null` on `closed`, hands its menu to `MenuBuilder` from `src/main/menu.ts`, and sends new-window requests to `shell.openExternal`. `window-all-closed` quits on every platform but macOS, and `activate` recreates the window when it is `null`. `src/main/updates.ts` starts `electron-updater` once after the window exists. `src/main/preload.ts` exposes `electron.ipcRenderer` through `contextBridge` with a `Channels` union that holds only `ipc-example`.

The icon files are already there: `assets/icon.png`, `assets/icon.icns`, `assets/icon.ico` and `assets/icons/` with sizes from `16x16.png` to `1024x1024.png`, and `package.json`'s `build.extraResources` copies `./assets/**` into the packaged app, which is why `getAssetPath` works in both modes. The agent adds `src/main/tray.ts` with a `createTray(mainWindow)` that builds a `nativeImage` from `assets/icons/16x16.png` and `32x32.png` for the two scale factors, marks it a template image on macOS so it follows the menu bar's light and dark modes, sets a tooltip from `app.name`, and attaches a `Menu` with Show, Hide and Quit items. A click on the icon toggles the window on Windows and Linux, where that is the convention, and opens the menu on macOS.

Closing the window then hides it instead of ending the app. The agent adds a `close` handler on the window that calls `preventDefault()` and `hide()` unless a module-level `quitting` flag is set, sets that flag in `before-quit`, and makes the Quit menu item call `app.quit()` so the flag is set first. `window-all-closed` keeps its platform check, because a hidden window is not a closed one. The tray is created once in the `whenReady` chain next to `startAutoUpdates()`, held in a module variable so it is not garbage collected, and `activate` on macOS shows the hidden window rather than creating a second one. A `tray:toggle` channel is added to the `Channels` union in `preload.ts` only if the renderer needs to ask for the window to hide; otherwise the preload is untouched.

Tests follow the pattern in `src/__tests__/updates.test.ts`, which runs under `/** @jest-environment node */`, mocks `electron` and `electron-log` with `jest.mock`, and calls `jest.resetModules()` before each case. A new `src/__tests__/tray.test.ts` mocks `Tray`, `Menu.buildFromTemplate`, `nativeImage.createFromPath` and `app`, then checks that the tray is created once, that the Quit item calls `app.quit`, that a `close` event hides the window when not quitting and lets it through after `before-quit`. The agent runs `npm run lint`, `npm exec tsc -- --noEmit`, `npm test` and `npm run package`, which `.github/workflows/test.yml` runs on macOS, Windows and Ubuntu with Node 24, and then `xvfb-run --auto-servernum npm run test:smoke` to start the app headless as the Linux job does.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add a system tray icon. Closing the window should hide the app to the tray, and the tray menu should have Show, Hide and Quit.\" Do the work in this repository. Read src/main/main.ts, src/main/menu.ts, src/main/preload.ts, src/main/updates.ts, src/__tests__/updates.test.ts, jest.config.js, electron.vite.config.ts, the assets directory and the build section of package.json first. Add src/main/tray.ts that builds the icon from the existing assets/icons files through getAssetPath, uses a template image on macOS, and attaches a Show, Hide and Quit menu. Make the window's close event hide it unless the app is quitting, set that flag in before-quit, keep the window-all-closed platform behaviour, and create the tray once after the window exists. Add src/__tests__/tray.test.ts in the style of updates.test.ts with electron mocked. Run npm run lint, npm exec tsc -- --noEmit, npm test, npm run package and the smoke test under xvfb-run, and open a pull request that describes the behaviour on each platform.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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 with `src/main/tray.ts`, a few lines in `src/main/main.ts` for the close handler, the `before-quit` flag and the tray creation, and `src/__tests__/tray.test.ts`. The description says what a click on the icon does on each platform, how closing the window now behaves, and quotes the lint, type check, Jest and packaging summaries.

The transcript holds each `npm test` run, the `npm run package` output with the electron-builder targets it produced, and the smoke test's startup under `xvfb-run`, so a reviewer sees the app start with the tray code in place rather than trusting the description. The repository's `Test` workflow runs the same steps on all three platforms on the pull request.

Before merging, a reviewer checks that the tray object is held in a module variable so it survives garbage collection, that Quit sets the flag before `app.quit()` so the close handler lets the window go, that `window-all-closed` still quits on Windows and Linux when the user quits from the menu, and that the macOS template image is monochrome. A follow-up message to the same session adds a badge count or an Open at Login item, and the sandbox already has the native dependencies rebuilt.

## Run it on every Linear issue labelled agent

In the Project that holds the app, add an automation with this prompt and a `linear` trigger on `linear.issue.labeled` filtered to the `agent` label. Each labelled desktop issue starts its own run in its own sandbox and ends in its own pull request; the issue text follows the prompt as data, and the automation's `max_runs_per_hour` caps how many its triggers start.

A handler on your own server does the same without the automation: it receives Linear's webhook, puts the issue text into `input`, and sends `POST /o/{org}/sessions` with the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered webhook returns the run already started.

## Why run it on Rush?

Electron main-process work is slow to verify by hand: every change means `npm start`, a window, a click on the tray and a quit, and `npm run package` to see the icon in the packaged build takes minutes. In a Rush sandbox the agent has Node 24, the rebuilt native modules and a virtual display, runs the Jest suite, the packager and the smoke test itself, and keeps every run in the record.

Tray behaviour differs by platform, and a laptop shows only one. The pull request spells out the behaviour per platform and carries the Linux smoke test, and the repository's workflow adds macOS and Windows on the pull request. Several Electron apps can get the same feature at once, each in its own sandbox, each with its own pull request.

## Frequently asked questions

### Which icon does the tray use?

The existing `assets/icons/16x16.png` and `32x32.png`, loaded through the same `getAssetPath` the window icon uses, so the packaged app finds them under `process.resourcesPath/assets` through `build.extraResources`. On macOS the agent marks the image as a template so it inverts with the menu bar; if your icon is not monochrome, say so in the prompt and it adds a separate template file.

### Will closing the window still quit the app?

Not by default after this change: close hides the window and the app stays in the tray, which is what the issue asks for. Quit in the tray menu or the application menu sets a flag in `before-quit` and the close handler lets the window go. If you want close to quit on Windows and Linux and hide only on macOS, say so in the prompt.

### How is main-process code tested without a display?

The same way `updates.test.ts` tests the updater: `jest.mock('electron', ...)` replaces `Tray`, `Menu`, `nativeImage` and `app` with stubs, and the test calls the handlers the module registered. The smoke test under `xvfb-run` then starts the real app once to confirm it boots.

### Does the renderer need to change?

No. The tray lives entirely in the main process. The `Channels` union in `preload.ts` is extended only if you ask for a hide-to-tray button inside the React UI.

## More Electron jobs

- [Fix a Failing CI Run for an Electron App](https://getrush.ai/run/fix-failing-ci/electron/)
- [Turn Sentry Errors Into Fix Pull Requests for an Electron App](https://getrush.ai/run/fix-sentry-errors/electron/)
- [Audit the Dependency Licenses of an Electron App](https://getrush.ai/run/license-audit/electron/)

## The same job on other stacks

- [Add a System Tray Icon to a Tauri App](https://getrush.ai/run/add-tray-icon/tauri/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Tree View to a VS Code Extension](https://getrush.ai/run/add-tree-view/vscode-extension/)
- [Add Two-Factor Authentication to an Express and Mongoose API](https://getrush.ai/run/add-two-factor-auth/mongoose/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
