garclip

Architecture

garclip is a Cargo workspace with three crates that work together:

The daemon runs a Tokio async event loop coordinating X11 monitoring, IPC serving, event broadcasting, auto-save, and signal handling. garclipctl and garclip-picker are standalone binaries that connect to the daemon's Unix socket.

Daemon Process

The main garclip daemon monitors X11 clipboard changes and maintains the history. It uses a Tokio async runtime with multiple concurrent tasks:

• XFixes monitor - Receives SelectionNotify events when clipboard owner changes
• Poll timer - 250ms fallback polling if XFixes unavailable
• IPC server - Accepts client connections via Unix socket, spawns per-client handler tasks
• Event broadcaster - Pushes events (clipboard_changed, entry_pinned, etc.) to subscribed clients
• Auto-save timer - Persists history to disk every 5 minutes
• Signal handler - SIGTERM/SIGINT for graceful shutdown, SIGHUP for config reload

DaemonState

The DaemonState struct in daemon/state.rs owns the ClipboardManager and executes all commands. It handles debounced PRIMARY selection (300ms delay to avoid capturing partial drag selections), processes X11 events, and persists/loads history on demand.

PID File

On startup, the daemon checks for an existing instance via $XDG_RUNTIME_DIR/garclip.pid. It writes a PID file on start and removes it on clean exit.

garclipctl CLI

Command-line interface for interacting with the daemon. Uses blocking IPC (no async runtime).

Global flags: --socket PATH for custom socket, --json for machine-readable output.

garclip-picker UI

A graphical picker window rendered with gartk (Cairo/Pango). Opens as a 600x420px popup centered on the primary monitor with exclusive keyboard grab.

Keyboard Controls

Visual Layout

┌──────────────────────────────────┐
│ Search: [user input]▌            │
├──────────────────────────────────┤
│ * entry1 [pinned, 100ch preview] │
│ ▌ entry2 [selected, highlighted] │
│   entry3 [text preview...]       │
│   entry4 [Image: image/png]      │
│   entry5 [Copy: 2 files]         │
│   ...                            │
└──────────────────────────────────┘

History Management

garclip maintains a clipboard history using a VecDeque<ClipboardEntry> with newest entries at the front. The history supports configurable limits, persistence, deduplication, and pinning.

Storage & Persistence

History is stored in JSON format at ~/.local/share/garclip/history.json. Each entry contains:

{
  "id": 42,
  "content": { "Text": "Hello world" },
  "source": "firefox",
  "timestamp": "2024-01-15T10:30:00Z",
  "pinned": false,
  "hash": "abc123..."
}

Images are base64-encoded in the JSON with their MIME type. File URIs are stored as string arrays with a cut/copy flag.

History is saved on daemon shutdown (SIGTERM/SIGINT), every 5 minutes via auto-save, and on explicit garclipctl clear-history. On load, the next ID counter is rebuilt from the highest existing ID.

Deduplication

When deduplicate = true, copying the same content moves the existing entry to the front instead of creating a duplicate. Uses blake3 hashing for fast comparison.

How It Works

1. Calculate blake3(content) for new clipboard data
2. Check the in-memory HashSet<String> for existing hash
3. If found: remove old entry, update timestamp, re-add to front
4. If not found: create new entry with auto-incremented ID

This keeps frequently copied text at the top of history without creating duplicate entries.

Pinning Entries

Pinned entries are protected from automatic removal when history exceeds max_entries. Pin frequently used snippets to keep them always available.

X11 Integration

garclip interacts with X11 through several mechanisms for clipboard monitoring and content transfer. The X11 module handles atom interning, selection ownership, content negotiation, and window class identification.

CLIPBOARD vs PRIMARY

X11 has multiple clipboard selections. garclip monitors both by default:

PRIMARY selection is debounced by primary_debounce_ms (default 300ms) to avoid capturing partial text during drag selection.

XFixes Extension

garclip uses the XFixes extension (version 5.0+) for event-driven clipboard monitoring. When a selection owner changes, XFixes sends a SelectionNotify event immediately rather than requiring polling.

How It Works

1. Create a hidden input-only window for selection ownership
2. Subscribe via xfixes_select_selection_input() for SetSelectionOwner, WindowDestroy, ClientClose events
3. On SelectionNotify: request TARGETS from new owner, negotiate content format, convert and read
4. When garclip sets clipboard: call claim_ownership(CLIPBOARD) and handle incoming SelectionRequest events

If XFixes is unavailable, garclip falls back to polling at poll_interval_ms (default 250ms).

Content Negotiation

The TransferManager requests TARGETS first, then picks the best available format. Priority: files (gnome-copied-files, text/uri-list) > images (image/png, jpeg, gif, webp, bmp) > text (UTF8_STRING, text/plain, STRING). Large transfers use the INCR protocol with 1MB chunks.

Content Filtering

Filter clipboard content by pattern or source window to avoid storing sensitive data:

• ignore_patterns - Regex patterns (case-insensitive) matched against text content
• ignore_classes - Window class substring matching (case-insensitive)
• min_length / max_length - Text size bounds (default 1 byte to 10MB)
• max_image_size - Image size limit (default 50MB)
• ignore_empty - Skip empty/whitespace-only content

Filters are applied before adding entries to history. File URIs are never filtered.

Reload filters without restart: garclipctl reload or kill -HUP $(pgrep garclip).

Image Support

garclip stores images in their original format. Supported X11 targets and MIME types:

Images are base64-encoded in the history JSON file. The max_image_size config limits stored image size (default 50MB).

File URI Support

Copied files (e.g., from a file manager) are stored as URI lists. garclip parses both text/uri-list and x-special/gnome-copied-files formats, preserving the cut/copy distinction.

Picker Interface

The garclip-picker renders a popup window using gartk's Cairo/Pango backend. It fetches the current history from the daemon, displays entries with content type indicators and pinned status, and supports real-time fuzzy filtering.

Rendering Pipeline

1. Clear background, draw rounded border (gartk_render)
2. Draw search input field with cursor
3. For each visible entry (scroll_offset to scroll_offset + max_visible):
   • Draw selection highlight if active
   • Draw pinned indicator (*) and content type icon
   • Draw preview text truncated to 100 chars
4. Blit to X11 window via graphics context

Window Properties