Recallyx

A programmable clipboard for macOS — run script & AI pipelines on anything you copy.

Website · Download

What it is

macOS now has a basic built-in clipboard history. Recallyx is the layer on top of it. It keeps a fast, searchable history of everything you copy — text and images — on disk, and adds an actions layer that the system clipboard can't: small pipelines of script (bash) and AI steps that transform a clip and paste the result. Clean up some JSON, fix grammar, rewrite a selection, reshape data — then paste it right where you were. Select text anywhere (even in Chrome) and transform it in place.

Why it's different

Recallyx is the free, open-source (MIT), developer-first programmable clipboard for macOS — script and AI pipelines on anything you copy, with AI that can run entirely on your Mac.

• Programmable — chain bash and AI steps per clip. Most clipboard managers stop at history and snippets; Recallyx lets you build and run real transform pipelines on anything you copy.
• Multi-provider and local AI — AI steps run on OpenAI, Anthropic (Claude), Google Gemini, local Ollama, or on-device Apple Intelligence — pick the provider per step. Cloud providers use your own API key; Ollama and Apple on-device need no key and never leave your Mac, so you can run a fully private, offline setup.
• Free, open, and native — MIT-licensed, zero dependencies, a floating ⌘⇧V panel, no Electron.

The two hotkeys

• ⌘⇧V — open the history panel. Fuzzy-search your clips, ↑/↓ to select, ↵ pastes the selected clip into wherever you were, ⇥ opens its action menu, esc closes.
• ⌃⇧V — grab the current selection, push it to history, and open straight into its actions. Select text anywhere — including browsers like Chrome — transform it, paste the result in place.

Both are defaults, not fixtures: in Settings → General → Shortcuts, click a shortcut to record a new combo (applied immediately, no relaunch) or ✕ to disable it. The menu-bar items always show the current bindings.

A few more in the panel:

• Pin a clip to keep it at the top of your history — pinned clips are exempt from retention-cap eviction, so they stick around no matter how much you copy.
• ⌘1–9 quick-pastes the Nth clip in the history list, or quick-runs the Nth saved action in the action menu. Hold ⌘ to reveal the number badges on the rows.

Screenshots

⌘⇧V — fuzzy-search your clipboard history.

⇥ — run a script or AI action on the selected clip.

Actions

Press ⇥ on a clip to open its action menu. Built-in actions are Paste, Copy, and Delete (images also get Copy file path / Reveal in Finder). Below those are your saved actions and a Custom… entry:

• A saved action runs the clip's text through a pipeline of script (bash filter) and AI steps and pastes the result. Each AI step picks its own provider — OpenAI, Anthropic, Gemini, local Ollama, or on-device Apple Intelligence. Steps are reorderable and individually toggled.
• Custom… lets you type a one-off instruction that runs once and is then discarded.
• ⇥ again on a saved action lets you edit its steps for just this run (⇥ paginates the steps, ⌘↵ runs) without changing the saved action.

Image clips get vision actions too — built-in Extract text (OCR) and Describe image, runnable against a cloud provider or a local Ollama vision model (e.g. llava).

Recallyx ships with a developer action pack of built-in script transforms: URL encode/decode, Base64 encode/decode, Decode JWT, pretty-print/minify JSON, slugify, extract URLs, and remove whitespace. They run offline with no key.

Build and edit actions in Settings → Actions. Missing some of the built-ins (deleted one, or installed before they shipped)? Restore built-in actions re-adds the defaults you don't have.

Cloud AI steps (OpenAI / Anthropic / Gemini) need that provider's own API key in Settings → General (stored in the macOS Keychain). Ollama and Apple on-device need no key.

Privacy: your history stays local, on disk — never the cloud. With Ollama or Apple on-device AI, nothing your clips touch ever needs to leave your Mac. The Capture sensitive data toggle (Settings → General) is off by default, so Recallyx honors org.nspasteboard.* hints and skips password-manager and transient clips. There's also an optional, off-by-default local usage journal (Settings → General) — it never records clip contents and is never sent anywhere.

Install

Requirements: macOS 13 (Ventura) or newer · Apple Silicon (arm64).

Grab the latest DMG from the Releases page, open it, and drag Recallyx.app onto Applications.

The DMG builds are ad-hoc signed (not yet notarized), so Gatekeeper blocks the first launch with "Apple could not verify Recallyx is free of malware." Clear the quarantine flag once, then open the app normally:

xattr -dr com.apple.quarantine /Applications/Recallyx.app

(On macOS 15 Sequoia and later, the old right-click → Open override no longer appears for un-notarized apps, so the xattr command is the reliable way in.)

Heads up on iCloud sync: the DMG (and the bundle.sh build below) is ad-hoc signed, which can't carry the CloudKit entitlement — so iCloud sync is unavailable in these builds: the Settings toggle is disabled and captioned, and the app never turns mirroring on there. Everything else works. Syncing your clipboard across Macs needs the team-signed Xcode build (below).

Building from source (team-signed, required for iCloud sync)

This is the primary build. iCloud sync (Settings → General → Sync via iCloud (text)) only runs in a team-signed build, because the CloudKit entitlement needs real signing — Apple's automatic signing (Xcode) provides it; the ad-hoc scripts can't.

Prerequisites

• Full Xcode (App Store) — not just the Command Line Tools. Launch it once to accept the license.
• XcodeGen: brew install xcodegen.
• An Apple ID signed into Xcode → Settings → Accounts.
• For sync specifically: an Apple Developer Program membership (a paid team). A free Apple ID can build and run the app, but automatic signing fails on the iCloud capability, so the CloudKit entitlement — and therefore sync — needs a paid team. Without one, use the ad-hoc path below and skip sync.

Setup (one-time)

cp Local.xcconfig.example Local.xcconfig   # then set DEVELOPMENT_TEAM to your Apple Developer team id
xcodegen generate                          # writes Recallyx.xcodeproj (gitignored)
open Recallyx.xcodeproj                     # once — let Xcode register the CloudKit capability

Local.xcconfig and the generated Recallyx.xcodeproj are gitignored — never commit your team id. Opening the project once lets Xcode's automatic signing provision the iCloud capability; the CLI does the same with -allowProvisioningUpdates (used by the script below), so the one-time open is optional if you prefer to stay on the command line.

Build + install (day to day)

./scripts/install-dev.sh          # team-signed Release build → ~/Applications, then relaunch
./scripts/install-dev.sh --build-only   # build only, no install/relaunch

install-dev.sh runs xcodegen generate then a signed xcodebuild (Release, -allowProvisioningUpdates), and installs the app — you never need to open the Xcode UI day to day.

Turn on sync: Settings → General → Sync via iCloud (text), then relaunch (the flag is read at launch). Do the same on your other Mac, signed into the same iCloud account — text clips sync both ways. Images stay local to each Mac.

All builds — the Development-signed Mac app and the TestFlight/App Store iOS app — use the CloudKit Production environment (set via the com.apple.developer.icloud-container-environment entitlement), so your dev Mac build syncs with the iPhone companion. Before the first Production sync you must deploy the container schema to Production once: CloudKit Console → the container → Deploy Schema Changes to Production. (Maintainers: adding a new synced field later needs the same deploy step again — ./scripts/install-dev.sh --ck-dev builds against Development so the field gets created there first; see CLAUDE.md.)

How sync interacts with retention: history deletions sync too — an explicit delete, Clear history, and retention-cap eviction all propagate to every synced device. That means the smallest retention cap among your synced Macs governs the whole fleet: lowering it on one Mac prunes older clips everywhere. Pinned clips are never evicted, on any device.

./scripts/test.sh   # unit tests

There's also an iPhone companion app in testing. scripts/testflight.sh archives and uploads it to TestFlight (--archive-only builds without uploading). It requires the paid team plus an Apple ID signed into Xcode → Settings → Accounts.

Alternative: the ad-hoc build (no Xcode, no Apple account)

If you don't need sync, the zero-cost path needs only the Command Line Tools (xcode-select --install) — no Xcode, no Apple account. This is also what CI ships as the DMG releases. It's ad-hoc signed, so iCloud sync is unavailable (the toggle is disabled); everything else works.

# one-time, per machine: a stable code-signing identity
./scripts/create-signing-identity.sh        # prints one `security add-trusted-cert …` to run yourself

# build + install (install.sh kills any running instance, then relaunches)
./scripts/bundle.sh && ./scripts/install.sh

The stable signing identity matters because ad-hoc signing produces a fresh signature on every rebuild, which makes macOS drop the Accessibility grant each time; a self-signed Recallyx Dev cert keeps the grant across rebuilds (Apple's recommendation).

For a quick compile check without any signing, the Xcode project also builds unsigned:

cp Local.xcconfig.example Local.xcconfig   # leave DEVELOPMENT_TEAM blank
xcodegen generate
xcodebuild -project Recallyx.xcodeproj -scheme Recallyx build CODE_SIGNING_ALLOWED=NO

Permissions

The clipboard history (⌘⇧V) works with no special permission. ⌃⇧V (grab selection + paste results) needs Accessibility: on first use the app shows an Open Settings alert → toggle Recallyx on under Privacy & Security → Accessibility → quit and relaunch (macOS reads the grant only at process start).

CLI

recallyx is a small command-line companion: search your clipboard history and run your saved action pipelines as unix filters, straight from the terminal. It reads the same history the menu-bar app records — strictly read-only, so it can never mutate or corrupt the app's database, and it reads fine while the app is running.

The CLI ships inside the app (at Recallyx.app/Contents/Helpers/recallyx), so there's nothing extra to build. Put it on your PATH one of two ways:

• Settings → General → Command-line tool → Install — symlinks it into /usr/local/bin/recallyx. (If that dir isn't writable it shows the ln -s command to run instead — no admin prompt.)

• Or by hand:

  ln -s /Applications/Recallyx.app/Contents/Helpers/recallyx /usr/local/bin/recallyx

Building from source instead? The CLI is also an SPM product:

swift build -c release --product recallyx-cli
ln -s "$(swift build -c release --product recallyx-cli --show-bin-path)/recallyx-cli" \
      /usr/local/bin/recallyx

recallyx search "api key" -n 5     # fuzzy-search history (index · kind · time · app · snippet)
recallyx recent -n 20              # most-recent clips
recallyx get 2 | pbcopy            # print the full text of the 2nd clip
echo '{"z":9,"a":1}' | recallyx run "Pretty-print JSON"   # pipe stdin through a saved action
recallyx get 1 | recallyx run "Fix grammar (EN)"          # chain them
recallyx list-actions              # names + SCRIPT/AI tags
git rev-parse HEAD | recallyx copy # set the clipboard (the app then captures it into history)

Notes:

• Script action steps run fully. AI steps need the app's Keychain access — from a separate binary macOS may prompt or deny; if the key can't be read, recallyx run prints a clear message pointing you back to the app instead of failing cryptically. When the key is readable it makes the real API call.
• Honors RECALLYX_DATA_DIR (same as the app), so you can point it at an isolated store.
• recallyx --help lists everything.

Troubleshooting

• A hotkey doesn't fire — another app may have grabbed the combo globally (Alfred / Raycast / etc.); the status menu shows an error when that happens at launch. Rebind it in Settings → General → Shortcuts, or quit the other app.
• "Accessibility permission missing" after granting it — macOS is holding a stale requirement (usually from an earlier ad-hoc build). Reset and re-grant:

  tccutil reset Accessibility io.github.macrosak.recallyx
  killall Recallyx && ./scripts/install.sh

• App blocked by Gatekeeper after replacing the bundle — re-run the xattr command above on the new Recallyx.app.

License

MIT — see LICENSE.