Skip to content

feat: add Linux X11 support with hotkey registration and error handler #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rgdevment merged 4 commits into from
Mar 13, 2026
Merged

feat: add Linux X11 support with hotkey registration and error handler #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
30bd2f5
feat: add Linux X11 support with hotkey registration and error handli…
rgdevment Mar 13, 2026
5981714
feat: update Linux X11 support with additional hotkey options and ins…
rgdevment Mar 13, 2026
5e3049c
fix: update installation notes for Linux X11 support and clarify perm…
rgdevment Mar 13, 2026
3a5f635
chore: remove unnecessary whitespace from README.md
rgdevment Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 44 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,23 +258,23 @@ If you care about privacy and control, this is made for you. Read our full [Priv

CopyPaste is designed for power users who prefer keyboard navigation:

| Shortcut | Action |
| :------------------------ | :-------------------------------------------------- |
| `Win+Alt+V` / `Cmd+Alt+V` | Open/close CopyPaste (default hotkey, customizable) |
| `↓` or `Tab` | Navigate from search to clipboard items |
| `↑` / `↓` | Navigate between clipboard items |
| `Space` | Expand/collapse selected card to see more text |
| `Ctrl+F` / `Cmd+F` | Focus search box |
| `Enter` | Paste selected item and return to previous app |
| `Delete` | Delete selected item |
| `P` | Pin/Unpin selected item |
| `E` | Edit card (add label and color) |
| `Ctrl+1` | Switch to Recent tab |
| `Ctrl+2` | Switch to Pinned tab |
| `Alt+C` | Switch to Content filter mode (text search) |
| `Alt+G` | Switch to Category filter mode (by color) |
| `Alt+T` | Switch to Type filter mode (by item type) |
| `Esc` | Clear current filter or close window |
| Shortcut | Action |
| :--------------------------------------- | :-------------------------------------------------- |
| `Win+Alt+V` / `Cmd+Alt+V` / `Ctrl+Alt+V` | Open/close CopyPaste (default hotkey, customizable) |
| `↓` or `Tab` | Navigate from search to clipboard items |
| `↑` / `↓` | Navigate between clipboard items |
| `Space` | Expand/collapse selected card to see more text |
| `Ctrl+F` / `Cmd+F` | Focus search box |
| `Enter` | Paste selected item and return to previous app |
| `Delete` | Delete selected item |
| `P` | Pin/Unpin selected item |
| `E` | Edit card (add label and color) |
| `Ctrl+1` | Switch to Recent tab |
| `Ctrl+2` | Switch to Pinned tab |
| `Alt+C` | Switch to Content filter mode (text search) |
| `Alt+G` | Switch to Category filter mode (by color) |
| `Alt+T` | Switch to Type filter mode (by item type) |
| `Esc` | Clear current filter or close window |

### Card Customization

Expand Down Expand Up @@ -344,7 +344,7 @@ Clipboard items (cards) can be expanded to show more text content:

### Keyboard-Only Workflow

1. **Press `Win+Alt+V`** → Window opens with focus on search box
1. **Press your platform default hotkey** (`Win+Alt+V` on Windows, `Cmd+Alt+V` on macOS, `Ctrl+Alt+V` on Linux) → Window opens with focus on search box
2. **Type to filter** (optional) → Results update in real-time (searches content and labels)
3. **Press `Esc`** (optional) → Clear search to see all items again
4. **Press `↓`** → Navigate to first clipboard item
Expand Down Expand Up @@ -396,7 +396,7 @@ brew tap rgdevment/tap && brew install --cask copypaste

Packages are hosted on [Cloudsmith](https://cloudsmith.io/~rgdevment/repos/copypaste/) — set up the repository once, then get updates through your system package manager.

**Debian, Ubuntu, Pop!_OS and derivatives:**
**Debian, Ubuntu, Pop!\_OS and derivatives:**

```bash
curl -1sLf 'https://dl.cloudsmith.io/public/rgdevment/copypaste/setup.deb.sh' | sudo -E bash
Expand All @@ -411,6 +411,8 @@ sudo dnf install copypaste
```

> **Note:** Requires an **X11 session**. On Wayland, global hotkey and auto-paste are unavailable — a warning is shown at startup.
> **Permissions note:** `apt`/`dnf` installation writes to system locations, so `sudo` is required. If your user cannot use `sudo`, those commands will fail with permission errors.
> **No-sudo alternatives:** Use **Homebrew (Linux)** if available for your user, or run the `.AppImage` from your home directory (`chmod +x CopyPaste-*.AppImage && ./CopyPaste-*.AppImage`).

**Alternative Linux (requires Homebrew installed):**

Expand All @@ -420,7 +422,9 @@ brew tap rgdevment/tap && brew install copypaste

---

After installing, open CopyPaste with **`Win+Alt+V`** (Windows), **`Cmd+Alt+V`** (macOS), or **`Super+Alt+V`** (Linux).
After installing, open CopyPaste with **`Win+Alt+V`** (Windows), **`Cmd+Alt+V`** (macOS), or **`Ctrl+Alt+V`** (Linux).

If `Ctrl+Alt+V` is already taken on Linux/X11 by another app or desktop shortcut, CopyPaste temporarily uses **`Ctrl+Alt+Shift+V`** for that session and shows a warning.

### Compatibility

Expand All @@ -436,13 +440,13 @@ After installing, open CopyPaste with **`Win+Alt+V`** (Windows), **`Cmd+Alt+V`**

_Not a fan of package managers? Direct packages are on [GitHub Releases](https://github.com/rgdevment/CopyPaste/releases/latest)._

| Platform | Download | Notes |
| :---------- | :------- | :---- |
| **Windows** | [`.exe`](https://github.com/rgdevment/CopyPaste/releases/latest) | Self-signed installer — see security note below |
| **macOS** | [`.dmg`](https://github.com/rgdevment/CopyPaste/releases/latest) | Universal binary (Apple Silicon + Intel) |
| **Linux** | [`.AppImage`](https://github.com/rgdevment/CopyPaste/releases/latest) | No install — `chmod +x` and run |
| **Linux** | [`.deb`](https://github.com/rgdevment/CopyPaste/releases/latest) | Debian, Ubuntu and derivatives |
| **Linux** | [`.rpm`](https://github.com/rgdevment/CopyPaste/releases/latest) | Fedora, RHEL and derivatives |
| Platform | Download | Notes |
| :---------- | :-------------------------------------------------------------------- | :---------------------------------------------- |
| **Windows** | [`.exe`](https://github.com/rgdevment/CopyPaste/releases/latest) | Self-signed installer — see security note below |
| **macOS** | [`.dmg`](https://github.com/rgdevment/CopyPaste/releases/latest) | Universal binary (Apple Silicon + Intel) |
| **Linux** | [`.AppImage`](https://github.com/rgdevment/CopyPaste/releases/latest) | No install — `chmod +x` and run |
| **Linux** | [`.deb`](https://github.com/rgdevment/CopyPaste/releases/latest) | Debian, Ubuntu and derivatives |
| **Linux** | [`.rpm`](https://github.com/rgdevment/CopyPaste/releases/latest) | Fedora, RHEL and derivatives |

<details>
<summary>⚠️ Windows standalone: security warnings</summary>
Expand Down Expand Up @@ -474,6 +478,9 @@ No. It works fully offline. The standalone version makes a lightweight check for
**Does it sync between devices?**
No. There’s intentionally no cloud sync.

**Do I need `sudo` to install on Linux?**
For `apt`/`dnf`, yes. They install to system paths, so without `sudo` (or equivalent admin rights) installation fails due to permissions. If you cannot use `sudo`, use Homebrew (if available) or the `.AppImage`.

**Where are my files stored?**
Windows: `%LOCALAPPDATA%\CopyPaste\` — macOS: `~/Library/Application Support/com.rgdevment.copypaste/CopyPaste/` — Linux: `~/.local/share/com.rgdevment.copypaste/CopyPaste/`. All contain the database, images, config, and logs.

Expand Down Expand Up @@ -597,17 +604,17 @@ Contributions are always appreciated — whether that's a bug report, a translat

If you're curious about what's under the hood:

| Technology | Why |
| :--------------------------------- | :------------------------------------------------------------------------------------ |
| **Flutter** | Cross-platform UI toolkit — native on Windows, macOS, and Linux. |
| **Dart** | Clean, performant language for core logic, services, and domain models. |
| **Platform Channels + FFI** | Native integration with each OS for clipboard hooks and system APIs. |
| **Windows Mica / macOS Sidebar** | Native translucent effects that match each platform's design language. |
| Technology | Why |
| :---------------------------------------------------- | :------------------------------------------------------------------------------------ |
| **Flutter** | Cross-platform UI toolkit — native on Windows, macOS, and Linux. |
| **Dart** | Clean, performant language for core logic, services, and domain models. |
| **Platform Channels + FFI** | Native integration with each OS for clipboard hooks and system APIs. |
| **Windows Mica / macOS Sidebar** | Native translucent effects that match each platform's design language. |
| **C++ Plugin (Win) / Swift (Mac) / C Plugin (Linux)** | Low-level clipboard listener to capture every content type before the OS discards it. |
| **Native C++ Launcher (Win)** | Lightweight splash process that appears instantly while Flutter warms up. |
| **SQLite (Drift) + FTS5** | Local database with full-text search across content and labels. |
| **Auto-update (Standalone)** | WinSparkle appcast on Windows · GitHub Releases API notification on macOS and Linux. |
| **Theme System** | Built-in Default and Compact themes, plus custom theme support via external packages. |
| **Native C++ Launcher (Win)** | Lightweight splash process that appears instantly while Flutter warms up. |
| **SQLite (Drift) + FTS5** | Local database with full-text search across content and labels. |
| **Auto-update (Standalone)** | WinSparkle appcast on Windows · GitHub Releases API notification on macOS and Linux. |
| **Theme System** | Built-in Default and Compact themes, plus custom theme support via external packages. |

---

Expand Down
22 changes: 20 additions & 2 deletions app/lib/l10n/app_en.arb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -357,6 +357,24 @@
"updateDismiss": "Later",
"@updateDismiss": { "description": "Button to dismiss the update notification" },

"waylandWarning": "Wayland detected: global hotkey and auto-paste are not supported. Use an X11 session for full functionality.",
"@waylandWarning": { "description": "Warning shown when running under Wayland instead of X11" }
"waylandWarning": "Wayland is not supported yet on Linux for global hotkeys and auto-paste because of desktop/session restrictions. Please use X11 or a compatible session.",
"@waylandWarning": { "description": "Warning shown immediately when running under Wayland on Linux" },

"linuxHotkeyFallbackWarning": "The shortcut {requested} is unavailable on this X11 desktop. CopyPaste is temporarily using {fallback}. You can change it in Settings.",
"@linuxHotkeyFallbackWarning": {
"description": "Shown when the preferred Linux hotkey is unavailable and a temporary fallback is active",
"placeholders": {
"requested": { "type": "String" },
"fallback": { "type": "String" }
}
},

"linuxHotkeyConflictWarning": "The shortcut {requested} is unavailable on this X11 desktop, and the temporary fallback {fallback} also failed. Open Settings to choose another shortcut.",
"@linuxHotkeyConflictWarning": {
"description": "Shown when both the requested Linux hotkey and the temporary fallback fail",
"placeholders": {
"requested": { "type": "String" },
"fallback": { "type": "String" }
}
}
}
4 changes: 3 additions & 1 deletion app/lib/l10n/app_es.arb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,5 +175,7 @@
"updateViewRelease": "Ver versi\u00f3n",
"updateDismiss": "Despu\u00e9s",

"waylandWarning": "Wayland detectado: el atajo global y el pegado autom\u00e1tico no est\u00e1n soportados. Usa una sesi\u00f3n X11 para funcionalidad completa."
"waylandWarning": "Wayland a\u00fan no est\u00e1 soportado en Linux para atajos globales y pegado autom\u00e1tico por restricciones del escritorio o la sesi\u00f3n. Usa X11 o una sesi\u00f3n compatible.",
"linuxHotkeyFallbackWarning": "El atajo {requested} no est\u00e1 disponible en este escritorio X11. CopyPaste est\u00e1 usando temporalmente {fallback}. Puedes cambiarlo en Configuraci\u00f3n.",
"linuxHotkeyConflictWarning": "El atajo {requested} no est\u00e1 disponible en este escritorio X11 y el fallback temporal {fallback} tambi\u00e9n fall\u00f3. Abre Configuraci\u00f3n para elegir otro atajo."
}
16 changes: 14 additions & 2 deletions app/lib/l10n/app_localizations.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -950,11 +950,23 @@ abstract class AppLocalizations {
/// **'Later'**
String get updateDismiss;

/// Warning shown when running under Wayland instead of X11
/// Warning shown immediately when running under Wayland on Linux
///
/// In en, this message translates to:
/// **'Wayland detected: global hotkey and auto-paste are not supported. Use an X11 session for full functionality.'**
/// **'Wayland is not supported yet on Linux for global hotkeys and auto-paste because of desktop/session restrictions. Please use X11 or a compatible session.'**
String get waylandWarning;

/// Shown when the preferred Linux hotkey is unavailable and a temporary fallback is active
///
/// In en, this message translates to:
/// **'The shortcut {requested} is unavailable on this X11 desktop. CopyPaste is temporarily using {fallback}. You can change it in Settings.'**
String linuxHotkeyFallbackWarning(String requested, String fallback);

/// Shown when both the requested Linux hotkey and the temporary fallback fail
///
/// In en, this message translates to:
/// **'The shortcut {requested} is unavailable on this X11 desktop, and the temporary fallback {fallback} also failed. Open Settings to choose another shortcut.'**
String linuxHotkeyConflictWarning(String requested, String fallback);
}

class _AppLocalizationsDelegate
Expand Down
12 changes: 11 additions & 1 deletion app/lib/l10n/app_localizations_en.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,5 +460,15 @@ class AppLocalizationsEn extends AppLocalizations {

@override
String get waylandWarning =>
'Wayland detected: global hotkey and auto-paste are not supported. Use an X11 session for full functionality.';
'Wayland is not supported yet on Linux for global hotkeys and auto-paste because of desktop/session restrictions. Please use X11 or a compatible session.';

@override
String linuxHotkeyFallbackWarning(String requested, String fallback) {
return 'The shortcut $requested is unavailable on this X11 desktop. CopyPaste is temporarily using $fallback. You can change it in Settings.';
}

@override
String linuxHotkeyConflictWarning(String requested, String fallback) {
return 'The shortcut $requested is unavailable on this X11 desktop, and the temporary fallback $fallback also failed. Open Settings to choose another shortcut.';
}
}
12 changes: 11 additions & 1 deletion app/lib/l10n/app_localizations_es.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -464,5 +464,15 @@ class AppLocalizationsEs extends AppLocalizations {

@override
String get waylandWarning =>
'Wayland detectado: el atajo global y el pegado automático no están soportados. Usa una sesión X11 para funcionalidad completa.';
'Wayland aún no está soportado en Linux para atajos globales y pegado automático por restricciones del escritorio o la sesión. Usa X11 o una sesión compatible.';

@override
String linuxHotkeyFallbackWarning(String requested, String fallback) {
return 'El atajo $requested no está disponible en este escritorio X11. CopyPaste está usando temporalmente $fallback. Puedes cambiarlo en Configuración.';
}

@override
String linuxHotkeyConflictWarning(String requested, String fallback) {
return 'El atajo $requested no está disponible en este escritorio X11 y el fallback temporal $fallback también falló. Abre Configuración para elegir otro atajo.';
}
}
Loading
Loading