clipboard-daemon

name	clipboard-daemon
description	Set up and manage the clipboard-history background daemon. Use when configuring automatic clipboard capture, troubleshooting the daemon, or setting up auto-start on login. Triggers include "clipboard daemon", "auto-capture clipboard", "clp daemon", "start clipboard watcher", "daemon not running".

clipboard-daemon

Guide to running and managing the clipboard-history daemon.

How the Daemon Works

The daemon polls the system clipboard every 500ms. When the content changes, it computes a SHA-256 hash and saves the new content to the database if the hash differs from the last saved entry. Identical consecutive copies are stored only once.

Starting and Stopping

clp daemon start        # start in background
clp daemon stop         # send SIGTERM, wait for exit
clp daemon status       # check running state and uptime

Auto-Start on Login

macOS / zsh

Add to ~/.zshrc or ~/.zprofile:

clp daemon status > /dev/null 2>&1 || clp daemon start

Linux / bash

Add to ~/.bashrc or ~/.profile:

clp daemon status > /dev/null 2>&1 || clp daemon start

PID File

The daemon writes its PID to:

~/.local/share/clipboard-history/daemon.pid

The daemon stop command reads this file and sends SIGTERM. If the process is not running but the PID file exists, daemon start will overwrite it.

Daemon Status Output

When running:

  *   daemon running  (pid 12345)
  --  uptime: 3h 24m
  --  entries recorded: 142
  --  polling every 500ms

When not running:

  --  daemon not running
  --  start with: clp daemon start

Troubleshooting

Daemon stops unexpectedly - Check system memory. The daemon uses minimal memory but may be killed by the OS. Add auto-start to your shell profile.

Entries not being captured - Verify with clp daemon status. If not running, restart with clp daemon start.

High CPU usage - Unlikely at 500ms polling, but increase the interval: CLP_POLL_MS=2000 clp daemon start.

Stale PID file - If daemon start reports already running but the process is not alive, the PID file may be stale. Remove it: rm ~/.local/share/clipboard-history/daemon.pid, then start again.

Configuration

# Change polling interval (milliseconds)
CLP_POLL_MS=1000 clp daemon start

# Use custom database path
CLP_DB_PATH=/path/to/db.sqlite clp daemon start

# Enable debug logging (logs to stderr)
CLP_DEBUG=1 clp daemon start