maCopy/docs/GUIDE.md

maCopy — Install & Usage Guide

The single living reference for installing and using maCopy. Update this whenever a shortcut, setting, or behavior changes — this is the doc a new user (including future-you) should be able to follow start to finish without reading any source code.

Current version: see CHANGELOG.md. Feature backlog: ROADMAP.md.

---

1. Install

Option A — you already have a built DMG/app

1. Double-click the DMG, drag maCopy.app into Applications.
2. First launch: Gatekeeper will likely warn the app is unverified (it's ad-hoc signed, not notarized yet — see docs/SHARING.md). Right-click the app → Open → confirm.
3. macOS will prompt for Accessibility permission the first time you try to paste — this is required for auto-paste (Cmd+V simulation). System Settings → Privacy & Security → Accessibility → enable maCopy.
4. Look for the maCopy icon in the menu bar (top-right). No Dock icon — that's expected, it's a menu-bar-only app.

Option B — build it yourself

Requirements: macOS 10.15+, Rust 1.77+, Node 18+, Xcode Command Line Tools (xcode-select --install).

git clone gitea@git.levkin.ca:ilia/maCopy.git
cd maCopy
npm install
npm run tauri build
open src-tauri/target/release/bundle/macos/maCopy.app

Copy the resulting .app to /Applications if you want Launch at login to stick across rebuilds (see step 4 below).

First-run checklist

• App icon visible in the menu bar
• Accessibility permission granted (Settings → Privacy & Security → Accessibility)
• Global hotkey Ctrl+` opens/closes the picker
• (Optional) Settings → Launch at login turned on

---

2. Everyday usage

Opening the picker

Action	How
Open/close	Click the menu bar icon, or press Ctrl+`
Dismiss	Escape, or click outside the window

The hotkey is configurable — Settings → Global hotkey → click the field → press your new combo.

Pasting

Action	How
Paste an item into the app you were just using	Click it, or select + Enter
Paste plain (strip formatting)	⌥/Alt + click, or right-click → Paste plain
Paste with a transform	Right-click → Transform → pick one
Paste the Nth item directly (no picker needed)	Cmd+1 … Cmd+9 while picker is open
Copy to clipboard without auto-pasting	Right-click → Copy

Transforms (right-click → Transform): trim whitespace, UPPERCASE / lowercase / Title Case, collapse whitespace/newlines, pretty-print JSON, join to a single line. Transforms apply just before the paste — the saved history entry is never modified.

Selecting & managing history

Action	How
Multi-select	Cmd+Click to toggle one, Shift+Click/Shift+Arrow for a range, Cmd+A for all
Paste multiple selected items (joined with newlines)	Enter
Delete	Backspace/Delete with items selected, or right-click → Delete
Pin (keep forever, always on top)	Right-click → Pin / Unpin

On macOS, Control+click opens the context menu (same as right-click). Use Cmd+Click for multi-select — Control+click is not multi-select. | Search | Just start typing — instant full-text search |

What you'll see in the list

• Images show a small thumbnail; the full-resolution image stays in the database and is only loaded when you actually paste.
• Colors — an entry that's exactly a hex/rgb/hsl value (e.g. #3366ff) shows a small color chip next to it.
• Sensitive items (passwords, card numbers, banking details) show •• and a redacted preview in the list — the real value is still stored and still pastes correctly. See "Privacy" below.
• PIN badge — pinned items, always sorted to the top, never auto-trimmed.
• ⌘1–⌘9 badges on the first nine rows — quick-paste reference.

Settings panel

Menu bar icon → Settings…

Setting	What it does
Global hotkey	Re-bind the open/close shortcut
Show images	Toggle thumbnail rendering in the list (off = faster on huge histories)
Max history	1K / 5K / 10K / 50K entries kept before auto-trim (pinned items are exempt)
Window position	Near cursor, center, or a screen corner
Launch at login	Registers/unregisters a macOS Login Item — see docs/LAUNCH-AT-LOGIN.md
Pause monitoring	Tray menu checkbox — temporarily stop capturing new clipboard content

---

3. Privacy — what gets captured and how

• Whitespace-only clipboard content is ignored (never saved).
• Password/card/banking-looking text is detected and redacted in the list preview only — the real value is still in the database (needed so paste still works) and still pastes correctly.
• No network calls, no telemetry, no accounts. Everything lives in:

  ~/Library/Application Support/maCopy/clipboard.db
  

• You can pause monitoring any time from the tray menu.
• Full picture, including what's not yet implemented (encryption at rest, per-app exclusions): ROADMAP.md → "Privacy & trust".

---

4. Troubleshooting

Symptom	Fix
Hotkey does nothing	Settings → check it isn't a duplicate of a macOS shortcut (the old default Cmd+\`` conflicted with window-cycling — current default is `` Ctrl+ ``)
Paste doesn't happen (item copies but old app doesn't receive it)	Grant Accessibility permission — System Settings → Privacy & Security → Accessibility → add/enable maCopy
App won't open ("cannot verify developer")	Right-click → Open, or xattr -cr /Applications/maCopy.app — see docs/SHARING.md
Launch at login doesn't stick after rebuild	You're running a dev/rebuilt binary at a new path — install the .app under /Applications and re-toggle the setting
App feels slow / using lots of memory	Update to the latest build — see the performance notes in README.md; file it as a regression if it persists

---

5. Where things live (quick reference)

What	Path
App (after build)	src-tauri/target/release/bundle/macos/maCopy.app
Installer DMG	src-tauri/target/release/bundle/dmg/maCopy_<version>_aarch64.dmg
Your clipboard database	~/Library/Application Support/maCopy/clipboard.db
Source	this repo

Sharing the app with someone else: docs/SHARING.md. Full doc index: docs/README.md.