Skip to content
Back to search

clippy

Unified clipboard tool for macOS that intelligently handles both text and file copying

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neilberkman--clippy/badge.svg)](/listings/neilberkman--clippy)

HTML

<a href="/listings/neilberkman--clippy"><img src="/api/listings/neilberkman--clippy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Claude Code:**

# Install for all your projects (recommended)
claude mcp add --scope user clippy $(which clippy) mcp-server

# Or for current project only
claude mcp add clippy $(which clippy) mcp-server

Note: `$(which clippy)` finds the clippy binary on your system. On Apple Silicon Macs this is typically `/opt/homebrew/bin/clippy`, on Intel Macs it's `/usr/local/bin/clippy`.

**Claude Desktop:**

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "clippy": {
      "command": "clippy",
      "args": ["mcp-server"]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 493 lines
  1. # Clippy 📎
  2. [![Homebrew](https://img.shields.io/homebrew/v/clippy?color=FBB040)](https://formulae.brew.sh/formula/clippy)
  3. [![Release](https://img.shields.io/github/v/release/neilberkman/clippy)](https://github.com/neilberkman/clippy/releases)
  4. [![CI](https://github.com/neilberkman/clippy/actions/workflows/release.yml/badge.svg)](https://github.com/neilberkman/clippy/actions/workflows/release.yml)
  5. [![Go Version](https://img.shields.io/github/go-mod/go-version/neilberkman/clippy)](https://go.dev/)
  6. [![License](https://img.shields.io/github/license/neilberkman/clippy)](https://github.com/neilberkman/clippy/blob/main/LICENSE)
  7. Copy files from your terminal that actually paste into GUI apps. No more switching to Finder.
  8. **macOS only** - built specifically for the Mac clipboard system.
  9. ## Why Clippy?
  10. `pbcopy` copies file _contents_, but GUI apps need file _references_. When you `pbcopy < image.png`, you can't paste it into Slack or email - those apps expect files, not raw bytes.
  11. Clippy bridges this gap by detecting what you want and using the right clipboard format:
  12. ```bash
  13. # Copy files as references (paste into any GUI app)
  14. clippy report.pdf # ⌘V into Slack/email - uploads the file
  15. clippy *.jpg # Multiple files at once
  16. # Pipe data as files
  17. curl -sL https://picsum.photos/300 | clippy # Download → clipboard as file
  18. # Copy your most recent download (immediate)
  19. clippy -r # Grabs the file you just downloaded
  20. clippy -r 3 # Copy 3 most recent downloads
  21. # Interactive picker for recent files
  22. clippy -i # Choose from list of recent downloads
  23. clippy -i 5m # Show picker for last 5 minutes only
  24. ```
  25. Stay in your terminal. Copy anything. Paste anywhere.
  26. **Installation:**
  27. ```bash
  28. brew install clippy
  29. ```
  30. **The Terminal-First Clipboard Suite:** [Clippy](#core-features) copies files to clipboard, includes an [MCP server](#mcp-server) for AI assistants, [Pasty](#pasty---intelligent-clipboard-pasting) pastes intelligently, and [Draggy](#draggy---visual-clipboard-companion) (optional GUI) bridges drag-and-drop workflows. Use as a [Go library](#library) for custom integrations. All designed to minimize context switching from your terminal.
  31. ## Core Features
  32. ### 1. Smart File Copying
  33. ```bash
  34. clippy document.pdf # Copies as file reference (paste into any app)
  35. clippy notes.txt # Also copies as file reference
  36. clippy -t notes.txt # Use -t flag to copy text content instead
  37. clippy *.jpg # Multiple files at once
  38. ```
  39. ### 2. Recent Downloads
  40. ```bash
  41. # Immediate copy (no UI)
  42. clippy -r # Copy your most recent download
  43. clippy -r 3 # Copy 3 most recent downloads
  44. clippy -r 5m # Copy all downloads from last 5 minutes
  45. # Interactive picker
  46. clippy -i # Choose from list of recent downloads
  47. clippy -i 3 # Show picker with 3 most recent files
  48. clippy -i 5m # Show picker for last 5 minutes only
  49. # Copy and paste in one step
  50. clippy -r --paste # Copy most recent and paste here
  51. clippy -i --paste # Pick file, copy it, and paste here
  52. ```
  53. ### 3. Find Files with Spotlight
  54. ```bash
  55. clippy -f invoice # Search for files matching "invoice"
  56. clippy -f screenshot # Find screenshots
  57. clippy -f .pdf # Find all PDF files (by extension)
  58. clippy -f report.xlsx # Find specific file "report.xlsx"
  59. # Shows interactive picker with results
  60. ```
  61. No more switching to Finder to search for files - find and copy them directly from your terminal.
  62. ### 4. Pipe Data as Files
  63. ```bash
  64. curl -sL https://example.com/image.jpg | clippy
  65. cat archive.tar.gz | clippy
  66. ```
  67. ### 5. Copy and Paste Together
  68. ```bash
  69. clippy ~/Downloads/report.pdf --paste # Copy to clipboard AND paste here
  70. clippy -r --paste # Copy recent download and paste here
  71. clippy -i --paste # Pick file, copy it, and paste here
  72. ```
  73. ### 6. Clear Clipboard
  74. ```bash
  75. clippy --clear # Empty the clipboard
  76. echo -n | clippy # Also clears the clipboard
  77. ```
  78. ### 7. Content Type Detection
  79. A nice bonus: clippy auto-detects content types (JSON, HTML, XML) so receiving apps handle them properly - something `pbcopy` can't do. This means when you paste into apps that support rich content, they'll handle it correctly - JSON viewers will syntax highlight, HTML will render, etc.
  80. ```bash
  81. echo '{"key": "value"}' | clippy # Recognized as JSON
  82. clippy -t page.html # Recognized as HTML
  83. clippy -t file.txt --mime application/json # Manual override when needed
  84. ```
  85. ### 8. Gmail-Ready Markdown Email
  86. Copy Markdown, render it as rich email content, then paste normally into Gmail,
  87. Mimestream, Mail, or another rich composer:
  88. ```bash
  89. clippy md2rich draft.md # from a file
  90. cat draft.md | clippy md2rich # from a pipe
  91. clippy md2rich # render the clipboard in place
  92. ```
  93. The clipboard carries HTML, RTF, and plain-text representations together. Rich
  94. composers preserve intentional paragraph spacing, emphasis, links, lists,
  95. inline code, and Mimestream-style fenced code blocks; plain-text targets still
  96. receive a readable fallback.
  97. ### 9. Native Slack Messages
  98. Write Markdown, then paste into any Slack composer and get real formatting —
  99. not literal asterisks:
  100. ```bash
  101. clippy md2slack notes.md # from a file
  102. cat notes.md | clippy md2slack # from a pipe
  103. clippy md2slack # render the clipboard in place
  104. ```
  105. Slack's composer stores messages as a Quill Delta document and puts that same
  106. document on the clipboard when you copy from it. `md2slack` writes exactly that
  107. format, so a normal Command-V produces bold, italic, strikethrough, inline
  108. code, code blocks, block quotes, headings, links, and bulleted or numbered
  109. lists (including nesting) — as though the message had been typed in Slack.
  110. Slack has no table, image, or horizontal-rule construct, so tables become
  111. unaligned text rows, images become links, and rules become a divider line.
  112. Anything that does not understand the Slack format receives plain text.
  113. For aligned columns, use space-padded text inside a fenced code block. Put
  114. both fences on their own lines, with real line breaks between the rows:
  115. ````markdown
  116. Current values:
  117. ```
  118. name value
  119. alpha 10
  120. beta 20
  121. ```
  122. ````
  123. Indentation inside a fence is preserved; it is not required to create a code
  124. block. Keep existing column padding when editing. Input uses CommonMark/GFM
  125. syntax (`**bold**`, `~~strikethrough~~`), not Slack's mrkdwn syntax.
  126. The `copy_slack` MCP tool returns `formatting` counts and `warnings`. Set
  127. `expected_code_blocks: 1` for a message with one fenced table: a mismatch
  128. returns an error before changing the clipboard. `preview: true` reports the
  129. same counts and warnings without copying. `clippy --verbose md2slack` reports
  130. counts too, and the CLI always prints formatting warnings.
  131. These counts describe generated formatting, not a verified Slack paste. Use
  132. normal Command-V. Plain-text clipboard reads omit formatting and fence markers,
  133. so they cannot verify code blocks. If the counts are correct but the paste
  134. is wrong, inspect the clipboard/paste path before changing the Markdown.
  135. The MCP tool and CLI use the same renderer.
  136. ### 10. Teams-Ready Markdown
  137. Render a message, then paste with Command-V into Microsoft Teams on macOS:
  138. ```bash
  139. clippy md2teams notes.md # from a file
  140. cat notes.md | clippy md2teams # from a pipe
  141. clippy md2teams # read Markdown from the clipboard
  142. ```
  143. `md2teams` uses the same formatting as `md2rich`, wrapped in a complete UTF-8
  144. HTML document. Teams on macOS renders a rich paste only when the HTML is a
  145. complete document and no plain text is offered. When plain text is offered,
  146. Teams falls back to it and shows raw text. Clippy therefore writes only HTML
  147. and RTF — no plain text. Successful copying does not verify how Teams renders
  148. the paste.
  149. Plain-text-only apps (Terminal, editors) therefore paste nothing.
  150. The clipboard no longer contains the Markdown source, so re-running `md2teams`
  151. on its own output finds no Markdown on the clipboard.
  152. Keep the source file for subsequent edits. The `copy_teams` MCP tool accepts
  153. the same CommonMark/GFM Markdown and only copies; it never sends or posts.
  154. ### 11. Helpful Flags
  155. ```bash
  156. clippy -v file.txt # Show what happened
  157. clippy --debug file.txt # Technical details for debugging
  158. ```
  159. ## Why "Clippy"?
  160. Because it's a helpful clipboard assistant that knows what you want to do! 📎
  161. ---
  162. ## MCP Server
  163. Clippy includes a built-in MCP (Model Context Protocol) server that lets AI assistants copy generated content directly to your clipboard.
  164. Ask Claude to generate any text - code, emails, documents - and have it instantly available to paste anywhere:
  165. - "Write a Python script to process CSV files and copy it to my clipboard"
  166. - "Draft an email about the meeting and put it on my clipboard"
  167. - "Generate that regex and copy it so I can paste into my editor"
  168. No more manual selecting and copying from the chat interface.
  169. For email drafts, the dedicated **copy_email** tool is advertised to the model.
  170. Prefer its explicit `salutation`, `body_markdown`, and `signoff` fields so the
  171. email structure is preserved without guessing at language-specific greetings.
  172. The complete-body `markdown` field remains available for compatibility. The
  173. tool only copies the draft; it does not address or send mail.
  174. ### Setup
  175. **Claude Code:**
  176. ```bash
  177. # Install for all your projects (recommended)
  178. claude mcp add --scope user clippy $(which clippy) mcp-server
  179. # Or for current project only
  180. claude mcp add clippy $(which clippy) mcp-server
  181. ```
  182. Note: `$(which clippy)` finds the clippy binary on your system. On Apple Silicon Macs this is typically `/opt/homebrew/bin/clippy`, on Intel Macs it's `/usr/local/bin/clippy`.
  183. **Claude Desktop:**
  184. Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  185. ```json
  186. {
  187. "mcpServers": {
  188. "clippy": {
  189. "command": "clippy",
  190. "args": ["mcp-server"]
  191. }
  192. }
  193. }
  194. ```
  195. ### Metadata Overrides (Optional)
  196. You can customize MCP tool/prompt/example descriptions without changing behavior:
  197. ```bash
  198. clippy mcp-server \
  199. --tools /path/to/tools.json \
  200. --prompts /path/to/prompts.json \
  201. --examples /path/to/examples.json
  202. ```
  203. By default, override files can be partial. Add `--strict-metadata` to require full coverage of every tool, prompt, and parameter.
  204. ### Available Tools
  205. #### System Clipboard Tools
  206. - **clipboard_copy** - Copy text or files to system clipboard
  207. - **copy_email** - Copy a structured email draft as Gmail-ready rich text (never sends)
  208. - **copy_teams** - Copy Markdown as Teams-ready HTML and RTF (never sends or posts)
  209. - **clipboard_paste** - Paste clipboard content to files/directories
  210. - **get_recent_downloads** - List recently downloaded files
  211. #### Agent Buffer Tools
  212. - **buffer_copy** - Copy file bytes (with optional line ranges) to agent's private buffer
  213. - **buffer_cut** - Cut lines from file to buffer (copy and delete from source)
  214. - **buffer_paste** - Paste bytes to file with append/insert/replace modes
  215. - **buffer_list** - Show buffer metadata (lines, source file, range)
  216. **Why buffer tools?** Solves the LLM "remember and re-emit" problem. The MCP server reads/writes file bytes directly - agents never generate tokens for copied content. Enables surgical refactoring (copy lines 17-32, paste to replace lines 5-8) with byte-for-byte accuracy, without touching your system clipboard.
  217. ---
  218. ## Pasty - Intelligent Clipboard Pasting
  219. When you copy a file in Finder and press ⌘V in terminal, you just get the filename as text. Pasty actually copies the file itself to your current directory.
  220. ### Core Use Cases
  221. **1. Copy file in Finder → Paste actual file in terminal**
  222. ```bash
  223. # 1. Copy any file in Finder (⌘C)
  224. # 2. Switch to terminal and run:
  225. pasty
  226. # File gets copied to your current directory (not just the filename!)
  227. ```
  228. **2. Smart text file handling**
  229. ```bash
  230. # Copy a text file in Finder (⌘C), then:
  231. pasty # Outputs the file's text content to stdout
  232. pasty notes.txt # Saves the file's text content to notes.txt
  233. ```
  234. **3. Save browser images**
  235. ```bash
  236. # Right-click "Copy Image" in any browser, then:
  237. pasty photo.png # Saves the image (auto-converts TIFF to PNG)
  238. pasty --preserve-format # Keep original format if needed
  239. ```
  240. Also handles rich text with embedded images (`.rtfd` bundles from TextEdit/Notes).
  241. **4. Debugging and plain text extraction**
  242. ```bash
  243. pasty --inspect # Show clipboard types + paste priority (metadata only)
  244. pasty --plain notes.txt # Force plain text, strip all formatting
  245. pasty -f existing.txt # Overwrite existing files instead of creating duplicates
  246. ```
  247. By default, pasty uses Finder-style duplicate naming if a file already exists.
  248. ---
  249. ## Draggy - Visual Clipboard Companion
  250. Draggy is a menu bar app that brings visual functionality to your clipboard workflow. While clippy handles copying from the terminal, Draggy provides a visual interface for dragging files to applications and viewing recent downloads.
  251. **Important:** Draggy is a separate, optional tool. It's not automatically installed with clippy.
  252. ### Features
  253. #### Core Functionality
  254. - **Drag & Drop Bridge** - Makes clipboard files draggable to web browsers, Slack, and other apps
  255. - **Recent Downloads Viewer** - Toggle between clipboard and recent downloads with one click
  256. - **File Thumbnails** - Visual previews for images and PDFs right in the file list
  257. - **Quick Preview** - Hold ⌥ Option while hovering to see larger previews
  258. - **Zero Background Activity** - No polling or battery drain, only activates on demand
  259. #### User Experience
  260. - **Double-Click to Open** - Quick access to files without leaving the menu
  261. - **Keyboard Shortcuts** - ESC to close, Space to refresh
  262. #### Design Philosophy
  263. - **Not a clipboard manager** - No history, no database, no complexity
  264. - **Terminal-first workflow** - Designed to complement terminal usage, not replace it
  265. - **Minimal but complete** - Every feature serves a specific workflow need
  266. ### Installation
  267. ```bash
  268. # Separate brew install (not included with clippy)
  269. brew install --cask neilberkman/clippy/draggy
  270. ```
  271. **⚠️ First Launch:** macOS may show a security warning since Draggy isn't code-signed. If you see "Draggy is damaged and can't be opened":
  272. - The Homebrew cask automatically removes the quarantine flag during installation
  273. - If the warning persists, run: `xattr -dr com.apple.quarantine /Applications/Draggy.app`
  274. - Or right-click Draggy.app and select "Open" to bypass Gatekeeper
  275. ### Usage
  276. ```bash
  277. # Copy files in terminal:
  278. clippy ~/Downloads/*.pdf # Copy PDFs with clippy
  279. curl -sL image.jpg | clippy # Pipe downloads to clipboard
  280. clippy -r # Copy most recent download
  281. # Use Draggy GUI:
  282. # 1. Click Draggy icon in menu bar
  283. # 2. Drag files to browser upload fields, Slack, etc.
  284. # 3. Toggle to Recent Downloads view with clock icon
  285. # 4. Hold ⌥ Option to preview files
  286. # 5. Double-click to open files
  287. ```
  288. ### Workflow Examples
  289. **Upload screenshots to GitHub:**
  290. ```bash
  291. # Take screenshot (macOS saves to Desktop)
  292. # In terminal: clippy ~/Desktop/Screenshot*.png
  293. # In Draggy: Drag to GitHub comment box
  294. ```
  295. **Quick file sharing:**
  296. ```bash
  297. # Terminal: clippy ~/Downloads/report.pdf
  298. # Draggy: Shows thumbnail, drag to Slack or email
  299. ```
  300. **Recent downloads workflow:**
  301. ```bash
  302. # Download file in browser
  303. # Click Draggy → Click clock icon → See your download
  304. # Drag where needed or double-click to open
  305. ```
  306. ### Philosophy
  307. Draggy is intentionally not a clipboard manager. No history, no search, no database. It's a visual bridge between your terminal clipboard workflow and GUI applications. For terminal users who occasionally need to see what's on their clipboard or drag files somewhere, then get back to work.
  308. ---
  309. ## Build from Source
  310. ```bash
  311. # Clone and build
  312. git clone https://github.com/neilberkman/clippy.git
  313. cd clippy
  314. go build -o clippy ./cmd/clippy
  315. go build -o pasty ./cmd/pasty
  316. sudo mv clippy pasty /usr/local/bin/
  317. # Or use go install
  318. go install github.com/neilberkman/clippy/cmd/clippy@latest
  319. go install github.com/neilberkman/clippy/cmd/pasty@latest
  320. ```
  321. ## Library
  322. [Clippy](#core-features) can be used as a Go library in your own applications:
  323. ```bash
  324. go get github.com/neilberkman/clippy
  325. ```
  326. ### High-Level API
  327. ```go
  328. import "github.com/neilberkman/clippy"
  329. // Smart copy - automatically detects text vs binary files
  330. err := clippy.Copy("document.pdf")
  331. // Copy multiple files as references
  332. err := clippy.CopyMultiple([]string{"image1.jpg", "image2.png"})
  333. // Copy text content
  334. err := clippy.CopyText("Hello, World!")
  335. // Copy data from reader (handles text/binary detection)
  336. reader := strings.NewReader("Some content")
  337. err := clippy.CopyData(reader)
  338. // Copy from stdin
  339. err := clippy.CopyData(os.Stdin)
  340. // Get clipboard content
  341. text, ok := clippy.GetText()
  342. files := clippy.GetFiles()
  343. ```
  344. ### Features
  345. - **Smart Detection**: Automatically determines whether to copy as file reference or text content
  346. - **Multiple Files**: Copy multiple files in one operation
  347. - **Reader Support**: Copy from any io.Reader with automatic format detection
  348. - **Clipboard Access**: Read current clipboard content (text or file paths)
  349. - **Cross-Platform Types**: Uses standard Go types, handles platform-specific clipboard internally
  350. ## License
  351. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.