✓ Stable v0.1.0

garclip

X11 clipboard manager with history, filtering, and persistence

garclip is a clipboard manager for the gardesk ecosystem that monitors both CLIPBOARD and PRIMARY X11 selections. It maintains a searchable history with configurable limits, supports text, images, and file URIs, provides content filtering by regex patterns and window class, and includes a keyboard-driven picker UI for selecting from history. Built with XFixes for efficient event-driven monitoring.

View on GitHub Download RPM

🎯 RPM Available

Installation

garclip is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garclip

Building from Source

$git clone https://github.com/espadon/gardesk

$cd gardesk/garclip

$cargo build --release

$sudo cp target/release/garclip /usr/local/bin/

$sudo cp target/release/garclipctl /usr/local/bin/

$sudo cp target/release/garclip-picker /usr/local/bin/

Components

garclip - Main daemon with built-in CLI commands
garclipctl - Standalone control utility
garclip-picker - GUI picker for selecting from history

Quick Start

Start the daemon and interact with the clipboard.

Starting the Daemon

$garclip daemon# start in background (default)

$garclip daemon --foreground# start in foreground for debugging

Basic Operations

$garclip copy "Hello, World!"# copy text

$echo "From stdin" | garclip copy# copy from stdin

$garclip paste# output clipboard to stdout

$garclip history# show recent history

$garclip select 42# select entry #42 from history

Using the Picker

$garclip-picker# open GUI picker

Use arrow keys to navigate, type to filter, Enter to select, Escape to cancel.

Autostart with gar

Add garclip to your gar configuration with a keybinding for the picker.

-- ~/.config/gar/init.lua

-- Start clipboard daemon
gar.exec_once("garclip daemon")

-- Bind Super+V to open clipboard picker
gar.bind("mod+v", function()
  gar.spawn("garclip-picker")
end)

systemd Service

Create a user service for automatic startup.

# ~/.config/systemd/user/garclip.service
[Unit]
Description=garclip clipboard manager
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/garclip daemon --foreground
Restart=on-failure

[Install]
WantedBy=graphical-session.target

$systemctl --user daemon-reload

$systemctl --user enable --now garclip.service

CLI Commands

Option	Type	Default	Description
`daemon [--foreground]`	-	-	Start the clipboard daemon (--foreground for debugging)
`copy [TEXT]`	-	-	Copy text to clipboard (reads from stdin if TEXT not provided)
`paste`	-	-	Output current clipboard content to stdout
`history [--limit N] [--json]`	-	-	Show clipboard history (default: 20 entries)
`select ID`	-	-	Select an entry from history (makes it current clipboard)
`delete ID`	-	-	Delete an entry from history
`clear`	-	-	Clear the clipboard
`clear-history [--keep-pinned]`	-	-	Clear history (optionally keep pinned entries)
`pin ID`	-	-	Pin an entry (survives history limit)
`unpin ID`	-	-	Unpin an entry
`list-pinned [--json]`	-	-	List pinned entries
`search QUERY [--limit N] [--json]`	-	-	Search history by text content
`status [--json]`	-	-	Show daemon status
`reload`	-	-	Reload configuration
`stop`	-	-	Stop the daemon

Configuration File

garclip loads configuration from ~/.config/garclip/config.toml. All settings have sensible defaults.

Minimal Configuration

A minimal configuration to get started:

# ~/.config/garclip/config.toml

[history]
max_entries = 500
persist = true

[behavior]
watch_primary = true
watch_clipboard = true
deduplicate = true

Full Configuration Reference

# ~/.config/garclip/config.toml

[history]
max_entries = 1000
persist = true
# persist_path = "~/.local/share/garclip/history.json"

[behavior]
watch_primary = true
watch_clipboard = true
deduplicate = true
ignore_empty = true
min_length = 1
max_length = 10485760      # 10MB
max_image_size = 52428800  # 50MB
poll_interval_ms = 250
primary_debounce_ms = 300

[filters]
ignore_patterns = [
  "^\\s*$",                # Empty/whitespace only
  "password[:=]",          # Lines containing passwords
]
ignore_classes = [
  "keepassxc",             # Password manager
  "1password",
]

[daemon]
# socket_path = "/run/user/1000/garclip.sock"
log_level = "info"
# log_file = "/tmp/garclip.log"

History Options

Option	Type	Default	Description
`max_entries`	usize	1000	Maximum number of entries to keep in history
`persist`	bool	true	Persist history across restarts
`persist_path`	path?	~/.local/share/garclip/history.json	Custom path for history file

Behavior Options

Option	Type	Default	Description
`watch_primary`	bool	true	Watch PRIMARY selection (middle-click paste)
`watch_clipboard`	bool	true	Watch CLIPBOARD selection (Ctrl+C)
`deduplicate`	bool	true	Deduplicate entries (move to front instead of adding)
`ignore_empty`	bool	true	Ignore empty clipboard content
`min_length`	usize	1	Minimum text length to record (bytes)
`max_length`	usize	10485760	Maximum text length to record (10MB default)
`max_image_size`	usize	52428800	Maximum image size to record (50MB default)
`poll_interval_ms`	u64	250	Poll interval in milliseconds (fallback when XFixes unavailable)
`primary_debounce_ms`	u64	300	Debounce time for PRIMARY selection to avoid partial text

Filter Options

Option	Type	Default	Description
`ignore_patterns`	string[]	[]	Regex patterns to ignore (matched against text content)
`ignore_classes`	string[]	[]	Window classes to ignore (case-insensitive substring match)

Daemon Options

Option	Type	Default	Description
`socket_path`	path?	$XDG_RUNTIME_DIR/garclip.sock	Custom socket path for IPC
`log_level`	string	"info"	Log level: trace, debug, info, warn, error
`log_file`	path?	none	Log file path (logs to stdout if not set)

Filter Examples

Common filter patterns for sensitive content:

[filters]
ignore_patterns = [
  # AWS credentials
  "AKIA[0-9A-Z]{16}",

  # Private keys
  "-----BEGIN.*PRIVATE KEY-----",

  # API keys/tokens
  "api[_-]?key\\s*[:=]",
  "bearer\\s+[a-zA-Z0-9_-]+",

  # Passwords in config
  "password\\s*[:=]\\s*\\S+",
]

ignore_classes = [
  "keepassxc",
  "1password",
  "bitwarden",
  "seahorse",      # GNOME keyring
  "gnome-keyring",
]

Reload Configuration

Reload configuration without restarting the daemon:

$garclip reload# via CLI

$kill -HUP $(cat $XDG_RUNTIME_DIR/garclip.pid)# via signal

Overview

garclip is an X11 clipboard manager that monitors selection changes and maintains a searchable history. It supports multiple content types, provides filtering capabilities, and includes a graphical picker for easy access to clipboard history.

Key Features

Monitors both CLIPBOARD (Ctrl+C) and PRIMARY (middle-click) selections
Supports text, images (PNG, JPEG), and file URIs
Event-driven monitoring via XFixes extension
Configurable history limit with persistence
Content filtering by regex patterns and window class
Entry pinning to protect important items
Deduplication using blake3 hashing
Source application tracking
IPC interface for external integrations
Graphical picker with fuzzy search

Architecture

garclip runs as a daemon that connects to the X11 server and monitors clipboard changes. It uses an async event loop with tokio for efficient I/O handling.

┌─────────────────────────────────────────────────────┐
│                   garclip daemon                     │
├─────────────────────────────────────────────────────┤
│  ┌──────────────────────┐  ┌─────────────────────┐ │
│  │   X11 Connection     │  │    IPC Server       │ │
│  │   (XFixes events)    │  │  (Unix socket)      │ │
│  └──────────┬───────────┘  └──────────┬──────────┘ │
│             │                         │            │
│             ▼                         ▼            │
│  ┌─────────────────────────────────────────────────┐│
│  │              Clipboard Manager                  ││
│  │   (Selection handling, content transfer)        ││
│  └─────────────────────────────────────────────────┘│
│                         │                          │
│         ┌───────────────┼───────────────┐         │
│         ▼               ▼               ▼         │
│  ┌───────────┐   ┌───────────┐   ┌───────────────┐│
│  │  Content  │   │  History  │   │    Event      ││
│  │  Filter   │   │  (JSON)   │   │  Broadcast    ││
│  └───────────┘   └───────────┘   └───────────────┘│
└─────────────────────────────────────────────────────┘

X11 Selections

X11 has two primary selection mechanisms that garclip monitors:

CLIPBOARD - Traditional copy/paste (Ctrl+C/Ctrl+V). Applications explicitly copy content to this selection.
PRIMARY - Implicit selection. Text becomes selected when highlighted with the mouse, pasted with middle-click.

Both selections can be enabled/disabled independently via configuration.

XFixes Monitoring

garclip uses the XFixes extension for efficient event-driven selection monitoring. When a selection owner changes, garclip receives an event and requests the content.

If XFixes is unavailable, garclip falls back to polling at a configurable interval (default 250ms). The poll_interval_ms option controls this fallback behavior.

Content Types

garclip supports three content types:

Text - Plain text content (UTF-8 string)
Image - PNG, JPEG, and other image formats (stored as raw bytes with MIME type)
Files - File URIs from file managers (supports cut/copy distinction)

Content type is detected during X11 selection transfer by negotiating with the selection owner for available targets.

Event Loop

The daemon event loop handles multiple event sources:

X11 events (selection changes, transfer requests)
IPC commands from clients
Unix signals (SIGTERM, SIGINT, SIGHUP for reload)
Auto-save timer (every 5 minutes)
PRIMARY debounce timer

Content Filtering

garclip provides multiple filtering mechanisms to prevent sensitive content from being stored in history.

Pattern Filters

Regex patterns in filters.ignore_patterns are matched against text content. If any pattern matches, the content is not stored.

[filters]
ignore_patterns = [
  "^\\s*$",           # Empty or whitespace-only
  "password[:=]",     # Password assignments
  "secret[:=]",       # Secret values
]

Window Filters

Window classes in filters.ignore_classes are matched against the source window's WM_CLASS property. Content from matching windows is not stored.

This is useful for excluding password managers and other sensitive applications.

Size Limits

Content size limits prevent large items from consuming memory:

min_length - Minimum text length (default: 1)
max_length - Maximum text size (default: 10MB)
max_image_size - Maximum image size (default: 50MB)

Clipboard Picker

garclip-picker is a graphical UI for browsing and selecting from clipboard history. It uses gartk for X11 window management and provides a keyboard-driven interface.

Launching the Picker

$garclip-picker# launch picker

The picker opens as a centered popup window and grabs keyboard focus. It fetches the current history from the garclip daemon and displays entries in a scrollable list.

Keybindings

Option	Type	Default	Description
`Up/Down`	-	-	Navigate through entries
`Page Up/Page Down`	-	-	Navigate by page (10 entries)
`Enter`	-	-	Select current entry and copy to clipboard
`Delete`	-	-	Delete current entry from history
`Escape`	-	-	Close picker without selecting
`Type characters`	-	-	Filter entries by text content
`Backspace`	-	-	Delete filter character
`Left/Right`	-	-	Move cursor in filter input
`Home/End`	-	-	Move cursor to start/end of filter

Entry Display

Each entry shows:

Entry ID (for reference in CLI commands)
Content preview (truncated text or type indicator for images/files)
Content type indicator (text/image/files)
Pin indicator (*) for pinned entries
Source application (if known)

Filtering

Type to filter entries. The filter matches against:

Entry preview text (case-insensitive substring)
Source application name

Press Backspace to delete filter characters. The entry list updates as you type.

Selection

Press Enter to select the highlighted entry. This:

Sends a select command to the daemon
The daemon copies the entry content to the CLIPBOARD selection
The picker closes

The content is now ready to paste (Ctrl+V) into any application.

gar Integration

Add a keybinding in gar to quickly access the picker:

-- ~/.config/gar/init.lua

-- Super+V opens clipboard picker
gar.bind("mod+v", function()
  gar.spawn("garclip-picker")
end)

-- Super+Shift+V opens picker in a specific position
gar.bind("mod+shift+v", function()
  gar.spawn("garclip-picker")
end)

Alternative: rofi Integration

If you prefer rofi, you can create a script that uses garclipctl:

#!/bin/bash
# garclip-rofi.sh

# Get history as JSON and format for rofi
selected=$(garclipctl history --json -l 50 | \
  jq -r '.[] | "\(.id)\t\(.preview)"' | \
  rofi -dmenu -i -p "Clipboard" -format "s" | \
  cut -f1)

if [ -n "$selected" ]; then
  garclipctl select "$selected"
fi

IPC Protocol

garclip provides an IPC interface via Unix domain socket for external control and event subscriptions. The socket is located at $XDG_RUNTIME_DIR/garclip.sock.

garclipctl Commands

Option	Type	Default	Description
`copy [TEXT]`	-	-	Copy text to clipboard
`paste`	-	-	Get current clipboard content
`history [-l N]`	-	-	Show clipboard history
`select ID`	-	-	Select entry from history
`delete ID`	-	-	Delete entry from history
`clear`	-	-	Clear clipboard
`clear-history [--keep-pinned]`	-	-	Clear history
`pin ID`	-	-	Pin an entry
`unpin ID`	-	-	Unpin an entry
`pinned`	-	-	List pinned entries
`search QUERY [-l N]`	-	-	Search history
`status`	-	-	Show daemon status
`reload`	-	-	Reload configuration
`stop`	-	-	Stop daemon

JSON Protocol

IPC uses newline-delimited JSON. Each command is a JSON object with a "command" field.

Available Commands

Option	Type	Default	Description
`copy`	-	-	Copy text to clipboard (text: string)
`copy_image`	-	-	Copy image to clipboard (data: base64, mime_type: string)
`paste`	-	-	Get current clipboard content
`history`	-	-	Get clipboard history (limit: number)
`select`	-	-	Select entry from history (id: number)
`delete`	-	-	Delete entry from history (id: number)
`clear`	-	-	Clear the clipboard
`clear_history`	-	-	Clear history (keep_pinned: bool)
`pin`	-	-	Pin an entry (id: number)
`unpin`	-	-	Unpin an entry (id: number)
`list_pinned`	-	-	List pinned entries
`search`	-	-	Search history (query: string, limit: number)
`status`	-	-	Get daemon status
`reload`	-	-	Reload configuration
`subscribe`	-	-	Subscribe to events (events: string[])
`quit`	-	-	Stop daemon

Command Examples

// Copy text
{"command": "copy", "text": "Hello, World!"}

// Get clipboard content
{"command": "paste"}

// Get history
{"command": "history", "limit": 20}

// Select entry
{"command": "select", "id": 42}

// Pin entry
{"command": "pin", "id": 42}

// Search
{"command": "search", "query": "hello", "limit": 10}

// Subscribe to events
{"command": "subscribe", "events": ["clipboard_changed", "entry_pinned"]}

// Subscribe to all events
{"command": "subscribe", "events": ["all"]}

Response Format

All commands return a JSON response:

// Success (no data)
{"success": true}

// Success with data
{"success": true, "data": {...}}

// Error
{"success": false, "error": "Entry not found"}

// Paste response
{
  "success": true,
  "data": {
    "id": 42,
    "content_type": "text",
    "text": "Hello, World!"
  }
}

// History response
{
  "success": true,
  "data": [
    {
      "id": 42,
      "preview": "Hello, World!",
      "content_type": "text",
      "size": 13,
      "timestamp": "2024-01-15T10:30:00Z",
      "pinned": false,
      "source": "firefox"
    }
  ]
}

// Status response
{
  "success": true,
  "data": {
    "history_count": 150,
    "pinned_count": 5,
    "owns_clipboard": true,
    "watching_primary": true,
    "uptime_secs": 3600,
    "current_preview": "Hello, World!"
  }
}

Event Subscription

The subscribe command keeps the connection open and streams events as they occur.

Event Types

Option	Type	Default	Description
`clipboard_changed`	-	-	Clipboard content changed (id, preview, source, content_type)
`history_cleared`	-	-	History was cleared
`entry_pinned`	-	-	Entry was pinned (id)
`entry_unpinned`	-	-	Entry was unpinned (id)
`entry_deleted`	-	-	Entry was deleted (id)
`entry_selected`	-	-	Entry was selected (id)

Event Examples

// Clipboard changed
{"event": "clipboard_changed", "id": 43, "preview": "New content",
 "source": "code", "content_type": "text"}

// Entry pinned
{"event": "entry_pinned", "id": 42}

// History cleared
{"event": "history_cleared"}

Status Bar Integration

Example script for displaying clipboard info in a status bar:

#!/bin/bash
# garclip-status.sh

status=$(garclipctl status --json 2>/dev/null)
if [ $? -ne 0 ]; then
  echo " offline"
  exit 0
fi

count=$(echo "$status" | jq -r '.history_count')
pinned=$(echo "$status" | jq -r '.pinned_count')

echo " $count ($pinned)"

Raw Socket Usage

$echo '{"command":"status"}' | nc -U $XDG_RUNTIME_DIR/garclip.sock

$echo '{"command":"history","limit":5}' | nc -U $XDG_RUNTIME_DIR/garclip.sock | jq

Common Issues

"Another garclip instance is running"

A previous instance may have crashed. Clean up stale files:

$rm -f $XDG_RUNTIME_DIR/garclip.pid

$rm -f $XDG_RUNTIME_DIR/garclip.sock

$garclip daemon

Clipboard content not being captured

Check if the daemon is running and content isn't being filtered:

$garclip status# check daemon status

$RUST_LOG=debug garclip daemon --foreground# run with debug logging

Look for "Filtering content" messages that indicate why content was skipped.

PRIMARY selection not captured

PRIMARY selection has a debounce to avoid partial text. Check configuration:

[behavior]
watch_primary = true
primary_debounce_ms = 300  # Reduce if needed

History not persisting

Ensure persistence is enabled and the data directory exists:

$mkdir -p ~/.local/share/garclip

$cat ~/.config/garclip/config.toml | grep persist

[history]
persist = true

Picker not showing entries

The picker connects to the daemon. Ensure it's running:

$garclip status# check if daemon is running

$garclip history# verify history has entries

Images not being captured

Check the max_image_size limit:

[behavior]
max_image_size = 104857600  # 100MB

Debugging

Enable Debug Logging

$RUST_LOG=debug garclip daemon --foreground

$RUST_LOG=garclip=trace garclip daemon --foreground# verbose tracing

Check XFixes Support

$xdpyinfo -ext XFIXES 2>/dev/null && echo "XFixes available" || echo "No XFixes"

Monitor Clipboard Changes

$xclip -selection clipboard -o# current CLIPBOARD

$xclip -selection primary -o# current PRIMARY

Test Copy/Paste

$echo "test" | garclip copy && garclip paste

Log Locations

Console output when running with --foreground
systemd journal: journalctl --user -u garclip
Custom log file: Set daemon.log_file in config
History file: ~/.local/share/garclip/history.json

Getting Help

If you encounter issues not covered here:

Check the GitHub Issues
Run with debug logging and include relevant output
Include your configuration file when reporting issues