What the agent does
The agent starts from the Linear issue and reads the three processes before it binds a key. In an app like electron-react-boilerplate/electron-react-boilerplate, src/main/main.ts creates one BrowserWindow of 1024 by 728 with a preload script, shows it on ready-to-show unless START_MINIMIZED is set, hands it to MenuBuilder, sends external links to shell.openExternal, starts electron-updater through src/main/updates.ts, and recreates the window on macOS activate. src/main/menu.ts builds a macOS template from the appMenu, editMenu and windowMenu roles, a View menu with reload and toggleDevTools in development and togglefullscreen always, and a Help menu of links, and a default template with &File, editMenu, &View and Help; every accelerator in it comes from a role, none is the app's own. src/main/preload.ts exposes ipcRenderer.sendMessage, on and once through contextBridge for a Channels type that allows only ipc-example, and src/renderer/App.tsx renders one route in a MemoryRouter. There is no globalShortcut import and no shortcut handling in the renderer.
The change adds one module and touches the three files around it. src/main/shortcuts.ts exports toggleWindow, which hides a visible focused window and otherwise shows and focuses it, and registerShortcuts, which calls globalShortcut.register with CommandOrControl+Shift+Space for toggleWindow, logs through electron-log when register returns false because another application holds the key, and unregisters everything on will-quit. main.ts calls it from whenReady after createWindow. menu.ts gains the app's own accelerators beside the roles: a Toggle Window item under Window and &View that shows the same key as the global shortcut, and a Keyboard Shortcuts item under Help on CommandOrControl+/ that sends shortcut with show-help to the renderer. preload.ts widens Channels to ipc-example | shortcut, which is the only change the typed bridge needs, and App.tsx adds a ShortcutsHelp component that listens on that channel through window.electron.ipcRenderer.on and lists each binding with a label that reads Cmd on macOS and Ctrl elsewhere.
Tests go where jest.config.js finds them. The config runs ts-jest from the isolated .erb/tooling install in a jsdom environment with check-build-exists.ts as a setup file, so npm run build must have run first; src/__tests__/updates.test.ts shows the pattern for main-process code: a @jest-environment node docblock, jest.mock('electron', ...) returning only the pieces under test, and jest.resetModules before each test. src/__tests__/shortcuts.test.ts mocks electron with a globalShortcut whose register records its arguments and returns true, asserts the accelerator and that will-quit unregisters, flips register to return false and asserts the electron-log error, and drives toggleWindow with a stub window whose isVisible and isFocused are controlled. src/__tests__/App.test.tsx already renders App with Testing Library and asserts the heading and links; the agent extends it so a shortcut event with show-help makes the panel visible.
Verification follows .github/workflows/test.yml, which runs on macOS, Windows and Ubuntu with Node 24: npm ci, npm run package (an electron-vite build followed by electron-builder build --publish never), npm run lint, npm exec tsc -- --noEmit and npm test, then xvfb-run --auto-servernum npm run test:smoke on Linux. .erb/scripts/smoke-test.cjs spawns npm start with a remote debugging port and waits for a page target, so the agent runs it under xvfb-run in the sandbox the way CI does, and then, with the app still running under the virtual display, injects the key chord with a key-injection tool and takes a screenshot before and after, so the pull request shows the window hiding and returning. package.json requires Node 24 or newer and npm 10 or newer, which the sandbox matches.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labelled agent says: \"Add keyboard shortcuts: a global shortcut that shows or hides the main window, menu accelerators for the app's own actions, and a panel that lists the bindings.\" Do the work in this repository. Read package.json, src/main/main.ts, src/main/menu.ts, src/main/preload.ts, src/main/updates.ts, src/renderer/App.tsx, src/renderer/preload.d.ts, src/__tests__/updates.test.ts, src/__tests__/App.test.tsx, jest.config.js, .erb/scripts/check-build-exists.ts, .erb/scripts/smoke-test.cjs and .github/workflows/test.yml first. Add src/main/shortcuts.ts with a toggleWindow function and a registerShortcuts function that registers CommandOrControl+Shift+Space through globalShortcut, logs through electron-log when register returns false, and unregisters everything on will-quit; call it from whenReady after createWindow. Add the app's own accelerators to MenuBuilder in both templates, a Toggle Window item showing the same key and a Keyboard Shortcuts item on CommandOrControl+/ that sends a shortcut channel message to the renderer. Widen the Channels type in preload.ts, and add a ShortcutsHelp component to App.tsx that opens on that message and lists each binding with a platform-aware label. Add src/__tests__/shortcuts.test.ts in the style of updates.test.ts with electron mocked, and extend App.test.tsx for the panel. Run npm ci, npm run build, npm run lint, npm exec tsc -- --noEmit and npm test, then xvfb-run --auto-servernum npm run test:smoke, and with the app running under the virtual display press the global shortcut and take a screenshot before and after. Do not change electron.vite.config.ts, the updater, or any workflow. Open a pull request that links the issue, lists each binding and its key per platform, and quotes the test, type check and lint output.",
"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 adding src/main/shortcuts.ts and src/__tests__/shortcuts.test.ts, and changing src/main/main.ts, src/main/menu.ts, src/main/preload.ts, src/renderer/App.tsx and src/__tests__/App.test.tsx. The body links the Linear issue, lists each binding with its key on macOS and on Windows and Linux, says what happens when the global key is already taken, and quotes the Jest summary, the tsc run and the lint result.
The transcript keeps npm ci, the electron-vite build, the Jest run before and after the module existed, the type check, the lint, the smoke test under xvfb-run, and the two screenshots around the injected key chord, so a reviewer sees the window hide and return rather than reading that it should. The repository's Test workflow runs the same steps on all three operating systems on the pull request.
Before merging, a reviewer checks that the global shortcut is unregistered on will-quit, that a false from register is logged and not thrown, that the menu accelerators do not collide with the editMenu and windowMenu roles' defaults, and that the Channels union still lists only channels the renderer should see. A follow-up on the same session can make the bindings user-configurable and persist them with electron-store, with node_modules and the build already in place.
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 issue starts its own run in its own sandbox and ends in its own pull request; the issue text follows the prompt as data, so one issue can ask for a different default key or a third accelerator, and the trigger fills in no placeholder. Only a change by someone in your Rush org fires it, and changes made by an app integration never do.
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. A webhook_url on that key posts run.completed or run.failed when the turn ends.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A shortcut change is checked by building the app, launching it, pressing keys and watching the window, and the main-process half of it cannot be seen in a browser. In a Rush sandbox the agent has Node 24, the electron-vite build, a virtual display for the smoke test and a way to inject the key chord, so it does the whole loop itself and keeps the screenshots, and the Jest tests with electron mocked cover the registration and the toggle logic without a display at all.
Small desktop requests pile up because each one costs a build and a manual check on someone's machine. Labelling the issue hands that cycle to a sandbox, and the pull request arrives with the build, the three CI checks and the visual evidence already done. Several labelled issues run at once, each in its own sandbox, and a review comment becomes a follow-up on the same session.
Frequently asked questions
What happens when another app already uses the global key?
globalShortcut.register returns false and the app keeps running; the agent logs that through electron-log so it shows in the log file the updater already writes to, and the shortcuts panel marks the binding as unavailable. The test flips register to return false and asserts the log line.
Will the shortcut work when the window is hidden or minimised?
Yes for the global one. globalShortcut fires even when the app has no focused window, which is why toggleWindow is bound to it rather than to a menu accelerator, which only fires while the app's menu is active. The menu item shows the same key so users can discover it.
Does the renderer get access to more of Electron?
No. The preload bridge still exposes only sendMessage, on and once, and the only change is that the Channels type now allows shortcut beside ipc-example. The renderer learns the binding names from the message payload, not from electron itself.
How are main-process modules tested without launching Electron?
The same way updates.test.ts already does: a @jest-environment node test that mocks electron with only globalShortcut and app, requires the module fresh after jest.resetModules, and asserts on the recorded calls. The smoke test under xvfb-run and the screenshots cover the real wiring.
More Electron jobs
The same job on other stacks
- Add Keyboard Shortcuts to a Chrome Extension (Chrome Extension)
More jobs like this: Turn a Linear label into a PR
- Add KV Caching to a Cloudflare Worker (Cloudflare Workers)
- Add Lambda Powertools to an AWS CDK App from a Linear Issue (AWS CDK)