clipboard-daemon

# 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

```bash
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`:

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

### Linux / bash

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

```bash
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

```bash
# 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
```