Documentation

ClipChrono is installed once from the terminal and then lives in your menu bar forever. Everything below happens in the panel — you never need the command line again.

Getting started

Requirements: macOS and Node.js 22.12 or newer. The install downloads ClipChrono's Electron runtime (~100 MB) once.

The first run:

• puts the 📋 icon in your menu bar and registers a LaunchAgent so ClipChrono starts automatically at login
• walks you through a short welcome flow, including the Accessibility grant that powers auto-paste
• starts recording every copy — text, images, and files — into a local history of up to 500 items

In the Accessibility dialog the app appears as "Electron" — that is ClipChrono's runtime, not a stranger. Without the grant, clicking an item still puts it on your clipboard; with it, the click pastes directly into the app you came from.

The panel

Press ⌘⇧V in any app and the panel opens over your work.

Re-copying identical text never double-stacks: deduplication ignores invisible-whitespace differences, so one snippet is one entry no matter how often you copy it.

Smart clips

ClipChrono recognises what you copy and shows it accordingly. All detection is local — nothing is ever fetched or uploaded.

• 🔗 Links: a copied URL shows its domain, with a 🌐 open-in-browser button on the clip. Clicking the clip still pastes the full URL; the 🌐 button opens it in your browser.
• Code: multi-line snippets render in a monospace block with indentation and line breaks preserved, so a function still looks like a function when you find it again.
• Files: copy a file in Finder (⌘C) and it's captured as a reference — its icon and name appear in history, and clicking it pastes the actual file into Finder, an email, or an upload field. The file is never duplicated into ClipChrono; if you move or delete the original, the clip greys out and says so instead of pasting a stale copy.

Folders

The history is a stream — it caps at your configured size and can auto-expire unused items. Folders are for the clips you keep:

• File a clip: hover it → 📁 → pick a folder or create one on the spot (e.g. "CLI", or one per project)
• What filing does: the clip leaves the history stream and becomes permanent — exempt from the item cap, auto-expiry, and Clear
• Browse: switch between History and your folders with the dropdown next to search
• Manage: rename or delete a folder from its header. Deleting a folder deletes its clips — ClipChrono asks for confirmation first

Pins & multi-select

• 📌 Pin the items you paste every day — pins stay on top and survive Clear
• ⌘-click several items to select them, then delete them together
• Clear wipes the history stream in one go — pins and foldered clips are untouched

Settings & shortcuts

Open ⚙︎ Settings from the panel.

Backup & restore

Open ⚙︎ Settings → Backup. A backup is a single local file — there is no cloud involved.

• Export… writes your entire history, folders, pins, and stored images to one .zip you save wherever you like (default name ClipChrono-backup-YYYY-MM-DD.zip).
• Import… merges a backup into this Mac. Items already present are skipped, folders with the same name are combined, and nothing you already have is ever overwritten or deleted.
• Move to a new Mac: Export on the old one, copy the .zip across, Import on the new one. File clips are references, so they only paste where those files exist.

Privacy & storage

ClipChrono is local-only: no cloud, no sync, no telemetry, no account. Everything lives in one folder you can inspect, back up, or delete:

~/Library/Application Support/ClipChrono/
├── history.json     # the stream: text, link, code & file items + metadata
├── folders.json     # your folders and their clips
├── settings.json    # shortcut, cap, expiry, login item
└── images/          # copied images, stored as files

File clips store only a path — the file itself is never copied in. Backups you Export are separate .zip files saved wherever you choose; nothing is ever written here without your action.

Items copied from password managers that mark them confidential (1Password, Bitwarden and friends set a special pasteboard flag) are never recorded — they don't enter the history at all.

Updating

Then quit ClipChrono from Settings and run clipchrono once (or log out and back in). The LaunchAgent's paths self-heal across npm updates and folder moves, so start-at-login keeps working after every upgrade. See what changed in the changelog.

Troubleshooting

Uninstall

Quit ClipChrono from ⚙︎ Settings, then:

launchctl bootout gui/$(id -u)/com.clipchrono.agent
npm uninstall -g clipchrono
rm -rf ~/Library/Application\ Support/ClipChrono \
       ~/Library/LaunchAgents/com.clipchrono.agent.plist

That removes the app, the login item, and every stored clip. Nothing else was ever written anywhere.