Using Ginkgo

Ginkgo requires macOS 14 or later. Both paths install the same app: once installed, Ginkgo settles into the menu bar and stays out of the Dock.

The one-line installer fetches the latest release, places Ginkgo into Applications, and launches it. curl downloads carry no quarantine attribute, so there is no Gatekeeper friction on first launch. To pin a version, prefix the command with GINKGO_VERSION=v0.1.2.

• Disk image: download Ginkgo.dmg from the official download page, open it, and drag Ginkgo into Applications.

Or install with Homebrew (same published version as the DMG and install script):

Upgrading from Clipmate: Ginkgo was previously named Clipmate. First launch migrates your old history once, safely; old self-writes stay suppressed. Settings do not migrate (a fresh defaults domain), so give them one pass.

Ginkgo lives in the menu bar—the ginkgo leaf at the top right of your screen. On launch, a larger card with the leaf and the name floats for about 1.5 seconds, then the History window opens so you can see where clips are saved. Click the card before the timer finishes to dismiss it without opening History. While the card is visible it never activates the app and never takes focus.

Left-click the leaf to open Quick Paste (same toggle as the global hotkey). Right-click for the menu of everyday actions:

• 「Open History…」 (⌘H): open the History window.
• 「Settings…」: open the Settings window (⌘, works too).
• 「Unlock Full Version…」: open the purchase page on this site.
• 「Quit Ginkgo」 (⌘Q): quit the app.

First launch also brings the one permission Ginkgo asks for: pasteboard access.

1. 01On macOS 15 and later, background clipboard reads are gated by the system's 「Paste from Other Apps」 control. At launch, Ginkgo shows a small guidance window to explain this.
2. 02Click 「Open System Settings…」 and turn Ginkgo on under System Settings › Privacy & Security › Pasteboard from Other Apps.
3. 03「Continue Anyway」 skips for now—but only after you allow it do copies flow into history automatically, with no relaunch needed.
4. 04On macOS 14 there is no such gate: nothing to do, and copies are already being recorded.

Press ⌘C in any app, and a small panel floats up in the bottom-right corner: the just-copied original on top (text, an image thumbnail, or Finder file names with image/PDF preview tiles), with the matched plugin's insight right below. Click an image or file preview tile to open it in the system Quick Look, zoomable. A single Finder image copy is treated like a screenshot image clip; a single PDF pastes as PDF bytes when you restore it. The panel activates no app and takes no keyboard focus—your typing goes exactly where it was.

At the same moment the menu-bar leaf bounces once to confirm the capture—same gate as the light layer—so you notice it even when the panel is off-screen or easy to miss. System Reduce Motion skips the bounce.

• Timestamp: a Unix timestamp or ISO 8601 date-time becomes readable at a glance.
• Dictionary: copy a headword and its meaning unfolds in place—lookups run on-device via Dictionary.app; choose English→Chinese or Chinese→English in Settings › Plugins › Dictionary.
• Certificate: a PEM certificate summarized—subject, issuer, validity, and fingerprint.
• JSON: payload pretty-printed with sorted keys.
• Anything unmatched is shown exactly as copied.

「Adopt」 writes the insight's result back to the clipboard. Until you adopt, the clipboard keeps your original—and dismissing the panel changes nothing.

The panel auto-dismisses after about 6 seconds; a new copy replaces the content and restarts the timer. A close button is always there, or swipe the panel right—it follows the cursor and flings off-screen on release, while a short, leftward, or vertical drag springs back.

Beside Adopt sits a camera button: it captures the result as a signed share card (next section). There is also 「Open in History」, which jumps straight to this clip.

The camera button captures the plugin's FULL result—not the panel's shortened preview: a dark, window-style card titled with the plugin name, signed 「Ginkgo」, written to the clipboard as a PNG, ready to paste into a chat.

A short original (such as the epoch number behind a timestamp) appears as a caption above the result.

Four card themes are picked in Settings › Share Card Theme: Evening Ginkgo (the default), Ginkgo Leaf, Autumn, and Paper. The next card any surface makes uses the new theme, and History's copy-as-image reads the same choice.

「Open History…」 (⌘H) in the menu bar opens a regular window (titled 「Ginkgo History」): the list on the left, the detail pane on the right, the split resizable, with the window's size and position kept across launches. Unlike the light layer, it takes keyboard focus normally—this is a management surface you opened on purpose.

• Browse: each row shows a kind icon or a 32 pt image/PDF preview tile for Finder file clips, the title, a relative timestamp, tags, and a pin marker; with the list focused, ↑/↓ move the selection. Detail shows a larger preview per image/PDF entry (click for Quick Look) plus name and path.
• Find: ⌘F focuses search—case-insensitive substring match over title, preview, and body; type and tag filters (any selected type / any selected tag) AND with search; clips copied while the window is open appear live.
• Detail: a row of actions under the title—pin, tags, delete, and the prominent 「Copy」; deletes confirm by name, and an undo bar offers ⌘Z to bring the clip back with its metadata and saved conversions.
• Organize: the pencil beside the title renames in place (Return saves, Esc cancels); tags attach and get created in a popover — each tag gets a color (random by default, optional swatch on create, changeable later in the popover); deleting a tag removes it from every clip after a confirmation (not undoable).
• Restore: 「Copy」 puts the original back through the same guarded writer the light layer uses—the restore write is never re-captured and never re-raises the layer.
• Agent: the sparkles control at the foot of the list column (beside the gear), or the global hotkey ⌘⇧A (default; Settings › Hot Keys), opens the reader window on its Agent tab—a global hub for licensed, configured installs. There is no Agent item in the status menu.
• Agent conversations: when the selected clip has bound agent conversations, the detail pane shows an 「Agent conversations」 section—one card per session (title and relative update time, newest first); a click opens that session in the reader's Agent tab.
• In-window keys: ⌘P toggles pin on the selection; ⇧⌘M merges a multi-selection (same confirm dialog as the batch Merge button); ⌘O opens the reader on the first text conversion (silent when there is none). ⌘⇧H (default global hotkey) also opens History from any app.

Type / at the detail foot, or click the dropdown button at the right of the field, and Ginkgo lists the enabled plugins that fit this clip; keep typing to narrow, Return or a click runs one. A success is saved on the record and still there when you reopen; conversions never write the clipboard and never add an extra row.

Base64 / URL transforms and MD5 / SHA-256 are listed for text clips and run only on demand—an encoder or hash would match nearly any text and crowd out the insight the content asks for.

Translate (/translate, requires macOS 26 or later): translates a text clip on this Mac with Apple's Translation framework. It never runs on copy.

• The target language is chosen at invocation, from ten languages: 简体中文, English, 日本語, 韩语, 法语, 德语, 西班牙语, 俄语, 葡萄牙语, 意大利语.
• Type to filter by Chinese name, English name, or code (ja finds Japanese), pick with ↑↓ or a click; a plain Return runs the pre-highlighted default—Settings › Plugins › Translate › Default target language (简体中文 on a fresh install).
• The source is detected automatically; a clip already in the target language, an undetectable source, or an unsupported pair shows a one-line hint and saves nothing.
• The result is saved as the record's conversion, titled 「source → target」; re-translating replaces the previous translation.
• Translation needs the pair's language packs: a missing pack points you to System Settings › General › Language & Region › Translation Languages (the download comes from Apple); below macOS 26 the command is not listed, and its Settings sub-page says 「Requires macOS 26 or later」.

Markdown (/markdown): turns a text clip or a copied .md / .markdown file into a self-contained styled HTML document. History shows an in-app rendered preview plus selectable HTML source, and 「Copy HTML」 writes through the guarded path with no new history row. Fenced mermaid blocks render as diagrams (bundled runtime, no network). Never runs on copy.

HTML (/html): renders HTML-looking plain text (or a copied .html / .htm file) as a safe in-app preview in History—sanitized, no content JavaScript, no remote fetches. Distinct from Format’s HTML pretty-print. Preview-focused (no 「Copy HTML」); never runs on copy.

Format (/format): pretty-prints a text clip on this Mac as one of JSON, JSONC, YAML, XML, JavaScript, TypeScript, HTML, or CSS. The language is picked in the command's second stage (JSON preselected; no auto-detection); a mismatched pick or a clip over ~250 KB shows a one-line hint and saves nothing, and everything formats locally through bundled engines—no network.

QR Code (/qr): turns a text clip into a scannable QR code PNG painted on a background you pick—four preset gradient backgrounds (Plain, Ginkgo, Ocean, and Sunset), or an uploaded custom image set in Settings › Plugins › QR Code (「Choose Image…」, applied live). Text that is too long shows a one-line hint and saves nothing. Never runs on copy.

Image (/image): on-demand transforms for an image clip—scale to 75% / 50% / 25%, or center-crop to 1:1 / 4:3 / 16:9. The original clip is never modified; re-running replaces the stored result.

OCR (/ocr): recognizes the text in an image clip on this Mac with Apple Vision—.accurate, Simplified/Traditional Chinese and English, no cloud—and saves it as the record's plain-text conversion, with 「Copy」 writing the recognized text through the guarded path. There is no second stage to pick (no parameter); an image with no readable text, or one still too large after the built-in downscale, shows a one-line hint and saves nothing. Never runs on copy.

Image conversions: a conversion's result can be a picture—the card shows it in place, and a click opens it in the system Quick Look to zoom (the detail's original image and the light layer's thumbnail open it the same way). The card's actions are 「Copy image」—written back through the guarded writer, never re-entering history—and remove. Image conversions never sync; they stay on the Mac that made them.

Agent (/agent, requires a license): runs a multi-step, tool-using AI agent on this clip with your own cloud model key (OpenAI, Anthropic, or any OpenAI-compatible endpoint—configured in Settings). It can read the clip (an image clip sends its picture to your configured provider), search history, read files the clip refers to, and fetch public web pages, with every gated call confirmed by a card before it happens; type a free-form instruction after the command to steer it. Never runs on copy, and saved runs carry their tool calls and sources into the reader.

Running the agent: answers stream in as they generate. On the light layer, the clip's preset chips start a run at a click; 「More…」 opens the reader's Agent tab on that clip (carrying any finished answer). In History, /agent runs in the detail pane; the list foot's sparkles opens the same Agent tab as a global hub. The tab is document-style: each turn reads top to bottom as your question, the steps the agent took (one quiet row per tool: what it did and exactly which URL, path, query, or clip), and the answer as it streams. Typing # (or full-width ＃) at the start of a word opens a searchable dropdown of history clips above the composer: ↑↓ to move, Return inserts #title (title plus one space), Esc closes—never while an IME composition is in progress. On send, referenced clips ride along as title + id only; the model reads them via read_history_clip, and exactly those cited ids skip this run's approval—every other id still asks. The multi-line composer sends on Return (Option- or Shift-Return breaks the line, an in-progress IME composition is never sent), and Esc stops the run—or denies a pending confirmation—without closing the reader window (Esc closes it only on a conversion tab).

Sessions: the left sidebar lists persisted conversations—click to switch, + for a new session without a clip anchor (a short hint until you type), hover a row to reveal delete (or use the context menu). Opening from a clip or /agent lands in (or creates) a session tied to that history row; 「Save as conversion」 on a finished answer writes to that clip. Only one agent run is active app-wide at a time.

Tool confirmations: each card names the tool, shows its complete arguments, and offers Deny, 「Always allow」 for exactly that scope (a domain for web fetches, otherwise the tool itself), and 「Allow once」. Allow once is the only prominent button and is deliberately never bound to Return—pressing Return on a confirmation does nothing, so a yes is always a deliberate click.

All saved conversions share one reader window: every open adds a tab, and opening an already-open conversion just selects its tab; with a single tab the window shows no tab chrome, and tabs are not restored across launches. Each tab keeps its own scroll position, Preview / Source choice, and copy feedback, while ⌘+ / ⌘− / ⌘0 zoom (80–200%) stays shared by the whole window; the Markdown preview and the card's copy actions work as before. ⌘W closes the current tab (the last tab closes the window), Esc closes the window, the context menu offers Close Others and Close to the Right, and removing a conversion or its clip closes only its own tab.

Open it from the app menu, the menu bar's 「Settings…」, or the gear at the foot of History's list column (⌘, works too): a fixed-size window whose content scrolls, where every choice applies live with no relaunch.

• Language: Follow System (the default; any zh preferred language resolves to Simplified Chinese, anything else to English), English, or 简体中文—menus, window titles, the light layer, and plugin insights all switch together.
• Appearance: Follow System (Ginkgo White in light, Ink Leaf in dark), Ginkgo White · Light, Ink Leaf · Dark—the light layer, launch splash, History, and Settings all follow.
• Updates: current version, Check for Updates, and when a newer build is available — Update, Later, or Skip This Version. The menu bar shows the same check / update row. Homebrew installs stay on brew upgrade --cask ginkgo and do not use in-app replace. Ad-hoc local builds may say they do not support in-app updates.
• Share Card Theme: a sub-page with live previews of the four themes; pick one directly (Back or Esc returns).
• Hot Keys: a sub-page listing the three global actions (Quick Paste, Open History, Open Agent) with their current glyphs—record a new combo, reset one row, or reset all. Changes apply live and persist; recording rejects bare keys, duplicates of Ginkgo's other global bindings, and system-reserved combos. The page notes that conflicts with other apps cannot be detected, that ⌘S / ⌘C-style combos are allowed but collide with common menus, and that Accessibility may need re-granting after each app update.
• Plugins: a row shows how many are on; the page lists every plugin as a card in priority order—name, one-line description, and for external packages an 「External」 badge with the package version—each with an inline switch that applies at once and persists. The card order IS the match priority: right-click a card to move it up, down, or to the top. Most clip plugins ship as first-party .ginkgoplugin bundles synced from the app on launch; Markdown, HTML preview, Agent, QR Code, and Image stay built in. A card opens a detail page with the 「Enabled」 toggle, the description, and its settings (Translate's 「Default target language」, Auto-cleanup's 「Retention days」, QR Code's default background and custom image, and the licensed Agent's provider, base URL, model, and API key). Licensed installs also list the global plugin Auto-cleanup under its own header—hidden entirely on the free tier. This is the only place plugins are managed.
• External plugins: copy a .ginkgoplugin folder into ~/Library/Application Support/Ginkgo/Plugins/—no marketplace, no in-app installer—then press 「Rescan」 (the page footer also opens the folder and lists packages that were refused, with reasons). An external switch turns on only after you grant every capability its manifest declares; a grant is consent, not enforcement. Externals are free-tier, off by default, and never auto-update—a changed package keeps the old code until you relaunch, flagged with a hint.

Sync is the official end-to-end encrypted history plugin (dev.ginkgo.sync, hand-installed during author testing): history is sealed on your Mac before upload, and the service stores ciphertext only. Sync is sold separately from the app license and needs a subscription — Standard ($1.29/month or $9.99/year, 1 GB vault, attachments up to 10 MB) or Plus ($1.99/month or $19.99/year, 10 GB, up to 100 MB). Checkout ends on a website page that shows your subscription key once; you enter it when creating the vault.

1. 01In Settings › Sync, choose Create vault: set a passphrase (twice) and a device name, then paste your subscription key.
2. 02On another Mac, install the plugin and choose Join vault; generate a pairing code on an enrolled Mac (8 characters, one-time, 5 minutes) and type it in.
3. 03History then syncs in the background — on launch, every ~45 s while running, 5 s after local saves, and on wake. Sync Now and Cancel live on the same page.

• The passphrase wraps the vault key locally (Argon2id) and never leaves the Mac; losing it with no enrolled Mac remaining means the cloud copy is permanently unreadable — nobody can reset it.
• One subscription carries one live vault; rebinding the key to a new vault replaces the old one (it stops syncing and is deleted after 30 days; the same key can swap back within that window). A cancelled subscription stops syncing and starts the same countdown, shown in the app and on the web stats page.
• The plan's capacity caps attachment uploads only — records and deletes always push, so an over-quota vault can shrink itself. Over-limit attachments arrive marked unavailable while text keeps flowing.
• A Mac without an activated app license pulls at most the free tier's 200 clips; activating the license triggers a one-time full re-pull.
• Settings › Sync links to the private stats page (a one-time code signs you in): upload heatmap, totals, streak, storage composition, subscription state, and the billing portal.

The free tier is not a trial: copying, the light layer, and plugin insights are fully unlimited. Once history holds 200 clips, new copies stop being saved; everything already saved is kept forever, searchable and restorable—and deleting down below 200 re-opens intake automatically.

Unlimited history unlocks with a serial-number license: $3.99/year (an auto-renewing subscription) or $7.99 once, priced in USD and hosted by Dodo Payments. The serial arrives by email right after checkout, and one serial activates up to 2 devices.

1. 01Enter the serial under Settings › License and click 「Activate」; the first activation needs a connection, after that Ginkgo works offline.
2. 02The annual subscription renews with the same serial—each ~30-day silent revalidation pushes the license forward; on cancellation, expiry, or revocation the app falls back to the free tier and keeps every saved clip.
3. 03Lifetime is paid once and kept forever; gift keys last 14 days from activation.
4. 04Slots full? Open Settings › License on an old device and click 「Unbind This Device」 to free one (that Mac returns to the free tier), then activate on this one.

Three global hotkeys work in any frontmost app (defaults below; rebind in Settings › Hot Keys). Menu and window shortcuts still apply when Ginkgo is frontmost. Quitting Ginkgo stops every global hotkey.

Quick Paste is a Spotlight-style picker of recent clips (newest first; pin status does not reorder the list). It never activates Ginkgo: the front app keeps focus. Image clips and Finder image/PDF file clips show a thumbnail in the row—click the tile for Quick Look; Return or clicking the rest of the row pastes (a single PDF pastes PDF bytes). Type to filter; exclusive type pills sit under the search field (→ focuses the first pill and filters to that type immediately, further →/← move focus and filter together, ← from the first returns to search and clears the type filter). When the recent clips carry tags, a tag chip row sits under the pills: → from the last pill walks the chips and applies each focused chip as the sole tag filter (entering the row clears the type filter; ← from the first chip clears the tag filter and re-applies the last pill's type), while clicking chips toggles any set of tags — a row shows when it carries any selected tag. ↑↓ move the list, Return (or a click) pastes the selection, Esc closes. Filters reset every time you open the picker. Closing also happens if you click outside, if it resigns key, or if you press the Quick Paste hotkey again.

• Return writes the clip through the guarded pasteboard path (no new history row, no light layer), then simulates ⌘V into the app that was frontmost when the picker opened—provided macOS Accessibility is granted for Ginkgo.
• Without Accessibility, Return still updates the clipboard and shows a one-line hint; paste yourself with ⌘V. A bounded onboarding window can deep-link to System Settings › Privacy & Security › Accessibility (up to three auto-shows, or Not Now forever).
• Secure Input sessions (for example Terminal sudo password prompts) also keep the picker open with a hint and skip simulated paste.

Menus, History, and the conversion reader:

Most clip plugins (Timestamp, Dictionary, JSON, Translate, Format, OCR, and the text/hash transforms) ship as first-party .ginkgoplugin bundles inside the app—Ginkgo syncs them into ~/Library/Application Support/Ginkgo/Plugins/ on launch unless you uninstalled them (uninstall is confirmed in Settings). Markdown, HTML preview, Agent, QR Code, and Image stay built into the app. Official catalog plugins: opening Settings › Plugins fetches the catalog once per visit—with an empty search a Recommended section lists up to six uninstalled official plugins (most-downloaded first) and a search matches installed and uninstalled plugins together on one card layout; an installed plugin shows Update when the catalog has a newer version. Each artifact is verified (SHA-256 plus code signature) before quarantine is cleared and it lands in the plugins folder; first install turns the plugin on when no extra capability grants are required. Uninstall a package-backed plugin from its detail page (confirmed). Third-party bundles stay manual: copy the folder in and press Rescan. Each bundle is validated before any code runs; refusals show at the foot of the page with a typed reason.

1. 01Manual install (third-party bundles): copy YourPlugin.ginkgoplugin into the Plugins folder (Settings › Plugins › Open Plugins Folder, or the path above).
2. 02If you downloaded the bundle, remove quarantine yourself: xattr -dr com.apple.quarantine YourPlugin.ginkgoplugin—Ginkgo never strips it for packages you copy in by hand (marketplace installs clear it automatically after verification).
3. 03Rescan, grant every capability the manifest declares, then enable the switch. Grants are consent, not enforcement—Ginkgo cannot sandbox third-party code.

• All storage is local (Application Support); clip content never leaves this Mac unless you send it somewhere yourself.
• License calls: activation and silent revalidation go straight to Dodo Payments, carrying only the serial, the license instance id, and the device name—never clip content. A never-activated install makes zero licensing network calls until you open the Settings › Plugins page (update checks below may still run on Sparkle-capable builds).
• Apple translation language packs: downloaded by the system the first time a translation is used; Apple collects usage metrics (bundle id and language pair) but never the translated content. Dictionary lookups and translation otherwise run on-device—cloud translation APIs were deliberately not used.
• Plugin marketplace: opening the Settings › Plugins page fetches the official catalog once per visit (the Recommended section and search both read that snapshot—no request at launch or while typing), downloads the artifact when you Install or Update, and posts an anonymous install counter (plugin id and version only—never clip content); unactivated installs can use it too. The web catalog (/plugins) is browse-only and serves no downloads.
• User-initiated agent runs: the licensed, opt-in Agent plugin sends prompt content only to the cloud provider you configured with your own API key—the agent can now read image clips, and an image clip's pixels travel only inside a run you started, to that same provider, downscaled to at most 1568 px on the long side first—plus web pages the agent fetches when you approve a web_fetch call. The plugin makes no network calls until you enable it, configure a provider, and start a run, and its API key lives in the login Keychain—never in history, conversions, or share cards.
• In-app updates (Sparkle): release builds periodically fetch the public appcast and, when you choose Update, download the signed zip—never clip content; available without a license. Homebrew installs stay on brew upgrade and do not use Sparkle replace. Ad-hoc builds without update signing make no update requests.
• On macOS 15 and later, background pasteboard reads are gated by 「Paste from Other Apps」—see First launch.
• External plugins you enable are third-party code: clip text enters their process after you grant declared capabilities; any network or file use beyond that is outside Ginkgo's control—see External plugins.