Claude Utils

Product Introduction

1. Claude Utils is a cross-platform companion toolkit designed to enhance interaction with Anthropic's Claude Code CLI through automated clipboard integration. It enables direct pasting of images and text into Claude Code using standard keyboard shortcuts (⌘V/Ctrl+V) without manual file handling. The tool operates as a background service that bridges system clipboard content with Claude Code's input requirements.
2. The core value lies in eliminating workflow interruptions caused by manual image/file management when using Claude Code. It provides a transparent bridge that automatically converts clipboard content into formats directly usable by Claude Code, maintaining a keyboard-centric workflow.

Main Features

1. Clipboard Bridge: Automatically detects clipboard content type (text or image) and stages it for Claude Code. Text under 64KB is injected inline, while images are saved to timestamped files in a staging directory (~/Desktop by default). The system preserves original clipboard content for use in other applications.
2. Watch Mode: Continuously monitors clipboard changes, instantly converting new images to symlinked paths for immediate pasting. Maintains a rotating cache of 15-minute-old files while creating persistent symlinks for active use. Integrates with native clipboard APIs (NSPasteboard on macOS, Win32 on Windows, X11/Wayland on Linux).
3. MCP Server: Implements the Model Context Protocol via JSON-RPC 2.0 on localhost:3830, providing secure tool exposure for Claude Code. Features include clipboard.get/set operations, Server-Sent Events (SSE) for real-time updates, and token-based authentication using HMAC-SHA256 signatures.

Problems Solved

1. Eliminates the need to manually save screenshots/images before analysis in Claude Code, addressing the workflow-breaking requirement of drag-and-drop file input. Removes context switching between image capture and CLI usage.
2. Targets technical users of Claude Code who frequently analyze visual data, including developers, data scientists, and AI researchers working with multimodal inputs. Particularly benefits users performing repetitive image analysis tasks.
3. Enables scenarios like instant paste of screenshots for debugging, bulk image processing through CLI pipelines, and real-time collaboration where multiple users feed visual data into shared Claude Code instances. Maintains terminal-based workflows while handling graphical content.

Unique Advantages

1. Native integration with Claude Code's MCP protocol distinguishes it from generic clipboard managers, providing structured tool definitions and secure JSON-RPC communication. Unlike OS-specific solutions, it offers cross-platform consistency with unified CLI commands.
2. Implements dual clipboard formats on macOS (NSFilenamesPboardType + public.file-url) to simultaneously provide file paths to Claude Code while preserving original image data for other applications. Uses inotify/Win32 hooks for low-latency clipboard monitoring without polling.
3. Combines security features (isolated localhost operation, 0600 file permissions, configurable token auth) with developer-friendly tools like auto-symlink management and staging directory cleanup. Outperforms web-based solutions through direct filesystem integration and CLI-native operation.

Frequently Asked Questions (FAQ)

1. How does authentication work between Claude Code and claude-utils? The tool generates an HMAC-SHA256 token stored in ~/.claude-utils/auth.token (0600 permissions) that must be set in Claude Code's environment variables. All MCP requests require X-Auth-Token header validation against this secret.
2. Can I use custom directories for staged files and symlinks? Yes, use --staging-dir to specify alternative storage locations and --symlink-dir to set custom symlink paths. Ensure both directories have proper write permissions and are excluded from system cleanup tools.
3. How does watch mode handle clipboard content from non-screenshot sources? The tool validates all clipboard images through MIME type checking (image/png, image/jpeg) and file signature verification. Non-image content is ignored unless using --write mode with explicit clipboard.set commands.
4. What happens to staged files after 15 minutes? The auto-cleanup daemon removes files older than 15 minutes from the staging directory while maintaining active symlinks. Persistent storage requires manual file movement or CLI integration with --no-cleanup flag during startup.
5. Is WSL2 on Windows supported? Yes, the Windows version bridges WSL2 environments by accessing the host OS clipboard via interop. Ensure Windows 10 build 19040+ with wsl --update and configure WSLg for X11 forwarding if using Linux GUI apps.