Workaround: Global hotkeys for Electron apps on COSMIC Wayland (OpenWhispr example)

[nickpitts32]

Hey everyone — new to Linux here (running Garuda Linux with COSMIC as my desktop). I've been using AI (Claude Code specifically) to help me navigate things I wouldn't otherwise know how to do, and between the two of us we figured out a workaround I wanted to share with the community.
I'm a heavy voice dictation user and wanted to get OpenWhispr working on COSMIC with a global hotkey. After a few hours of troubleshooting, Claude Code reverse-engineered a solution using Electron's Node inspector protocol and COSMIC's native keybinding system. I have no idea if this is the "right" way to do it, but it works great for me.
I also just want to say — COSMIC is the first desktop environment I've genuinely fallen in love with. Coming from Windows and Mac this thing just clicks for me. Happy to be here.

Getting OpenWhispr (and other Electron apps) Working with Global Hotkeys on COSMIC/Wayland

The Problem

COSMIC doesn't yet support the XDG GlobalShortcuts portal, which means Electron apps can't register global keyboard shortcuts. This affects any Electron-based app that relies on a system-wide hotkey — in my case, OpenWhispr, a voice-to-text dictation app.

On GNOME or KDE, OpenWhispr can grab a global hotkey to start/stop dictation. On COSMIC, pressing the hotkey does nothing. Running under XWayland (--ozone-platform=x11) partially works but breaks text injection into native Wayland apps.

The Solution

The workaround uses three pieces:

1. COSMIC's native keybinding system to trigger a script
2. Electron's Node.js inspector protocol to control the app programmatically
3. ydotool to simulate paste keystrokes (with terminal detection for Ctrl+Shift+V)

Step 1: Launch OpenWhispr with the Node Inspector

Edit ~/.local/share/applications/openwhispr.desktop:

[Desktop Entry]
Name=OpenWhispr
Exec=/path/to/OpenWhispr.AppImage --inspect=19223 --remote-debugging-port=19222
Icon=openwhispr
Type=Application
Categories=Utility;

The --inspect=19223 flag exposes the Electron main process via the V8 inspector protocol, allowing external scripts to execute code inside the app.

Step 2: Create the Toggle Script

Save this as ~/.local/bin/whispr-toggle and make it executable (chmod +x):

#!/usr/bin/env node
const http = require('http');
const { execSync, spawnSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const STATE_FILE = '/tmp/whispr-toggle-state';
const LOCK_FILE = '/tmp/whispr-toggle.pid';
const DB = path.join(process.env.HOME, '.config/open-whispr/transcriptions.db');

try {
  const oldPid = parseInt(fs.readFileSync(LOCK_FILE, 'utf8'), 10);
  if (oldPid && oldPid !== process.pid) process.kill(oldPid, 'SIGTERM');
} catch {}

function sendIPC(message) {
  return new Promise((resolve, reject) => {
    http.get('http://localhost:19223/json', (res) => {
      let d = '';
      res.on('data', c => d += c);
      res.on('end', () => {
        const t = JSON.parse(d);
        const ws = new WebSocket(t[0].webSocketDebuggerUrl);
        ws.onopen = () => ws.send(JSON.stringify({
          id: 1, method: 'Runtime.evaluate',
          params: { expression: `
            try {
              const req = process.mainModule.require.bind(process.mainModule);
              const { BrowserWindow } = req('electron');
              const w = BrowserWindow.getAllWindows().find(w => {
                const u = w.webContents.getURL();
                return u.includes('index.html') && !u.includes('panel=') && !u.includes('agent=');
              });
              if (w) {
                ${message === 'start-dictation' ? `
                  if (w.isMinimized()) w.restore();
                  if (!w.isVisible()) { if (typeof w.showInactive==='function') w.showInactive(); else w.show(); }
                ` : `
                  w.blur();
                `}
                w.webContents.send('${message}');
                'ok';
              }
            } catch(e) { e.message; }
          `}
        }));
        ws.onmessage = () => { ws.close(); resolve(); };
        ws.onerror = () => reject();
      });
    }).on('error', reject);
  });
}

function getLastId() {
  try {
    return parseInt(execSync(`sqlite3 "${DB}" "SELECT id FROM transcriptions ORDER BY id DESC LIMIT 1;"`, { timeout: 2000 }).toString().trim(), 10) || 0;
  } catch { return 0; }
}

function getNewText(afterId) {
  try {
    return execSync(`sqlite3 "${DB}" "SELECT text FROM transcriptions WHERE id > ${afterId} AND status='completed' ORDER BY id DESC LIMIT 1;"`, { timeout: 2000 }).toString().trim();
  } catch { return ''; }
}

function isTerminalFocused() {
  const terminals = ['alacritty', 'kitty', 'foot', 'wezterm', 'ghostty', 'konsole',
    'gnome-terminal', 'terminator', 'tilix', 'xterm', 'urxvt', 'st', 'cosmic-term'];
  try {
    const ppid = execSync("cat /proc/$(xdotool getactivewindow getwindowpid 2>/dev/null || echo 1)/comm 2>/dev/null", { timeout: 1000 }).toString().trim().toLowerCase();
    return terminals.some(t => ppid.includes(t));
  } catch {}
  return false;
}

function paste(text) {
  spawnSync('wl-copy', ['--', text], { timeout: 2000 });
  spawnSync('sleep', ['0.1']);
  if (isTerminalFocused()) {
    execSync('ydotool key 29:1 42:1 47:1 47:0 42:0 29:0', { timeout: 2000 }); // Ctrl+Shift+V
  } else {
    execSync('ydotool key 29:1 47:1 47:0 29:0', { timeout: 2000 }); // Ctrl+V
  }
}

async function main() {
  let isOn = false;
  let lastId = 0;
  try {
    const parts = fs.readFileSync(STATE_FILE, 'utf8').trim().split('\n');
    isOn = parts[0] === 'on';
    lastId = parseInt(parts[1], 10) || 0;
  } catch {}

  if (!isOn) {
    lastId = getLastId();
    fs.writeFileSync(STATE_FILE, `on\n${lastId}`);
    await sendIPC('start-dictation');
    process.exit(0);
  } else {
    lastId = parseInt(fs.readFileSync(STATE_FILE, 'utf8').trim().split('\n')[1], 10) || 0;
    fs.writeFileSync(STATE_FILE, 'off');
    fs.writeFileSync(LOCK_FILE, String(process.pid));
    await sendIPC('stop-dictation');

    for (let i = 0; i < 75; i++) {
      await new Promise(r => setTimeout(r, 200));
      const text = getNewText(lastId);
      if (text) { paste(text); break; }
    }
    try { fs.unlinkSync(LOCK_FILE); } catch {}
    process.exit(0);
  }
}

main().catch(() => process.exit(1));

Step 3: Set Up the COSMIC Keybinding

Create ~/.config/cosmic/com.system76.CosmicSettings.Shortcuts/v1/custom:

{
    (modifiers: [Super], key: "grave"): Spawn("/home/YOUR_USERNAME/.local/bin/whispr-toggle"),
}

Replace YOUR_USERNAME with your actual username. Log out and back in for the keybinding to take effect.

Step 4: Dependencies

Make sure you have these installed:

sudo pacman -S wl-clipboard xdotool ydotool sqlite

Ensure ydotoold is running (it provides the uinput daemon for simulating keypresses on Wayland):

systemctl --user enable --now ydotool

How It Works

1. You press Super+` — COSMIC runs the toggle script
2. First press: The script connects to OpenWhispr's Node inspector via WebSocket, finds the main BrowserWindow, and sends a start-dictation IPC message to the renderer. Recording begins.
3. Second press: The script sends stop-dictation. Audio is sent to Groq (or your configured provider) for transcription. The script polls OpenWhispr's SQLite database every 200ms until the transcription appears.
4. Once the transcription arrives, the script copies it to the Wayland clipboard via wl-copy and simulates a paste keystroke via ydotool (Ctrl+V for regular apps, Ctrl+Shift+V for terminals).

Why Not Just Use toggle-dictation?

OpenWhispr's toggle-dictation IPC message triggers the app's internal paste mechanism, which pastes a stale/cached transcription instead of waiting for the new one. By using separate start-dictation and stop-dictation messages and handling paste externally, we get reliable behavior.

Broader Applicability

This technique — using --inspect to expose an Electron app's main process, then controlling it via the V8 inspector protocol — works for any Electron app that needs global hotkey support on COSMIC. The general pattern is:

1. Launch the Electron app with --inspect=PORT
2. Write a script that connects to http://localhost:PORT/json, opens a WebSocket to the debugger, and calls Runtime.evaluate to execute code in the main process
3. Bind the script to a COSMIC keybinding via Spawn()

This should become unnecessary once COSMIC implements the GlobalShortcuts portal, but until then it's a solid workaround.

Environment

• OS: Garuda Linux (Arch-based)
• Desktop: COSMIC
• Session: Wayland
• OpenWhispr: v1.6.3 (AppImage)
• Node.js: v25.7.0 (needed for built-in WebSocket support in the toggle script)

openwhispr-cosmic-guide.md