• Repository

Meta

• License Expression: Apache-2.0
  SPDX License Expression
• Author: Mohammed El-sayed Ahmed
• Tags clipboard , gnome , wayland , gtk , linux
• Requires: Python >=3.10

Classifiers

• Development Status
  • 4 - Beta
• Environment
  • X11 Applications :: GTK
• Intended Audience
  • End Users/Desktop
• Operating System
  • POSIX :: Linux
• Programming Language
  • Python :: 3
• Topic
  • Desktop Environment :: Gnome

---

Clipman is a Wayland-native clipboard manager built on a GNOME Shell extension — no polling, no subprocesses, no screen flicker. It detects clipboard changes through Meta.Selection signals and communicates over D-Bus, making it fundamentally different from tools that rely on wl-paste --watch or timer-based polling. Privacy is built in: incognito mode, automatic sensitive data detection with 30-second auto-clear, and restrictive file permissions. The entire app is Python + GTK3 — no Electron, no heavy frameworks.

---

Features

Clipboard

• Text and image support — stores both content types with SHA256 deduplication
• Full-text search — instantly filter history by content
• Pin favorites — keep important entries permanently, exempt from pruning
• Filter tabs — switch between All, Text, Images, and Snippets views
• Snippet templates — save reusable text blocks for quick pasting
• Date grouping — entries organized into Today, Yesterday, and Older sections
• Inline editing — edit any text entry directly from the history
• Preview expansion — expand long entries inline to see full content
• URL detection — auto-detected with a one-click open button
• Character count — text entries show a character count badge
• Image preview — hover for a larger tooltip preview
• Auto-pruning — history capped at a configurable limit (pinned entries exempt)

Keyboard

Key	Action
+	Toggle the popup
keys	Navigate entries
Paste selected entry
+	Copy without pasting
Pin / unpin selected entry
Delete selected entry
Close popup

Appearance

• Dark and light themes — Catppuccin Mocha and Catppuccin Latte
• Font customization — adjustable size (8–20px) and 6 color presets (Default, Green, Peach, Mauve, Pink, Teal)
• Window opacity — configurable transparency from 30% to 100%

Privacy and Security

• Incognito mode — pause clipboard recording entirely
• Sensitive data detection — tokens and passwords auto-detected and cleared after 30 seconds
• Restrictive permissions — data directory 0o700, image files 0o600
• Path traversal protection — all image paths validated before file operations
• Backup validation — imported databases checked for schema integrity and sanitized
• Parameterized SQL — no injection vectors
• No shell execution — all subprocesses use argument lists, never shell=True
• Update notifications without telemetry — when enabled, the daemon does a single anonymous GET to api.github.com/repos/.../releases/latest once per day (no body, no params, no cookies, no identifiers). Default ON for source / PyPI / AUR installs, OFF for Snap and Flatpak (they auto-refresh). Settings → Updates to toggle. See ADR 0007.

Integration

• Terminal-aware paste — sends ++ in terminal emulators, + elsewhere
• XWayland support — clipboard detection for VSCode, Electron, and other XWayland apps via MIME type fallback
• Systemd autostart — runs as a background daemon, auto-restarts on crash
• Backup and restore — export and import your clipboard database from settings
• GNOME Shell extension — native clipboard monitoring with zero overhead

Performance

• Zero polling — event-driven via Meta.Selection signals and D-Bus
• SHA256 deduplication — copying the same content bumps it to the top without creating duplicates
• Configurable history — 50 to 5,000 entries
• Lightweight — Python + GTK3, no Electron or heavy frameworks

Requirements

• Ubuntu 22.04+ with GNOME 46–48 and Wayland
• Python 3.10+
• GTK 3

Dependencies are installed automatically by the install script.

Quick Start

# Clone the repo
gitclonehttps://github.com/MohammedEl-sayedAhmed/clipman.git
cdclipman

# Install dependencies, extension, keybinding, systemd service, and autostart
./install.sh

# Log out and back in to activate the GNOME Shell extension

# Start the daemon (runs automatically on next login)
systemctl--userstartclipman.service

The systemd service auto-restarts on crash and starts automatically on login.

If you cloned the repo and Clipman is useful to you, please star it on GitHub — source installs aren't counted anywhere else, and stars are how the project gets visibility.

Alternative Installation

Usage

Action	How
Open clipboard history	+
Paste an entry	Click on it or press
Copy without pasting	+
Pin / unpin an entry	Click the star icon or press
Delete an entry	Click the X icon or press
Filter by type	Click All, Text, Images, or Snippets tabs
Create a snippet	Switch to Snippets tab and click + Add
Search history	Type in the search bar
Edit a text entry	Click the edit icon on any text entry
Expand long text	Click the expand icon to see full content
Open a URL	Click the arrow icon on URL entries
Toggle incognito	Click the eye icon in the status bar
Clear all unpinned	Click Clear All
Close popup	or click outside

Settings

Click the gear icon to access settings. The panel is organised into five sections:

Section	Setting	Description
APPEARANCE	Theme	Segmented control: Dark (Catppuccin Mocha) / Light (Catppuccin Latte)
Font size	Text size for entries (8–20px)
Font color	Default, Green, Peach, Mauve, Pink, or Teal
Opacity	Window transparency (30%–100%)
HISTORY	Max history	Number of entries to keep (50–5,000)
SHORTCUTS	Toggle shortcut	Customize the popup-toggle keybinding (default Super+V) via an in-app capture dialog
Paste mode	How Clipman pastes after copy: Auto-detect (default — Ctrl+Shift+V in terminals, Ctrl+V elsewhere), Ctrl+V, Ctrl+Shift+V, or Shift+Insert
UPDATES	Check for updates	Toggle the daily anonymous check against GitHub Releases. Default: ON for source / PyPI / AUR, OFF for Snap and Flatpak (they auto-refresh). See ADR 0007
Check now	Manual check button — bypasses the 24h cooldown
DATA	Backup / Restore	Export and import your clipboard database

Settings are saved automatically and persist across sessions.

How It Works

1. A GNOME Shell extension detects clipboard changes natively via Meta.Selection's owner-changed signal — no polling, no subprocesses, no screen flicker
2. The extension reads the content using a MIME type fallback chain (text/plain;charset=utf-8 → UTF8_STRING → text/plain → STRING) and sends it to the daemon over D-Bus
3. The daemon stores entries in an SQLite database (WAL mode) at ~/.local/share/clipman/
4. Duplicates are detected via SHA256 hashing — copying the same content updates the timestamp and bumps it to the top
5. Pressing Super+V sends a D-Bus toggle to the daemon, which shows the popup window near the cursor
6. Clicking an entry copies it via wl-copy, hides the popup, and the extension simulates a paste keystroke using a Clutter virtual keyboard

Architecture

flowchart LR
 classDef user fill:#dbeafe,stroke:#3b82f6,color:#1e40af
 classDef gshell fill:#fef3c7,stroke:#d97706,color:#92400e
 classDef daemon fill:#dcfce7,stroke:#16a34a,color:#166534
 classDef storage fill:#f3e8ff,stroke:#9333ea,color:#6b21a8

 User((User)):::user
 App["Any GTK / Qt / Electron / terminal app"]:::user

 subgraph SHELL ["GNOME Shell"]
 Ext["clipman extension<br/>extension.js"]:::gshell
 KB["custom-keybinding<br/>(gsettings)"]:::gshell
 end

 Clip["Wayland clipboard"]:::gshell

 subgraph DAEMON ["clipman daemon (Python, GTK3)"]
 DbusSvc["dbus_service.py<br/>(com.clipman.Daemon)"]:::daemon
 Monitor["clipboard_monitor.py<br/>(dedupe + sensitive detect)"]:::daemon
 Window["window.py<br/>(GTK popup + settings)"]:::daemon
 Fallback["wl-paste --watch<br/>(used when extension absent)"]:::daemon
 end

 DB[("SQLite WAL<br/>~/.local/share/clipman/")]:::storage

 App -->|Ctrl+C| Clip
 Clip -. owner-changed .-> Ext
 Clip -. owner-changed .-> Fallback
 Ext -->|D-Bus: NewEntry text or image| DbusSvc
 Fallback --> DbusSvc

 DbusSvc --> Monitor
 Monitor -->|SHA256 dedup| DB

 User -->|Super+V| KB
 KB -->|launcher.sh toggle| DbusSvc
 DbusSvc -->|Toggle| Window
 Window <-->|history + snippets| DB

 User -->|click entry| Window
 Window -->|wl-copy| Clip
 Window -->|D-Bus: SimulatePaste mode| Ext
 Ext -->|virtual keyboard| App

The wl-paste --watch fallback only runs when the GNOME Shell extension is absent (e.g., other Wayland compositors). Inside snap confinement, neither path is available — snap users rely on the extension running in their host session.

Troubleshooting

Extension not loading after install Log out and back in. GNOME Shell extensions require a session restart to activate.

Super+V doesn't open Clipman The install script reassigns Super+V from GNOME's message tray. Check for conflicts:

gsettingsgetorg.gnome.shell.keybindingstoggle-message-tray

If it still shows <Super>v, the keybinding wasn't reassigned. Re-run ./install.sh.

XWayland apps (VSCode, Electron) not detected Verify the extension is enabled:

gnome-extensionslist--enabled|grepclipman

If missing, enable it with gnome-extensions enable clipman@clipman.com and log out/in.

Pasting shows ^V in VSCode/Electron integrated terminals Clipman auto-pastes with Ctrl+V, which standalone terminals interpret correctly. However, integrated terminals inside editors (VSCode, Cursor) expect Ctrl+Shift+V. Use Shift+Enter in Clipman to copy without auto-pasting, then manually Ctrl+Shift+V in the terminal.

Daemon not starting Check the service status:

systemctl--userstatusclipman.service
journalctl--user-uclipman.service-n20

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, project structure, coding guidelines, and how to run the test suite (303 tests, no GTK or D-Bus required).

Uninstall

./uninstall.sh

This stops the systemd service and removes the GNOME Shell extension, keybinding, systemd service, app icon, and optionally your clipboard history data.

License

Copyright 2025–2026 Mohammed El-sayed Ahmed

Licensed under the Apache License, Version 2.0. You may use, modify, and distribute this software, provided you:

• Include the original LICENSE and NOTICE files
• Give appropriate credit to the original author
• State any changes you made

See the LICENSE and NOTICE files for full details.

Star History

Acknowledgements

• Theme palette by Catppuccin
• CI powered by GitHub Actions

Verified details

These details have been verified by PyPI

Project links

• Homepage
• Issues
• Repository

GitHub Statistics

Maintainers

👁 Avatar for MohammedEl-sayedAhmed from gravatar.com
MohammedEl-sayedAhmed

Unverified details

These details have not been verified by PyPI

• Download URL: clipman_clipboard-1.0.6.tar.gz
• Upload date: May 20, 2026
• Size: 62.9 kB
• Tags: Source
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.13

Hashes for clipman_clipboard-1.0.6.tar.gz

Algorithm	Hash digest
SHA256	4fa9b37ca4ce331f4681856bdb55d3c4c09e15d6a165c4d8cbe01414916adea4
MD5	f989b64775a4449a21658e9b17ad779a
BLAKE2b-256	49876a5ce83ff02d5d455fc557bcc7e20befae9f2a8f4e0da2b843a755a87820

See more details on using hashes here.

• Download URL: clipman_clipboard-1.0.6-py3-none-any.whl
• Upload date: May 20, 2026
• Size: 40.4 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.13

Hashes for clipman_clipboard-1.0.6-py3-none-any.whl

Algorithm	Hash digest
SHA256	29542118231cc7a815f718fbabd0c6accf223b193a55a31051e3fddcf6adbd09
MD5	c68b3770539177cf9d368f9d92eba070
BLAKE2b-256	fbd91f849a4eee70dbff50972bfff4a09598e10aeb499caa631d7c48c29c2229

See more details on using hashes here.