# Add Keyboard Shortcuts to an Electron App from a Linear Issue

Yes. Label the Linear issue and an agent adds menu accelerators, a global shortcut that shows or hides the window and a shortcuts panel to your Electron app, tested.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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

- [Add a Local SQLite Database to an Electron App](https://getrush.ai/run/add-local-database/electron/)
- [Add Desktop Notifications to an Electron App](https://getrush.ai/run/add-notifications/electron/)
- [Add Persistent User Settings to an Electron App from a Linear Issue](https://getrush.ai/run/add-persistent-settings/electron/)

## The same job on other stacks

- [Add Keyboard Shortcuts to a Chrome Extension](https://getrush.ai/run/add-keyboard-shortcuts/chrome-extension/)

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

- [Add KV Caching to a Cloudflare Worker](https://getrush.ai/run/add-kv-caching/cloudflare-workers/)
- [Add Lambda Powertools to an AWS CDK App from a Linear Issue](https://getrush.ai/run/add-lambda-powertools/aws-cdk/)

## 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/)
