Clipwell is split into a daemon that owns state and a set of thin clients that talk to it over a public API. Nothing reaches around the daemon.

System view

The daemon is the only writer of history. The picker, CLI, MCP server, and any third‑party client are all peers on the same REST/WS surface.

Capture pipeline

Every clipboard change flows through the same path before it reaches subscribers:

• Watcher is per‑OS behind IClipboardWatcher (Windows: a message‑only window + AddClipboardFormatListener; macOS/Linux: polling pbpaste/wl-paste/xclip).
• Store is a direct port of the original backend's SQLite schema, so existing history files keep working.
• Detectors (IClipDetector) classify items into url/email/color/path/code/ image/text and are the plugin seam for richer, personal types.
• Broadcast is an in‑process fan‑out hub shared by SSE and WebSocket.

Why a daemon, not one app

Keeping capture + storage + API in a long‑lived background process means the picker can be a stateless, pre‑warmed window that shows in single‑digit milliseconds, the CLI and MCP server need no storage logic of their own, and the same history is available to anything on the machine. See ADR‑0001 and ADR‑0003.

Sensitive-item reads

The picker uses the full local REST response so it can display and paste a flagged item. REST list and search also offer excludeSensitive=true for callers that must omit those items before result limits are applied. Both MCP transports use that filtered read path, and their get-text tools refuse flagged items. Aliases of flagged items are excluded with their content. This is an explicit MCP output rule; the local REST API remains a full history interface.