clippy

# Clippy 📎

[![Homebrew](https://img.shields.io/homebrew/v/clippy?color=FBB040)](https://formulae.brew.sh/formula/clippy)
[![Release](https://img.shields.io/github/v/release/neilberkman/clippy)](https://github.com/neilberkman/clippy/releases)
[![CI](https://github.com/neilberkman/clippy/actions/workflows/release.yml/badge.svg)](https://github.com/neilberkman/clippy/actions/workflows/release.yml)
[![Go Version](https://img.shields.io/github/go-mod/go-version/neilberkman/clippy)](https://go.dev/)
[![License](https://img.shields.io/github/license/neilberkman/clippy)](https://github.com/neilberkman/clippy/blob/main/LICENSE)

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:

```bash
# 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:**

```bash
brew install clippy
```

**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.

## Core Features

### 1. Smart File Copying

```bash
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

```bash
# 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

```bash
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

```bash
curl -sL https://example.com/image.jpg | clippy
cat archive.tar.gz | clippy
```

### 5. Copy and Paste Together

```bash
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

```bash
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.

```bash
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:

```bash
# Copy a Markdown draft first, then render the clipboard in place
clippy md2rich

# The former experimental name remains an alias
clippy md2rtf
```

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. Helpful Flags

```bash
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:**

```bash
# 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`):

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

### Metadata Overrides (Optional)

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

```bash
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**

```bash
# 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**

```bash
# 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**

```bash
# 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**

```bash
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.

**Important:** Draggy is a separate, optional tool. It's not automatically installed with cl