Clippy

Clippy 📎

Copy files from your terminal that actually paste into GUI apps. No more switching to Finder.

macOS only - built specifically for the Mac clipboard system.

Why Clippy?

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.

Clippy bridges this gap by detecting what you want and using the right clipboard format:

# Copy files as references (paste into any GUI app)

clippy report.pdf # ⌘V into Slack/email - uploads the file clippy *.jpg # Multiple files at once

Pipe data as files

curl -sL https://picsum.photos/300 | clippy # Download → clipboard as file

Copy your most recent download (immediate)

clippy -r # Grabs the file you just downloaded clippy -r 3 # Copy 3 most recent downloads

Interactive picker for recent files

clippy -i # Choose from list of recent downloads clippy -i 5m # Show picker for last 5 minutes only

Stay in your terminal. Copy anything. Paste anywhere.

Installation:

brew install clippy

The Terminal-First Clipboard Suite: Clippy copies files to clipboard, includes an MCP server for AI assistants, Pasty pastes intelligently, and Draggy (optional GUI) bridges drag-and-drop workflows. Use as a Go library for custom integrations. All designed to minimize context switching from your terminal.

Core Features

1. Smart File Copying

clippy document.pdf    # Copies as file reference (paste into any app)

clippy notes.txt # Also copies as file reference clippy -t notes.txt # Use -t flag to copy text content instead clippy *.jpg # Multiple files at once

2. Recent Downloads

# Immediate copy (no UI)

clippy -r # Copy your most recent download clippy -r 3 # Copy 3 most recent downloads clippy -r 5m # Copy all downloads from last 5 minutes

Interactive picker

clippy -i # Choose from list of recent downloads clippy -i 3 # Show picker with 3 most recent files clippy -i 5m # Show picker for last 5 minutes only

Copy and paste in one step

clippy -r --paste # Copy most recent and paste here clippy -i --paste # Pick file, copy it, and paste here

3. Find Files with Spotlight

clippy -f invoice      # Search for files matching "invoice"

clippy -f screenshot # Find screenshots clippy -f .pdf # Find all PDF files (by extension) clippy -f report.xlsx # Find specific file "report.xlsx"

Shows interactive picker with results

No more switching to Finder to search for files - find and copy them directly from your terminal.

4. Pipe Data as Files

curl -sL https://example.com/image.jpg | clippy

cat archive.tar.gz | clippy

5. Copy and Paste Together

clippy ~/Downloads/report.pdf --paste  # Copy to clipboard AND paste here

clippy -r --paste # Copy recent download and paste here clippy -i --paste # Pick file, copy it, and paste here

6. Clear Clipboard

clippy --clear         # Empty the clipboard

echo -n | clippy # Also clears the clipboard

7. Content Type Detection

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.

echo '{"key": "value"}' | clippy          # Recognized as JSON

clippy -t page.html # Recognized as HTML clippy -t file.txt --mime application/json # Manual override when needed

8. Gmail-Ready Markdown Email

Copy Markdown, render it as rich email content, then paste normally into Gmail, Mimestream, Mail, or another rich composer:

clippy md2rich draft.md        # from a file

cat draft.md | clippy md2rich # from a pipe clippy md2rich # render the clipboard in place

The clipboard carries HTML, RTF, and plain-text representations together. Rich composers preserve intentional paragraph spacing, emphasis, links, lists, inline code, and Mimestream-style fenced code blocks; plain-text targets still receive a readable fallback.

9. Native Slack Messages

Write Markdown, then paste into any Slack composer and get real formatting — not literal asterisks:

clippy md2slack notes.md         # from a file

cat notes.md | clippy md2slack # from a pipe clippy md2slack # render the clipboard in place

Slack's composer stores messages as a Quill Delta document and puts that same document on the clipboard when you copy from it. md2slack writes exactly that format, so a normal Command-V produces bold, italic, strikethrough, inline code, code blocks, block quotes, headings, links, and bulleted or numbered lists (including nesting) — as though the message had been typed in Slack.

Slack has no table, image, or horizontal-rule construct, so tables become unaligned text rows, images become links, and rules become a divider line. Anything that does not understand the Slack format receives plain text.

For aligned columns, use space-padded text inside a fenced code block. Put both fences on their own lines, with real line breaks between the rows:

Current values:

  name   value

alpha 10 beta 20

````

Indentation inside a fence is preserved; it is not required to create a code block. Keep existing column padding when editing. Input uses CommonMark/GFM syntax (**bold**, ~~strikethrough~~), not Slack's mrkdwn syntax.

The copy_slack MCP tool returns formatting counts and warnings. Set expected_code_blocks: 1 for a message with one fenced table: a mismatch returns an error before changing the clipboard. preview: true reports the same counts and warnings without copying. clippy --verbose md2slack reports counts too, and the CLI always prints formatting warnings.

These counts describe generated formatting, not a verified Slack paste. Use normal Command-V. Plain-text clipboard reads omit formatting and fence markers, so they cannot verify code blocks. If the counts are correct but the paste is wrong, inspect the clipboard/paste path before changing the Markdown. The MCP tool and CLI use the same renderer.

10. Helpful Flags

clippy -v file.txt     # Show what happened

clippy --debug file.txt # Technical details for debugging

Why "Clippy"?

Because it's a helpful clipboard assistant that knows what you want to do! 📎

---

MCP Server

Clippy includes a built-in MCP (Model Context Protocol) server that lets AI assistants copy generated content directly to your clipboard.

Ask Claude to generate any text - code, emails, documents - and have it instantly available to paste anywhere:

• "Write a Python script to process CSV files and copy it to my clipboard"
• "Draft an email about the meeting and put it on my clipboard"
• "Generate that regex and copy it so I can paste into my editor"

No more manual selecting and copying from the chat interface.

For email drafts, the dedicated copy_email tool is advertised to the model. Prefer its explicit salutation, body_markdown, and signoff fields so the email structure is preserved without guessing at language-specific greetings. The complete-body markdown field remains available for compatibility. The tool only copies the draft; it does not address or send mail.

Setup

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"] } } }

Metadata Overrides (Optional)

You can customize MCP tool/prompt/example descriptions without changing behavior:

clippy mcp-server \

--tools /path/to/tools.json \ --prompts /path/to/prompts.json \ --examples /path/to/examples.json

By default, override files can be partial. Add --strict-metadata to require full coverage of every tool, prompt, and parameter.

Available Tools

System Clipboard Tools

• clipboard_copy - Copy text or files to system clipboard
• copy_email - Copy a structured email draft as Gmail-ready rich text (never sends)
• clipboard_paste - Paste clipboard content to files/directories
• get_recent_downloads - List recently downloaded files

Agent Buffer Tools

• buffer_copy - Copy file bytes (with optional line ranges) to agent's private buffer
• buffer_cut - Cut lines from file to buffer (copy and delete from source)
• buffer_paste - Paste bytes to file with append/insert/replace modes
• buffer_list - Show buffer metadata (lines, source file, range)

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.

---

Pasty - Intelligent Clipboard Pasting

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.

Core Use Cases

1. Copy file in Finder → Paste actual file in terminal

# 1. Copy any file in Finder (⌘C)

2. Switch to terminal and run:

pasty

File gets copied to your current directory (not just the filename!)

2. Smart text file handling

# Copy a text file in Finder (⌘C), then:

pasty # Outputs the file's text content to stdout pasty notes.txt # Saves the file's text content to notes.txt

3. Save browser images

# Right-click "Copy Image" in any browser, then:

pasty photo.png # Saves the image (auto-converts TIFF to PNG) pasty --preserve-format # Keep original format if needed

Also handles rich text with embedded images (.rtfd bundles from TextEdit/Notes).

4. Debugging and plain text extraction

pasty --inspect          # Show clipboard types + paste priority (metadata only)

pasty --plain notes.txt # Force plain text, strip all formatting pasty -f existing.txt # Overwrite existing files instead of creating duplicates

By default, pasty uses Finder-style duplicate naming if a file already exists.

---

Draggy - Visual Clipboard Companion

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.

**Import