garclip Implementation Plan

Overview

A bespoke X11 clipboard manager for the gardesk suite. Implements the X11 selection protocol directly using x11rb without any third-party clipboard crates. Supports clipboard history, PRIMARY/CLIPBOARD selections, and integrates with the gardesk ecosystem.

---

X11 Clipboard Protocol (The Bespoke Implementation)

How X11 Clipboard Works

X11 uses a selection ownership model - the clipboard doesn't store data. Instead:

1. When an app copies text, it becomes the selection owner
2. When another app wants to paste, it sends a SelectionRequest to the owner
3. The owner responds with SelectionNotify containing the data
4. Problem: When the owner app closes, clipboard data is lost

Clipboard Manager's Role

A clipboard manager solves this by:

1. Monitoring selection ownership changes
2. Grabbing clipboard contents before the owner releases
3. Becoming the new owner to persist the data
4. Responding to selection requests from other apps

Key X11 Atoms

CLIPBOARD          - Standard copy/paste selection
PRIMARY            - Middle-click paste (highlighted text)
TARGETS            - Query supported data formats
UTF8_STRING        - UTF-8 encoded text
STRING             - Latin-1 text (fallback)
TEXT               - Generic text
ATOM               - List of atoms
TIMESTAMP          - Selection timestamp
MULTIPLE           - Multiple target request
INCR               - Incremental transfer (large data)
CLIPBOARD_MANAGER  - Clipboard manager registration
SAVE_TARGETS       - Request to save clipboard

X11 Event Flow

┌─────────────────────────────────────────────────────────────────┐
│                    CLIPBOARD MONITORING                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. App copies text → SetSelectionOwner(CLIPBOARD)              │
│                       ↓                                         │
│  2. garclip receives SelectionClear (lost ownership)            │
│     OR detects new owner via polling                            │
│                       ↓                                         │
│  3. garclip requests content: ConvertSelection(CLIPBOARD)       │
│                       ↓                                         │
│  4. Owner sends SelectionNotify with data                       │
│                       ↓                                         │
│  5. garclip stores in history                                   │
│                       ↓                                         │
│  6. When owner closes → garclip becomes new owner               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    SERVING PASTE REQUESTS                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. App requests paste: ConvertSelection(CLIPBOARD, target)     │
│                       ↓                                         │
│  2. garclip receives SelectionRequest event                     │
│                       ↓                                         │
│  3. Check requested target (TARGETS, UTF8_STRING, etc.)         │
│                       ↓                                         │
│  4. Set property on requestor window with data                  │
│                       ↓                                         │
│  5. Send SelectionNotify to requestor                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Architecture

Project Structure

garclip/
├── Cargo.toml                    # Workspace definition
├── PLAN.md                       # This file
├── garclip/                      # Main daemon crate
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs               # Entry point, CLI parsing
│       ├── lib.rs                # Library exports
│       ├── error.rs              # Error types (thiserror)
│       │
│       ├── x11/                  # X11 clipboard implementation
│       │   ├── mod.rs
│       │   ├── atoms.rs          # Atom interning and caching
│       │   ├── selection.rs      # Selection ownership management
│       │   └── transfer.rs       # Data transfer (request/response)
│       │
│       ├── clipboard/            # Clipboard logic
│       │   ├── mod.rs
│       │   ├── manager.rs        # Main clipboard manager
│       │   ├── entry.rs          # Clipboard entry type
│       │   └── history.rs        # History storage
│       │
│       ├── daemon/               # Daemon infrastructure
│       │   ├── mod.rs
│       │   └── state.rs          # Daemon state machine
│       │
│       ├── ipc/                  # IPC layer
│       │   ├── mod.rs
│       │   ├── protocol.rs       # Command/Response/Event types
│       │   ├── server.rs         # Unix socket server
│       │   └── client.rs         # Client helpers
│       │
│       └── config/               # Configuration
│           ├── mod.rs
│           └── types.rs          # Config structs
│
└── garclipctl/                   # CLI control tool
    ├── Cargo.toml
    └── src/
        └── main.rs               # CLI commands

Core Types

// clipboard/entry.rs
pub struct ClipboardEntry {
    pub id: u64,                          // Unique ID
    pub content: ClipboardContent,        // The actual data
    pub source: Option<String>,           // Source application (if known)
    pub timestamp: SystemTime,            // When captured
    pub pinned: bool,                      // Pinned entries persist
}

pub enum ClipboardContent {
    Text(String),                         // UTF-8 text
    // Future: Image, Html, Files, etc.
}

// clipboard/history.rs
pub struct ClipboardHistory {
    entries: VecDeque<ClipboardEntry>,
    max_entries: usize,
    next_id: u64,
}

impl ClipboardHistory {
    pub fn push(&mut self, content: ClipboardContent, source: Option<String>);
    pub fn get(&self, id: u64) -> Option<&ClipboardEntry>;
    pub fn current(&self) -> Option<&ClipboardEntry>;
    pub fn list(&self, limit: usize) -> Vec<&ClipboardEntry>;
    pub fn remove(&mut self, id: u64) -> bool;
    pub fn clear(&mut self);
    pub fn pin(&mut self, id: u64) -> bool;
    pub fn unpin(&mut self, id: u64) -> bool;
}

X11 Selection Manager

// x11/selection.rs
pub struct SelectionManager {
    conn: Arc<RustConnection>,
    window: Window,                       // Our window for selection ownership
    atoms: Atoms,                         // Cached atoms
    owned_selections: HashSet<Atom>,      // Currently owned selections
}

impl SelectionManager {
    pub fn new(conn: Arc<RustConnection>) -> Result<Self>;

    // Ownership
    pub fn claim_ownership(&mut self, selection: Atom) -> Result<()>;
    pub fn release_ownership(&mut self, selection: Atom) -> Result<()>;
    pub fn is_owner(&self, selection: Atom) -> Result<bool>;

    // Requesting data from current owner
    pub fn request_targets(&self, selection: Atom) -> Result<Vec<Atom>>;
    pub fn request_text(&self, selection: Atom) -> Result<Option<String>>;

    // Handling incoming requests (when we're the owner)
    pub fn handle_selection_request(&self, event: SelectionRequestEvent, data: &[u8]) -> Result<()>;
    pub fn handle_selection_clear(&mut self, event: SelectionClearEvent);
}

// x11/atoms.rs
pub struct Atoms {
    pub clipboard: Atom,
    pub primary: Atom,
    pub targets: Atom,
    pub utf8_string: Atom,
    pub string: Atom,
    pub text: Atom,
    pub atom: Atom,
    pub timestamp: Atom,
    pub multiple: Atom,
    pub incr: Atom,
    pub clipboard_manager: Atom,
    pub save_targets: Atom,
    // Property atoms
    pub garclip_data: Atom,               // Our property for storing data
}

impl Atoms {
    pub fn intern(conn: &RustConnection) -> Result<Self>;
}

IPC Protocol

// ipc/protocol.rs

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "command", rename_all = "snake_case")]
pub enum Command {
    // Clipboard operations
    Copy { text: String },                 // Programmatic copy
    Paste,                                 // Get current clipboard

    // History operations
    History {
        limit: Option<usize>,              // Max entries to return (default: 50)
        #[serde(default)]
        include_pinned: bool,              // Include pinned entries
    },
    Select { id: u64 },                    // Select entry from history (makes it current)
    Delete { id: u64 },                    // Delete entry from history
    Clear,                                 // Clear clipboard
    ClearHistory { keep_pinned: bool },    // Clear all history

    // Pin management
    Pin { id: u64 },                       // Pin an entry
    Unpin { id: u64 },                     // Unpin an entry
    ListPinned,                            // List pinned entries

    // Search
    Search {
        query: String,
        limit: Option<usize>,
    },

    // Daemon control
    Status,                                // Get daemon status
    Reload,                                // Reload configuration
    Quit,                                  // Shutdown daemon

    // Subscriptions
    Subscribe { events: Vec<String> },     // Subscribe to events
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Response {
    pub success: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub data: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "event", rename_all = "snake_case")]
pub enum Event {
    ClipboardChanged {
        id: u64,
        preview: String,                   // First ~100 chars
        source: Option<String>,
    },
    HistoryCleared,
    EntryPinned { id: u64 },
    EntryUnpinned { id: u64 },
    EntryDeleted { id: u64 },
}

Configuration

# ~/.config/garclip/config.toml

[history]
max_entries = 1000                # Maximum history entries
persist = true                    # Persist history across restarts
persist_path = ""                 # Custom path (default: ~/.local/share/garclip/history.json)

[behavior]
watch_primary = true              # Also track PRIMARY selection (middle-click)
watch_clipboard = true            # Track CLIPBOARD selection (Ctrl+C)
deduplicate = true                # Don't add duplicate entries
ignore_empty = true               # Ignore empty clipboard
min_length = 1                    # Minimum text length to record
max_length = 1048576              # Maximum text length (1MB)

[filters]
# Regex patterns to ignore
ignore_patterns = [
    "^\\s*$",                     # Whitespace only
]
# Window classes to ignore
ignore_classes = [
    "keepassxc",                  # Password managers
    "1password",
]

[daemon]
socket_path = ""                  # Custom socket path (default: $XDG_RUNTIME_DIR/garclip.sock)
log_level = "info"                # Logging level

---

Implementation Phases

Phase 1: Foundation (Core X11 + Basic Daemon)

Goal: Get the daemon running and monitoring clipboard

1. Project scaffolding

   • Create workspace structure
   • Set up Cargo.toml with dependencies
   • Basic error types

2. X11 atom management (x11/atoms.rs)

   • Intern all required atoms
   • Atom caching

3. Selection ownership (x11/selection.rs)

   • Create hidden window for selection
   • Claim/release ownership
   • Check current owner

4. Basic clipboard read (x11/transfer.rs)

   • Request TARGETS from owner
   • Request UTF8_STRING/STRING data
   • Handle SelectionNotify response

5. Daemon skeleton (daemon/state.rs)

   • X11 event loop
   • Detect clipboard changes
   • Log clipboard content

Deliverable: Daemon that prints clipboard changes to stdout

Phase 2: Clipboard Manager (Persistence + History)

Goal: Persist clipboard data and maintain history

1. Clipboard entry types (clipboard/entry.rs)

   • ClipboardEntry struct
   • ClipboardContent enum

2. History storage (clipboard/history.rs)

   • In-memory VecDeque
   • Push/get/list/remove operations
   • Deduplication

3. Selection serving (x11/transfer.rs)

   • Handle SelectionRequest events
   • Respond with stored data
   • TARGETS response

4. Become clipboard owner

   • Take ownership when original owner releases
   • Serve clipboard content to requestors

5. Persistence (clipboard/history.rs)

   • Save history to JSON file
   • Load on startup

Deliverable: Daemon that persists clipboard across app closes

Phase 3: IPC Layer

Goal: Control daemon via Unix socket

1. Protocol types (ipc/protocol.rs)

   • Command, Response, Event enums
   • Serde serialization

2. IPC server (ipc/server.rs)

   • Unix socket listener
   • Accept connections
   • JSON message handling

3. Command handlers (daemon/state.rs)

   • Implement all commands
   • Wire to clipboard manager

4. Event subscriptions

   • Track subscribed clients
   • Broadcast events

Deliverable: Daemon controllable via JSON over socket

Phase 4: CLI Tool (garclipctl)

Goal: User-friendly CLI interface

1. CLI structure

   • clap argument parsing
   • Subcommands for each operation

2. Commands

   • garclipctl paste - Print current clipboard
   • garclipctl copy <text> - Copy text
   • garclipctl history - List history
   • garclipctl select <id> - Select from history
   • garclipctl clear - Clear clipboard
   • garclipctl search <query> - Search history
   • garclipctl status - Show daemon status

3. Output formatting

   • Human-readable default
   • --json flag for scripting

Deliverable: Full CLI control tool

Phase 5: Configuration + Polish

Goal: Configurable and robust

1. Configuration loading

   • Parse TOML config
   • Defaults for all values
   • Config reload via IPC

2. Filtering

   • Ignore patterns
   • Ignore window classes

3. PRIMARY selection

   • Monitor PRIMARY in addition to CLIPBOARD
   • Configurable

4. Signal handling

   • SIGTERM graceful shutdown
   • SIGHUP config reload

5. Logging

   • tracing integration
   • Log file support

Deliverable: Production-ready clipboard manager

---

Dependencies

[dependencies]
# X11
x11rb = { version = "0.13", features = ["allow-unsafe-code"] }

# Async runtime
tokio = { version = "1", features = ["full", "signal"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
toml = "0.8"

# Error handling
thiserror = "2.0"
anyhow = "1.0"

# CLI
clap = { version = "4.5", features = ["derive"] }

# Utilities
dirs = "6.0"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
regex = "1.10"      # For ignore patterns

---

Key Implementation Details

Detecting Clipboard Changes

Two approaches:

1. Polling (simpler, works reliably)

   loop {
       let owner = conn.get_selection_owner(atoms.clipboard)?.reply()?.owner;
       if owner != last_owner && owner != our_window {
           // New owner - request content
           request_clipboard_content()?;
           last_owner = owner;
       }
       tokio::time::sleep(Duration::from_millis(100)).await;
   }
   

2. XFixes extension (more efficient, event-driven)

   // Request SelectionNotify events
   xfixes::select_selection_input(
       &conn,
       our_window,
       atoms.clipboard,
       xfixes::SelectionEventMask::SET_SELECTION_OWNER,
   )?;
   

Recommendation: Start with polling (simpler), add XFixes later if needed.

Requesting Clipboard Content

async fn request_text(&self, selection: Atom) -> Result<Option<String>> {
    // 1. Request conversion to our property
    self.conn.convert_selection(
        self.window,
        selection,
        self.atoms.utf8_string,
        self.atoms.garclip_data,
        x11rb::CURRENT_TIME,
    )?;
    self.conn.flush()?;

    // 2. Wait for SelectionNotify event
    let event = self.wait_for_selection_notify(selection).await?;

    if event.property == x11rb::NONE {
        return Ok(None); // Conversion failed
    }

    // 3. Read property data
    let reply = self.conn.get_property(
        true,  // Delete after reading
        self.window,
        self.atoms.garclip_data,
        self.atoms.utf8_string,
        0,
        u32::MAX / 4,
    )?.reply()?;

    Ok(Some(String::from_utf8_lossy(&reply.value).into_owned()))
}

Serving Clipboard Requests

fn handle_selection_request(&self, event: SelectionRequestEvent, data: &str) -> Result<()> {
    let target = event.target;
    let property = if event.property == x11rb::NONE {
        event.target  // Old clients
    } else {
        event.property
    };

    if target == self.atoms.targets {
        // Respond with supported targets
        let targets = [
            self.atoms.targets,
            self.atoms.utf8_string,
            self.atoms.string,
            self.atoms.timestamp,
        ];
        self.conn.change_property32(
            PropMode::REPLACE,
            event.requestor,
            property,
            self.atoms.atom,
            &targets.iter().map(|a| a.resource_id()).collect::<Vec<_>>(),
        )?;
    } else if target == self.atoms.utf8_string || target == self.atoms.string {
        // Respond with text
        self.conn.change_property8(
            PropMode::REPLACE,
            event.requestor,
            property,
            target,
            data.as_bytes(),
        )?;
    } else {
        // Unsupported target - send failure
        property = x11rb::NONE;
    }

    // Send SelectionNotify
    let notify = SelectionNotifyEvent {
        response_type: SELECTION_NOTIFY_EVENT,
        sequence: 0,
        time: event.time,
        requestor: event.requestor,
        selection: event.selection,
        target: event.target,
        property,
    };
    self.conn.send_event(false, event.requestor, EventMask::NO_EVENT, notify)?;
    self.conn.flush()?;

    Ok(())
}

---

Integration Points

With gar (Window Manager)

• Could query gar IPC for focused window class (for source tracking)
• Future: Workspace-aware clipboard history

With garlaunch

• garlaunch could have a clipboard history picker mode
• Or garclip could have its own popup (using gartk)

---

Testing Strategy

1. Unit tests

   • History operations
   • Config parsing
   • IPC protocol serialization

2. Integration tests (Xephyr)

   Xephyr -br -ac -noreset -screen 1280x720 :1 &
   DISPLAY=:1 cargo run --bin garclip -- daemon
   DISPLAY=:1 garclipctl status
   

3. Manual testing

   • Copy in various apps
   • Close source app, verify paste works
   • History persistence across daemon restart

---

Progress & TODO

Phase 1: Foundation (COMPLETE)

• Project scaffolding (workspace, Cargo.toml)
• Error types
• X11 atom interning
• Selection ownership management
• Data transfer (request/response)
• Clipboard entry types (text + images)
• History storage with persistence
• Clipboard manager
• Configuration (TOML)
• IPC protocol (JSON over Unix socket)
• IPC server/client
• Daemon state machine
• CLI entry point
• garclipctl control tool

Phase 2: Daemon Command Handler (COMPLETE)

• Refactor client handler to use channels for daemon state access
• Proper async message passing between IPC and daemon loop
• Handle all commands through the daemon via CommandRequest + oneshot
• Handle Quit command for graceful shutdown
• Handle Subscribe for event streaming to clients

Phase 3: Selection Monitoring (COMPLETE)

• XFixes extension for event-driven clipboard monitoring
• Claim ownership when original owner releases
• Reduce polling overhead

Phase 4: Filtering

• Regex patterns to ignore content
• Window class filtering (ignore password managers, etc.)
• Configurable min/max content length enforcement

Phase 5: Signals & Lifecycle

• SIGHUP for config reload
• Graceful SIGTERM handling
• PID file for single-instance enforcement

Phase 6: Integration

• Query gar IPC for focused window class (source tracking)
• Optional garlaunch integration for history picker UI
• Systemd user service file

---

Open Questions

1. Encryption - Should sensitive clipboard data be encrypted at rest?

   • Recommendation: Optional, not in initial implementation

2. Popup UI - Should garclip have its own history picker UI, or rely on garlaunch?

   • Recommendation: Defer UI to later, CLI-first approach