feat: Allow attaching images from clipboard when running prompts

[TheephopWS]

PR: Allow attaching images from clipboard when running prompts

Summary

Add feature to attach clipboard contents (images or text) when running one-shot prompts or interactive chat sessions, enabling users to quickly share screenshots or copied images, with automatic fallback to text if no image is present.

Changes

New clipboard module (llm/clipboard.py)

• get_clipboard_image() - Retrieves image data from clipboard as PNG bytes
• get_clipboard_text() - Retrieves text from clipboard
• resolve_clipboard() - Returns an Attachment for images or str for text
• ClipboardError exception for empty/inaccessible clipboard
• Platform-specific implementations:
  • Windows: PIL/ImageGrab or win32clipboard fallback
  • macOS: PIL/ImageGrab or pbpaste fallback
  • Linux: PIL/ImageGrab or xclip/xsel fallback

New -C/--clipboard flag for llm prompt command (llm/cli.py)

• Added --clipboard / -C flag to attach clipboard contents
• Images are added as attachments to the prompt
• Text content is prepended to the user's prompt (fallback behavior)
• Can be combined with other -a attachments

New !clipboard command for llm chat (llm/cli.py)

• Added !clipboard interactive command in chat mode
• Displays confirmation message when image is attached
• For text clipboard, prompts user for additional input to combine with

Import updates (llm/cli.py)

• Added import for ClipboardError and resolve_clipboard from clipboard module

Documentation

Updated docs/usage.md

• Added new section (usage-clipboard)= explaining clipboard attachment feature
• Examples for image attachment, text fallback, and combining with other attachments

Regenerated docs/help.md

• Auto-regenerated with cog to include new --clipboard option in help output

Tests

Added tests in tests/test_clipboard.py:

• TestResolveClipboard::test_resolve_clipboard_with_image - Image returns Attachment
• TestResolveClipboard::test_resolve_clipboard_with_text - Text fallback returns string
• TestResolveClipboard::test_resolve_clipboard_empty - Empty clipboard raises error
• TestResolveClipboard::test_resolve_clipboard_image_priority - Image takes priority over text
• TestClipboardCLI::test_prompt_with_clipboard_image - CLI with image in clipboard
• TestClipboardCLI::test_prompt_with_clipboard_text - CLI with text in clipboard
• TestClipboardCLI::test_prompt_with_clipboard_empty - CLI with empty clipboard
• TestClipboardCLI::test_prompt_clipboard_with_other_attachments - Combining -a and --clipboard
• TestClipboardCLI::test_prompt_short_flag - Testing -C short flag
• TestClipboardTextFallback::test_text_prepended_to_prompt - Text prepended correctly
• TestClipboardTextFallback::test_text_only_no_user_prompt - Text-only prompt works

Testing Results

Test 1: Attach image from clipboard

# Copy an image to clipboard (e.g., screenshot)
$ llm "describe this image" --clipboard -m gpt-4o
I can see a screenshot showing...

Test 2: Attach text from clipboard (fallback)

# Copy some text to clipboard
$ llm "summarize this" -C -m gpt-4o
Here's a summary of the copied text...

Test 3: Short flag works

$ llm "what is this?" -C -m gpt-4o

Test 4: Combine with file attachment

$ llm "compare these images" -a reference.jpg --clipboard -m gpt-4o
Comparing the two images...

Test 5: Empty clipboard error

# Clear clipboard first
$ llm "describe" --clipboard
Error: Clipboard is empty or contains unsupported content. Supported content types: images (PNG, JPEG, etc.) and text.

Test 6: Interactive chat with !clipboard

$ llm chat -m gpt-4o
Chatting with gpt-4o
Type 'exit' or 'quit' to exit
Type '!multi' to enter multiple lines, then '!end' to finish
Type '!edit' to open your default editor and modify the prompt
Type '!fragment <my_fragment> [<another_fragment> ...]' to insert one or more fragments
Type '!clipboard' to attach clipboard contents (image or text)
> !clipboard
Attached image from clipboard
> describe what you see
I can see...

Automated Test Results

tests/test_clipboard.py::TestResolveClipboard::test_resolve_clipboard_with_image PASSED
tests/test_clipboard.py::TestResolveClipboard::test_resolve_clipboard_with_text PASSED
tests/test_clipboard.py::TestResolveClipboard::test_resolve_clipboard_empty PASSED
tests/test_clipboard.py::TestResolveClipboard::test_resolve_clipboard_image_priority PASSED
tests/test_clipboard.py::TestClipboardCLI::test_prompt_with_clipboard_image PASSED
tests/test_clipboard.py::TestClipboardCLI::test_prompt_with_clipboard_text PASSED
tests/test_clipboard.py::TestClipboardCLI::test_prompt_with_clipboard_empty PASSED
tests/test_clipboard.py::TestClipboardCLI::test_prompt_clipboard_with_other_attachments PASSED
tests/test_clipboard.py::TestClipboardCLI::test_prompt_short_flag PASSED
tests/test_clipboard.py::TestClipboardTextFallback::test_text_prepended_to_prompt PASSED
tests/test_clipboard.py::TestClipboardTextFallback::test_text_only_no_user_prompt PASSED

Files Changed

 llm/clipboard.py
 llm/cli.py
 docs/usage.md
 docs/help.md (auto-regenerated)
 tests/test_clipboard.py

Suggested Changelog Entry

• New -C/--clipboard flag for the prompt command allows attaching clipboard contents (images or text) directly to prompts. Use llm "describe this" --clipboard to attach a copied image, or use it with text in the clipboard to prepend copied text to your prompt. In chat mode, use the !clipboard command to attach clipboard content mid-conversation.

PR Plan Completion Check

• Manual Testing (Image attachment, Text fallback, Empty clipboard error, Interactive chat)
• Automated Tests (11 tests covering core functionality, CLI integration, edge cases)
• Documentation Updates (Usage guide and Help regenerated)

supports #1338