All jobs

Add Deep Link Handling to an Electron App from a Linear Issue

Yes. An agent registers a custom URL scheme, handles open-url and second-instance in the main process, sends parsed links to the renderer over IPC, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the app starts before it adds a way in. In an app shaped like electron-react-boilerplate/electron-react-boilerplate, package.json pins electron at ^44.4.0 and electron-builder ^26.15.3, builds with electron-vite, packages with npm run package, and its build section sets appId to org.erb.ElectronReact with mac, nsis and AppImage targets and no protocols entry, so no scheme is registered on install. src/main/main.ts holds one mainWindow, an ipcMain.on('ipc-example') handler, a setWindowOpenHandler that sends external URLs to the shell, and app.whenReady() followed by createWindow() and startAutoUpdates(); there is no single-instance lock. src/main/preload.ts exposes ipcRenderer.sendMessage, on and once over a Channels type whose only member is 'ipc-example', and src/renderer/App.tsx is a MemoryRouter with a single / route.

The checks are what the agent has to keep green. .github/workflows/test.yml runs on macOS, Windows and Ubuntu with Node 24: npm ci, npm run package, npm run lint, tsc --noEmit, npm test, then .erb/scripts/smoke-test.cjs, which starts the app with a remote debugging port and checks it comes up. src/__tests__/updates.test.ts shows the pattern for testing main-process code: a node Jest environment with electron, electron-updater and electron-log mocked.

The agent adds src/main/deep-links.ts with three parts. A parseDeepLink(url) function that accepts only the scheme the issue names, parses it with new URL(), allows a fixed set of hosts and paths, and returns a route and its parameters or null, so an unknown link cannot navigate anywhere. A registerDeepLinks(app, getWindow) function that calls app.setAsDefaultProtocolClient (with process.execPath and the script path when the app is not packaged, which is how a dev build registers on Windows and Linux), takes app.requestSingleInstanceLock() and quits if it loses, handles second-instance by finding the link in argv and focusing the window, and handles open-url on macOS, where the listener has to be attached before whenReady resolves. And a send step that forwards the parsed route to the renderer on a new 'deep-link' channel added to Channels in preload.ts, with a queue for a link that arrives before the window has loaded.

main.ts calls registerDeepLinks before app.whenReady(), and App.tsx gains a small DeepLinkListener inside the MemoryRouter that subscribes with window.electron.ipcRenderer.on('deep-link', …) and calls useNavigate. package.json gets a build.protocols entry with the scheme, which electron-builder writes into Info.plist for mac, the NSIS installer for Windows and the .desktop file for AppImage. A src/__tests__/deep-links.test.ts in the node environment covers the parser's accepted and rejected inputs and the queue, and the agent runs npm run lint, tsc --noEmit, npm test, npm run package and the smoke test under xvfb-run before it pushes.

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 asks for deep links: the app registers the custom scheme named in the issue, opening a link while the app is closed starts it on the right screen, opening one while it is running focuses the existing window and navigates, and unknown links are ignored. Read package.json, release/app/package.json, electron.vite.config.ts, src/main/main.ts, src/main/preload.ts, src/main/util.ts, src/main/updates.ts, src/renderer/App.tsx, src/renderer/preload.d.ts, src/__tests__/updates.test.ts, .erb/scripts/smoke-test.cjs and .github/workflows/test.yml first. Add src/main/deep-links.ts with a strict parser, setAsDefaultProtocolClient with the dev-mode arguments, a single-instance lock with a second-instance handler, an open-url handler attached before the app is ready, and a queue for links that arrive before the window loads; add a deep-link channel to Channels in preload.ts and a listener in App.tsx that navigates with the MemoryRouter; add build.protocols to package.json. Add a node-environment Jest test for the parser and the queue. Run npm run lint, tsc --noEmit, npm test, npm run package and the smoke test under xvfb-run, and open a pull request that links the issue and lists the accepted link shapes.",
  "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. It adds src/main/deep-links.ts and src/__tests__/deep-links.test.ts; it changes src/main/main.ts (the registration call before whenReady), src/main/preload.ts (the 'deep-link' member of Channels), src/renderer/App.tsx (the listener inside the router) and package.json (build.protocols). src/main/updates.ts, menu.ts and the vite config are untouched. The description lists the link shapes the parser accepts with the route each maps to, says what an unknown link does, and quotes the issue.

The checks are the proof. The repository's Test workflow runs on the pull request on all three operating systems: lint, type check, Jest including the new parser test, a full npm run package, and the smoke test that starts the packaged app. The trajectory at GET /o/{org}/sessions/{id}/messages keeps the same commands and their output from the sandbox, so a reviewer sees the app still starts rather than reading that it should.

Before merging, a reviewer tries the scheme on the platform they ship most, since protocol registration is the one part a Linux sandbox cannot exercise for macOS and Windows installers, and reads the parser's allowlist against the links their website will emit. Nothing is released by the run; the publish workflow is separate and untouched.

Run it on every Linear issue labelled agent

Sign in to Linear once from Settings → Connections, then add an automation to the Project that holds the app with this prompt and a linear trigger on linear.issue.labeled, naming the label in config.labels. The trigger appends the labelled issue after the prompt and fills in no placeholder, so the agent reads the scheme and the link shapes from the issue text. Each labelled issue starts its own run in its own sandbox and ends in its own pull request, up to the automation's max_runs_per_hour.

From your own server instead, a handler that receives Linear's webhook for the label sends POST /o/{org}/sessions with the repository and https://linear.app/<workspace>/issue/<ID> in resources, which puts the issue in the prompt through your Linear connection, and a request_id that is a UUID v5 of the issue id so a redelivered webhook returns the run it already started.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Deep links touch the two places an Electron app is hardest to test by hand: process startup and the packaged installer. Each try on a laptop is a full npm run package, an install, and a link clicked from a browser, and a mistake in the single-instance lock leaves a stray process behind. In a Rush sandbox the agent packages, runs the smoke test under xvfb-run exactly as the workflow does, reads the log and fixes the ordering of open-url and whenReady before anyone installs anything.

The pull request carries its proof: the repository's own workflow packages and starts the app on three operating systems, and the transcript keeps the lint, type check, test and package output beside the commands. A second issue, for a settings screen reachable by link or for an auth callback, is a second sandbox and a second pull request at the same time.

Frequently asked questions

Why a single-instance lock?

Because on Windows and Linux a protocol link starts a second copy of the app with the URL in its arguments. app.requestSingleInstanceLock() makes the second copy quit at once and hands its argv to the running one through the second-instance event, which is where the agent reads the link and focuses the window. macOS delivers links to the running app through open-url instead, and the handler covers both.

What happens to a link the app does not recognise?

Nothing. parseDeepLink accepts only the issue's scheme and a fixed set of hosts and paths, and returns null for anything else, so an unknown or malformed link neither navigates nor reaches the renderer. The test file covers rejected inputs as well as accepted ones.

Does it work in development, before the app is packaged?

On Windows and Linux, setAsDefaultProtocolClient is called with process.execPath and the script path when app.isPackaged is false, which is what registering a dev build requires. On macOS the scheme is read from the bundle's Info.plist, so a dev build does not register; the build.protocols entry covers the packaged app, and the pull request says so.

Why does the renderer listen through preload rather than reading the URL itself?

Because the renderer in this boilerplate runs with context isolation behind contextBridge, and preload.ts types every channel it allows. Adding 'deep-link' to Channels keeps that boundary: the main process parses and validates the link, and the renderer receives only a route and parameters.

More Electron jobs

The same job on other stacks

Keep reading