Agent clipboard API

Agent clipboard API

Since 2.8.0.

AI coding agents (Claude Code and others) can leave values in your clipboard history with a label and a note, and manage history items the way you do. Typical use: several agent sessions prepare SQL queries or shell commands for you. Each value carries the session it came from and where to run it, so you don't have to guess which clip is which.

For Claude Code, install the maccyplus-clipboard plugin. It teaches Claude when and how to use everything below:

/plugin marketplace add roypadina/padina-claude-code-plugins
/plugin install maccyplus-clipboard@padina

What you see

• Label: a chip at the start of the row.
• Note: on hover, and in the preview pane together with the label.
• Search: the popup search also matches labels and notes. Type a session name to see only its values.

Labels and notes stay on the item when it is copied again.

Commands

MaccyPlus must be running. The CLI hands each request to the app and prints its JSON answer.

BIN=/Applications/MaccyPlus.app/Contents/MacOS/MaccyPlus

"$BIN" history list [--limit N] [--label L] [--search Q] [--pinned] [--full]
"$BIN" history get <id>
"$BIN" history add [--text T | stdin] [--label L] [--note N] [--pin] [--copy]
"$BIN" history update <id> [--label L] [--note N]     # "" clears
"$BIN" history pin <id>      | unpin <id>
"$BIN" history top <id>      # move to the top of history
"$BIN" history copy <id>     # make it the live clipboard, like selecting it
"$BIN" history delete <id>

• add puts the value at the top of history without touching the live clipboard, so parallel agents never overwrite what you are copying. --copy also puts it on the clipboard.
• Pass multi-line values on stdin: "$BIN" history add --label x <<'EOF' … EOF.
• Labels are one line, at most 60 characters. Put detail in the note.
• list is newest first, 20 items by default. Text is cut at 500 characters unless --full. --label and --search are case-insensitive substring filters. --search also matches labels and notes.
• Item JSON: id, index, kind (text|image|file), title, text, label, note, pin, app, copies, firstCopiedAt, lastCopiedAt. Ids are stable, including when the value is copied again.
• Exit codes: 0 ok, 1 error (message on stderr), 2 MaccyPlus is not running.
• There is no clear command, on purpose.

Privacy

Any process running as you can read your clipboard history through this CLI. That was already true through pbpaste and the app's database file, so the CLI adds no new access. For Claude Code, the Bash permission prompt is the gate. Values that password managers mark as concealed are never recorded, as before.

How it works

The CLI never opens the history database. It writes a request file into the app's sandbox container (~/Library/Containers/com.royp.MaccyPlus/Data/Library/Application Support/Maccy/agent-ipc/) and posts a distributed notification. The running app executes the command through the same code paths as the UI, then writes the response file back. Round trip: about 0.1 s.