Claude-Utils 🚀

Cross-platform companion toolkit for Anthropic's Claude Code CLI, featuring seamless clipboard integration.

The Problem

Claude Code users cannot paste screenshots or images directly into the terminal using standard keyboard shortcuts (⌘V/Ctrl+V). Current workarounds require saving files and drag-dropping, breaking the keyboard-centric workflow.

The Solution

Claude-Utils provides a transparent clipboard bridge that:

• 🎯 Just Works™: Press ⌘V/Ctrl+V to paste anything into Claude Code
• 🖼️ Image Support: Automatically stages images and provides file paths
• 📋 Text Support: Handles text up to 64KB inline
• 🔐 Secure: Local-only with token authentication
• 🌍 Cross-Platform: macOS, Linux, and Windows support
• ✨ Watch Mode: Automatically converts copied images to paths for seamless pasting

Quick Start

Installation

# Install from crates.io (recommended)
cargo install claude-utils

# macOS via Homebrew
brew tap josharsh/homebrew-claude-utils
brew install claude-utils

# Build from source
git clone https://github.com/josharsh/claude-utils
cd claude-utils
cargo build --release

Basic Usage

Standard Mode

1. Start the daemon:

claude-utils start

2. Configure Claude Code and set token as shown
3. In Claude Code: "Analyze the image in my clipboard"

Watch Mode (Recommended) 🎯

1. Start with watch mode:

claude-utils start --watch

2. Copy any image (screenshot, etc.)
3. Image automatically saved to ~/Desktop/claude-paste.png
4. Press ⌘V in terminal → path appears!
5. Original image still available for other apps

The magic: When you copy an image, claude-utils:

• Saves it to a timestamped file
• Creates a symlink on your Desktop
• Sets clipboard to the file path (for terminal)
• Preserves original image (for other apps)

Features

Clipboard Bridge

• Automatic Detection: Detects content type (text/image)
• Smart Staging: Large content automatically saved to temp files
• Deduplication: Same content won't be staged twice
• Auto-Cleanup: Old files cleaned up after 15 minutes

MCP Server

• Full Model Context Protocol implementation
• JSON-RPC 2.0 compliant
• Server-Sent Events (SSE) support for real-time updates
• Tools: clipboard.get, clipboard.set

Security

• Runs on localhost only (127.0.0.1:3830)
• Token-based authentication
• Read-only by default (use --write flag for clipboard writes)
• Secure file permissions (0600 for tokens)

Advanced Usage

CLI Commands

# Start with watch mode (recommended!)
claude-utils start --watch

# Watch mode with custom options
claude-utils start --watch --symlink-dir ~/Documents --no-notifications

# Start with custom port
claude-utils start --port 8080

# Disable authentication (development only)
claude-utils start --no-auth

# Enable clipboard write operations
claude-utils start --write

# Custom staging directory
claude-utils start --staging-dir /path/to/staging

# Show authentication token
claude-utils token

# Quick clipboard operations
claude-utils clip get              # Get clipboard as JSON
claude-utils clip get --format text # Get as plain text
claude-utils clip paste            # Paste (outputs file path for images)

Watch Mode Options

--watch              # Enable clipboard watching
--symlink-dir PATH   # Where to create symlinks (default: ~/Desktop)
--no-dual-format     # Disable dual clipboard format (macOS)
--no-notifications   # Disable system notifications

MCP Integration

The server exposes these tools for Claude Code:

{
  "tools": [
    {
      "name": "clipboard.get",
      "description": "Get current clipboard content",
      "input_schema": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "enum": ["auto", "text", "image"]
          }
        }
      }
    },
    {
      "name": "clipboard.set",
      "description": "Set clipboard content (requires --write flag)",
      "input_schema": {
        "type": "object",
        "properties": {
          "type": {"type": "string"},
          "data": {"type": "string"}
        }
      }
    }
  ]
}

Architecture

Claude Code <---> MCP Client <---> claude-utils-clipd <---> System Clipboard
                     |                     |
                 JSON-RPC              File Staging
                  + SSE                    |
                                    /tmp/claude-utils/

Platform Notes

macOS

• Full support for text and images
• Uses native NSPasteboard API

Linux

• X11 and Wayland support (via arboard)
• May require xclip or wl-clipboard packages

Windows

• Native Win32 clipboard API
• WSL2 users: Bridges Windows clipboard to WSL

Building from Source

# Prerequisites
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/josharsh/claude-utils
cd claude-utils
cargo build --release

# Binary will be at ./target/release/claude-utils

Troubleshooting

"Authentication required" error

• Ensure CLAUDE_UTILS_TOKEN environment variable is set
• Check token with: claude-utils token

Images not pasting

• Check if daemon is running: curl http://localhost:3830/health
• Verify clipboard has image content: claude-utils clip get

Permission denied errors

• Ensure staging directory is writable
• Check file permissions on ~/.claude-utils/auth.token

Future Roadmap

• Terminal paste interception (the "magic" experience)
• Screenshot capture endpoint
• OCR capabilities
• Clipboard history
• Multi-agent orchestration support

Contributing

Contributions welcome! Please read our Contributing Guide.

License

MIT License - see LICENSE file.

Acknowledgments

Built with:

• arboard - Cross-platform clipboard
• axum - Web framework
• Model Context Protocol - MCP specification

Made with ❤️ for the Claude Code community