clipboard-indicator: a GNOME clipboard manager that keeps a searchable history

What the history actually holds, and the two switches that matter

Clipboard Indicator is described as the most popular, reliable and feature rich clipboard manager for GNOME, with over 2M downloads, and it is distributed through the GNOME Extensions site under the extension identifier [email protected].

The feature list is worth reading as a set of decisions rather than a list of buttons. It supports images in addition to text, which is the requirement that separates a real clipboard manager from a text buffer. Entries can be pinned so they stay at the top of the menu, and they can be tagged with custom labels to organise the history. Entries can be searched with text search, including regex, and existing text entries can be modified in place.

Then there are the two switches that determine whether you should install it at all.

Private mode temporarily pauses clipboard history when you are working with sensitive data. Exclude apps prevents clipboard tracking when specific applications are in focus, and the example given is password managers. Those are the two features that turn a convenience into something you can leave running, and they are the first thing to configure rather than the last.

Auto-clear history schedules automatic clipboard cleanup at regular intervals or at boot time, which is the third privacy control and the one that bounds growth.

The interface is keyboard first as well. The shortcut set covers opening and closing the menu, cycling through entries and activating actions without touching the mouse, and the in-menu controls are listed explicitly: arrow keys to move through the list, Enter to select, Delete to delete an item, v to paste directly from the menu, p to pin an item, t to add a tag, h to preview an image and e to edit an entry.

That is a complete workflow reachable without a mouse, which is the point of the extension living in the shell rather than in a separate window.

A shell extension, which is why the source install needs the UUID as a directory name

The install section is short and the reason it is shaped the way it is comes from how GNOME loads extensions.

Installation via git is performed by cloning the repo into your local gnome-shell extensions directory, usually ~/.local/share/gnome-shell/extensions/.

$ git clone https://github.com/Tudmotu/gnome-shell-extension-clipboard-indicator.git <extensions-dir>/[email protected]

The directory name is not cosmetic. GNOME identifies an extension by the UUID in the folder name, and the extension's own identity is [email protected], so a clone into a folder with any other name will not be picked up as that extension.

After cloning, the extension is practically installed yet disabled, and to enable it you run the following command.

$ gnome-extensions enable [email protected]

That two step is normal for a source install of any shell extension, and the reason is worth knowing even if you never install from source: the clone puts the files in place, the enable command tells the shell to load them, and a session restart is needed before the change takes effect in the running shell.

The Makefile shows the same install path scripted, and it makes the extension's internal structure visible. The install target removes the target directory, recreates it, and copies the module list, and the module list is the shape of the extension itself: the JavaScript files, the compiled locale message files, metadata.json, the stylesheet, the licence and readme, and the schemas/ directory. The default target compiles the locales and the settings schemas, which is the pair of build steps a GSettings based extension needs.

GSettings schemas, gettext locales, and a build that compiles both

The Makefile is short and each line describes a real mechanism.

The settings are compiled with glib-compile-schemas using the --strict flag, targeting the schemas/ directory. That is the GSettings mechanism, and the strict flag matters: it turns schema problems into build failures rather than letting a malformed schema through to produce a broken preferences dialog at runtime. The schemas/ directory in the repository listing is where those key files live, and the compile-settings target is what turns them into the binary form the shell reads.

The locales are compiled with msgfmt, one output per .po file into the matching .mo file under each locale's LC_MESSAGES directory. The update-po-files target runs xgettext against the JavaScript sources with the -L Python flag, which tells gettext to look for Python style comments even though the sources are JavaScript, because the translation comments in this codebase follow the gettext convention of a leading hash on the preceding line. The result is clipboard-indicator.pot at the repository root, the template catalogue, and the per-language .po files under locale/.

So the build has three moving parts: compile the schemas, compile the translations, and copy the whole set into the extensions directory. The install target does the copy, and the bundle target zips the same module list into bundle.zip, which is the artefact a distribution or a user who prefers a zip would take.

There is a fourth target that is unusual and worth knowing about, because it is how a shell extension developer works without a graphical session. The nested-session target runs dbus-run-session with gnome-shell under the nested wayland backend, with the MUTTER_DEBUG environment variables setting a dummy monitor layout and scale. That gives you a nested compositor to test the extension against, which is otherwise a hard problem because a shell extension cannot be exercised in a normal session without restarting the shell.

Pasting into terminals, which is where the extension has to work around the shell

There is a whole section of the README devoted to terminal support, and it exists because pasting into a terminal is a different problem from pasting into a normal application.

Pasting from the menu works by sending Shift+Insert to programs or Ctrl+Shift+Insert to terminals. The shift insert form is a long standing convention that a terminal emulator interprets, but a terminal multiplexer in the way does not, and neither does every terminal emulator, so the project documents the two workarounds.

For tmux, the configuration to add is a binding that sends the clipboard content as keys.

# Add Ctrl Shift Insert to paste for clipboard-indicator
bind -T root C-S-IC {
  run "tmux send-key \"$(xclip -d ${DISPLAY} -o -selection clipboard)\""
}

For Ghostty, the equivalent is a keybind mapping to paste_from_clipboard.

# Add Ctrl Shift Insert to paste for clipboard-indicator
keybind = ctrl+shift+insert=paste_from_clipboard

The tmux one is the interesting case, and the mechanism is worth understanding rather than copying. The binding is registered in the root table, and instead of asking tmux to paste, it shells out to xclip to read the X11 selection and then sends the result to tmux as keys. That is a workaround for a real conflict: tmux owns the terminal input, and the extension cannot reach inside it, so the paste has to be routed through tmux's own key handling.

The Ghostty binding is simpler because the terminal emulator itself is the one being told to paste, and the terminal can reach the clipboard directly.

The two known issues are stated plainly as well. Copying large images causes a short freeze, and pasting via menu does not work for every application. Both are the kind of limitation you find out about after installing, and both are cheap to check for yourself if you work with large images or with a specific set of applications.

The GNOME version table, and a release cycle that follows the desktop

The version support section is the most important thing in the README for a prospective user, because a shell extension is tied to the shell it extends.

Depending on your GNOME version, you need to install a specific Clipboard Indicator version. For GNOME 46 and above, use the latest version. For GNOME 45, use v57. For GNOME 42 to 44, use v47. For GNOME 40 to 41, use v39. And for GNOME below 40, use v37.

So the project supports a wide range of GNOME releases, and does it by keeping a separate version line for each generation, which is what you would expect from an extension that has to work across several years of shell API changes.

The release cycle section explains the cadence, and the word chosen for it is loosely. This project loosely follows the release cycle of GNOME, which means it will usually receive 2 updates a year, close to the release of a new major GNOME version. The advice for contributors is that if there are features you would like to implement or suggest, it is advised to start the discussion a month or two before a GNOME release.

That constraint shapes the project in a specific way. A shell extension cannot be ported to a new GNOME release quickly, because the shell's internals change, so the work is front loaded around the GNOME release rather than spread across the year. A user on a stable GNOME release is therefore looking at a version that was written for that release and has not been touched since, which is a reasonable trade but it does mean bug fixes for a specific shell version arrive on the GNOME cadence.

The contribution guidelines are equally specific, and unusually strict for a project of this size. If you want to contribute code, your best bet is to look for an issue with the label Up for grabs. Do not open unsolicited pull requests unless they are for updating translations. Look at the list of previous pull requests before you open one, because if your pull request conflicts with another it will be rejected. And if you have a feature idea, open an issue and discuss it there before implementing, since a pull request is not a platform for discussion.

Why a shell extension rather than a clipboard daemon

The interesting design question is why this lives inside the GNOME shell at all, since a clipboard manager could equally be a standalone application watching the clipboard, and many are.

The reason the extension model wins for this particular job is the keyboard. The extension's menu can be opened and driven entirely from the keyboard, with arrow keys to move through the list, Enter to select, Delete to remove, and single letter shortcuts for the actions you actually perform often, v to paste, p to pin, t to tag, h to preview an image, e to edit. A standalone clipboard window brings its own focus model, and a keyboard driven workflow in a separate window is a keyboard workflow you have to leave your current application to use, which defeats the point of a clipboard manager.

The cost of that choice is the extension platform itself. The extension has to be rebuilt against the shell's internals for each new GNOME generation, which is exactly what the version table is recording, and it means the extension is only usable on GNOME. The alternative, a standalone clipboard manager, would work on every desktop environment and would not need a per GNOME release branch, at the cost of a worse keyboard integration and a more conventional application experience.

There is a middle option worth naming, and it is a real one in the GNOME world. Several distributions package a clipboard manager as a regular application rather than as a shell extension, which gives you the history and the search without the shell integration, and which can be bound to a keyboard shortcut at the session level. The difference in use is that the extension's menu is part of the interface you are already in, while a standalone manager is a window you open, and the extension also inherits the shell's own styling.

The other thing to weigh is where the history lives. The README does not describe encryption, and an extension with a history of everything you copy is a sensitive store by nature, which is why private mode, app exclusions and auto-clear are the features to configure before anything else.

Editorial conclusion

clipboard-indicator fits a GNOME user who copies and pastes across applications constantly and wants a history that survives closing the source application, who can name the applications where clipboard capture should stop, and who prefers an extension that lives in the shell over a separate clipboard daemon. It does not fit a user on a GNOME version the extension does not support, and it does not fit someone who needs the history to be encrypted at rest or shared between machines. Check three things before you install it. Check your GNOME version against the support table, because the extension names a specific Clipboard Indicator version for each range, from v37 for GNOME below 40 through v39, v47 and v57 to the latest for GNOME 46 and above. Check whether the source install or the packaged version suits you, since the extension is also packaged by the community for many popular Linux distros, so your package manager may already have it. And check the two known issues, that copying large images causes a short freeze and that pasting via the menu does not work for every application. The last push was on 2026-05-07, the newest listed release is v44 from 2022-10-19, and the license is MIT.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Tudmotu/gnome-shell-extension-clipboard-indicator on GitHub