QuickClip

01

Overview

QuickClip adds one tile to Quick Settings and one popup under the keyboard. Both show the same history: your recent copies, kept in the Shell's memory and never written to disk except for snippets you explicitly pin.

02

Install

Requires

• GNOME Shell 50.
• A password manager that sets x-kde-passwordManagerHint on what it copies, for automatic skipping. KeePassXC and other KDE-convention managers do; without one, use Ignored apps in Preferences instead.

From a release

$ curl -LO https://github.com/Ghost-Assembly/quickclip/releases/latest/download/[email protected]
$ gnome-extensions install --force [email protected]
$ gnome-extensions enable [email protected]

From a clone

$ just setup
$ just install
$ just enable

03

Privacy

Everything QuickClip keeps lives in the Shell's memory for as long as the session runs. The one exception is a snippet you pin — the only clipboard content ever written to disk, in GSettings (dconf), and only because you asked.

What's skipped

• Password manager copies. A copy carrying the x-kde-passwordManagerHint MIME type — set by KeePassXC and other apps that follow the KDE convention — is never read, so its content never reaches QuickClip's memory. A manager that does not set this hint, such as some Electron-based ones, is not detected this way; add it to Ignored apps in Preferences instead.
• Ignored apps. Wayland does not say which application made a copy, so QuickClip uses whichever app is focused at the moment of the copy — which makes this check approximate, not exact.
• Pausing. Click the tile, or use the pause shortcut, to stop new copies being recorded until you resume.
• Expiry. Set Expire after in Preferences and a copy older than that is dropped. QuickClip keeps a single timer for whichever item is due next, and none at all while the history is empty. That timer stands still while the computer sleeps, so expired copies are also dropped whenever the menu or the popup opens, and on unlock.

The lock screen

QuickClip declares the unlock-dialog session mode so its history can survive a screen lock — but only when Clear on lock is turned off. Either way, while the screen is locked there is no tile, no popup, no keybinding and nothing is recorded. With Clear on lock on (the default), the history empties the moment the screen locks; with it off, the history stays in memory across the lock and is there again on unlock.

04

Transforms

Every transform is offered from Current's Transform submenu, or with Tab in the popup, whenever the copy on top qualifies. Two need no input at all and are always offered: they generate a fresh value instead of changing the copy.

A transform works only on a copy of up to 100,000 characters; a longer copy is offered only the generators, which ignore it. A date-time with no time zone is read as local time, the same as your system clock, not UTC.

05

Preferences

Open them from the Extensions app, or with just prefs from a clone. Recording is paused and resumed from the tile or the pause shortcut, not from this window; the state is remembered between sessions.

Setting a shortcut is checked against GNOME's own bindings (the window manager, the Shell, mutter, media keys and any custom shortcut) and QuickClip's other shortcut. A conflicting choice is refused, with a toast naming what already uses it — never silently overwritten. Other extensions' shortcuts are not visible to this check, so a conflict with one of those is not caught here.

06

Keyboard

Super+Shift+V opens the popup over any application window. It does nothing in the Activities overview or while the screen is locked.

Auto-paste sends Ctrl+Shift+V to the apps listed in Terminal apps — Ctrl+V would just insert a literal “v” there — and Ctrl+V to everything else, after a short delay so the previous window has focus back first.

07

Architecture

Every decision — what to record, what a transform does, what a shortcut may take — lives in a module that imports no GNOME API, only other modules like it, so the suite can test it whole on plain Node.

08

Testing

The unit suite runs on Node with the Shell's modules replaced by recording stubs. just test-live adds what CI cannot have: it boots a headless GNOME Shell, enables QuickClip, and checks that it starts listening and survives a disable and re-enable with no JavaScript errors or leaked signal or timeout sources. When a virtual clipboard can own the selection in that headless session it also checks that a plain-text copy is recorded and a password-manager copy is skipped; a headless Shell has no real seat, so those two checks are sometimes skipped there and covered by the manual checklist below instead.

Manual checklist

Run through this in a real session before a release; nothing here can run in CI, which has no GNOME Shell.

• The tile shows “QuickClip / Recording”; clicking it shows “Paused”; a copy while paused is not listed; clicking again resumes.
• Copy text in a GTK app → it appears under Recent and as Current.
• Copy a password from KeePassXC (if installed) → a “Sensitive copy skipped” row, and nothing new under Recent.
• Add the focused app to Ignored apps in Preferences, copy from it → “Copy in an ignored app skipped”.
• Take a screenshot to the clipboard → an Image row with a thumbnail and size.
• Super+Shift+V opens the popup; typing filters; ↑/↓ move; Enter pastes into the previous window (a GTK app takes Ctrl+V; Ptyxis takes Ctrl+Shift+V). Check Ghostty too, if it is available.
• Tab shows transforms for {"a":1}; Enter on Pretty-print JSON pastes the pretty result.
• Copy %E0%A4%A and choose URL decode → a notification reads “URL decode did not apply — Not valid URL encoding”, quoting nothing from the clipboard, and the clipboard is unchanged. No notification ever quotes clipboard text.
• Pin from Recent; the snippet appears under Pinned and in Preferences; unpin works from both.
• Set expiry to 1 minute; a copy disappears after about a minute.
• Lock the screen: the lock screen's Quick Settings has no QuickClip tile; Super+Shift+V does nothing; unlock → history empty (Clear on lock on).
• Turn Clear on lock off, copy something, lock, unlock → it is still listed; copies made while locked are not.
• Super+V still opens GNOME's notification list.
• In Preferences, choose Set… for the popup shortcut: the Shell asks whether to allow the app to inhibit shortcuts. Allow it, then press Super+V → the message tray stays shut and the shortcut is refused with a toast naming toggle-message-tray.
• just logs shows only [quickclip] lines with kinds and reasons — no clipboard content.

09

Packaging

just build makes the zip with plain zip, because gnome-extensions ships inside the gnome-shell package and CI has no GNOME. scripts/pack-check.sh keeps the official tool as the authority, diffs the two listings and confirms every shipped icon decodes — an icon that fails to load is silent.

The zip holds metadata.json, extension.js, prefs.js, modules/, schemas/, icons/ and stylesheet.css, which styles the tile and menu beyond what the Shell already styles. The uuid is written down once, in metadata.json, and everything else reads it from there.

10

Releasing

Set the version in metadata.json and package.json, commit, tag and push. The release workflow checks the tag against both files before building.

$ git tag -a v0.1.0 -m 'release v0.1.0'
$ git push origin v0.1.0

11

Development

just              # list every recipe
just test         # unit suite
just test-docs    # this site, in Chromium and Firefox
just lint         # eslint, prettier, gschema, shellcheck
just ci           # what CI runs: lint, tests, test-docs, security, build
just test-live    # headless gnome-shell smoke test, then the packed zip
just coverage     # unit suite with a coverage report
just docs         # serve this site on localhost:8000

Every decision lives in a module that imports no GNOME API, so the unit suite tests it on plain Node; see Architecture above.