feat: Add clipboard image paste support for macOS

[jaysondasher]

TLDR

Adds clipboard image pasting functionality for macOS using Ctrl+V. Images are automatically saved as temporary files and inserted as @ commands with clean [Image #N] display formatting.

Detailed Discussion

This PR implements clipboard image paste support to address issue #1452. The feature allows users to paste images directly from their clipboard using Ctrl+V, making it easier to share screenshots and images with Gemini.

Key Features:

• Ctrl+V shortcut: Dedicated keyboard shortcut for pasting images (separate from text)
• Clean display: Shows [Image #1] instead of long file paths in the UI
• Sequential numbering: Images numbered per-message starting from 1
• Automatic cleanup: Old clipboard images removed after 1 hour
• macOS support: Uses AppleScript for reliable clipboard access

Technical Implementation:

• clipboardUtils.ts: Handles clipboard detection and image saving using AppleScript
• messageFormatting.ts: Formats display text to show clean image references
• Enhanced InputPrompt.tsx: Adds Ctrl+V handler and display formatting
• Updated UserMessage.tsx: Applies formatting to message history
• Images stored in .gemini-clipboard/ within project directory

Platform Support:

Currently macOS only due to AppleScript dependency. Future work could add Linux/Windows support using platform-specific clipboard APIs.

Reviewer Test Plan

1. On macOS: Copy an image to clipboard (screenshot, image from browser, etc.)
2. In Gemini CLI: Press Ctrl+V in the input field
3. Verify: Image appears as [Image #1] in both input field and message history
4. Test multiple images: Paste several images, verify sequential numbering [Image #1] [Image #2]
5. Test AI response: Send message with images, verify Gemini can read them
6. Test cleanup: Wait or manually check that old images are cleaned up

Testing Matrix

Platforms Tested:

• ✅ macOS (primary implementation)
• ❌ Windows (not supported yet)
• ❌ Linux (not supported yet)

Installation Methods Tested:

• ✅ npm run (development)
• ⚠️ npx (should work but not extensively tested)
• ❌ Docker (not tested)
• ❌ Podman (not tested)
• ❌ Seatbelt (not tested)

Fixes #1452

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[jacob314]

Thanks for the pull request @jaysondasher! I'll review as soon as you sign the CLA.

[jacob314]

Reviewing now.

[jacob314]

I'd suggest we don't include this in the placeholder unless @miguelsolorio has some good ideas of how to make this read well.

[jacob314]

remove this comment.

[jacob314]

this needs to factor in the cursor location. textBuffer has an existing helper for inserting text which you should use that will help with this.

[jacob314]

nit remove (like Claude Code). ctrl-v to paste is quite standard.

[jacob314]

Bugs: pressing the left arrow when over the 1[Image #1] text causes confusing autocomplete behavior make it feel like Gemini CLI hung. We should fix so that delete removes the entire [Image 1] tag and does not trigger autocomplete.

[jacob314]

can you use fileUtils.ts which has a detectFileType util that already detects images?

[jacob314]

this logic should move to text-buffer.ts and operate on the lines before wrapping.
lets also be sure to implement this in a way that we can support highlighting blocks like [Image 1] with custom colors in the future. I'd suggest we move these complex changes to a second PR and land this first just supporting paste that adds a user visible @some/path/to/image.png in the input prompt.

[jacob314]

moving to text-buffer.ts will also make it easy to test this as that part of the code base has reasonable unit tests.

[jaysondasher]

Thank you for your review, @jacob314.
I think my latest commit addresses all of your concerns.
Your concerns about the arrow key navigation bugs and complex delete behavior made me realize the display formatting was adding unnecessary complexity. By showing raw @.gemini-clipboard/... paths instead of [Image #N], we:

• Eliminate all the cursor mapping complexity
• Fix the arrow key navigation issues naturally
• Remove the need for special delete/backspace handling
• Avoid autocomplete triggering issues
• Make the code much simpler and more maintainable

The simplified approach works seamlessly with the existing @ command system and avoids all the edge cases you identified. Images still paste with Ctrl+V and Gemini can read them perfectly.

I will leave advanced formatting display of the pasted images for a later PR, with more time allowing for a more robust implementation.

[umairidris]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces clipboard image pasting functionality for macOS. A critical security vulnerability exists due to command injection in the AppleScript execution, and a functional issue limits support to only PNG images. The review includes a code suggestion addressing both issues by properly escaping the file path and using a more robust AppleScript.

[gemini-code-assist]

The tempFilePath is embedded directly into the AppleScript string without escaping, creating a command injection risk¹. If the path contains special characters (e.g., a double quote "), a maliciously crafted directory name could break out of the string and inject arbitrary AppleScript, leading to arbitrary code execution. Also, the current script only attempts to read PNG data (as «class PNGf»), but clipboardHasImage() checks for PNG, TIFF, and JPEG, creating an inconsistency where the feature will fail for common image formats like JPEG, even when clipboardHasImage() returns true². I recommend replacing the current implementation with a more robust approach that addresses both problems by using Image Events to handle various image formats and properly escaping the file path to mitigate the injection vulnerability.

    const tempFilePath = path.join(tempDir, `clipboard-${timestamp}.png`);
    const safeTempFilePath = tempFilePath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');

    // Use a more robust AppleScript with Image Events to handle various image types
    const script = `
      try
        tell application "Image Events"
          launch
          set this_image to (the clipboard as picture)
          save this_image as PNG in (POSIX file "${safeTempFilePath}")
        end tell
        return "success"
      on error
        return "error"
      end try
    `;

Style Guide References

Footnotes

1. Embedding user-controlled input directly into commands without proper escaping can lead to command injection vulnerabilities. ↩

2. The application should handle all image formats that it detects, to avoid unexpected failures. ↩

[jacob314]

Sorry for the slow reply. I missed a notification that you had replied. Code looks good now. Please add a basic test and then I will approve.
one note, please run the code formatter as there was a spurious whitespace diff on the commit that makes it look like it changes more than it does.

[jaysondasher]

@jacob314 I have added a basic test, run the code formatter, as well as improved the image type handling.

[jacob314]

why does mac return a string?

[jacob314]

sorry to be clear, please add tests for this logic added to InputPrompt then LGTM.

[jaysondasher]

@jacob314

1. Mac returns a string because saveClipboardImage() returns the file path on
   success (or null if no image/error). The test verifies it returns a valid path
   string.

2. Got it! I'll add tests for the InputPrompt clipboard logic. Thanks for
   clarifying!

[jaysondasher]

Added the InputPrompt tests. They cover:

• Ctrl+V with image in clipboard
• No image in clipboard (no-op)
• Image save failure handling
• Cursor position insertion with proper spacing
• Error handling during clipboard operations

All tests passing

[jacob314]

please avoid timeouts in tests as slow tests slow everyone down. Can you use
await wait(1) if a wait is really required for this to pass?

[jacob314]

comment applies to all wait calls added in the file

[jacob314]

avoid wait(100)

[jacob314]

remove this comment

[jacob314]

lgtm. Only small issue is to replace the wait(100) calls with wait(1) or better yet wait() calls in the tests

[jaysondasher]

@jacob314 I replaced all wait(100) calls with wait() and removed the outdated comment you highlighted above.

[jaysondasher]

@jacob314, I accidentally rebased against my own fork's main branch instead of upstream/main, which created duplicate commits in the history. I have successfully updated my branch with upstream/main and fixed merge conflicts. Ready for review!

[youaodu]

powershell -command "Add-Type -AssemblyName System.Windows.Forms; if ([System.Windows.Forms.Clipboard]::ContainsImage()) { Write-Output 'true' } else { Write-Output 'false' }"

This command can be used on the Windows platform to detect whether the clipboard contains an image, and it will return a result of either "true" or "false" after execution. Could the Windows platform be included in this submission as well? Thank you for your assistance.

[jaysondasher]

Thank you for the suggestion, @youaodu ! I've attempted to implement Windows support using the PowerShell command you provided. However, I wasn't able to get it working properly during testing on my Windows machine. I don't have much experience with Windows development or PowerShell, so I may be missing something obvious.

The implementation is in the latest commit if you'd like to review it. I'm happy to work with you to get this working if you can provide additional guidance, or feel free to make adjustments directly. The macOS implementation is working well and ready for review.

[youaodu]

Hi, thank you for adopting my suggestions @jaysondasher , but unfortunately, Windows may not be compatible with this function. Please delete the Windows - related code. After multiple tests and verifications, I found that in the terminal of the Windows platform, which is in text mode, when non - text formats are pasted, the terminal will automatically ignore this pasting event, which leads to the failure of this code to be triggered actively.

      // Ctrl+V for clipboard image paste
      if (key.ctrl && key.name === 'v') {
        console.error('[DEBUG] Ctrl+V detected in InputPrompt');
        handleClipboardImage();
        return;
      }

[youaodu]

One feasible approach is to poll and monitor changes in the clipboard. When a copied image is detected, it is automatically pasted into the inputPrompt box. However, this undermines user initiative, so I do not recommend it. I have implemented a version, and I can submit it if needed.

[jaysondasher]

Okay, @youaodu , I have reset the branch back to the commit before trying to implement the windows functionality. Feel free to implement your version for that. Not sure if that would be added manually by you to this PR, or if this PR will be approved for just the MacOS functionality, and you create a new PR for the windows functionality. Let me know what the best path forward is. This branch IS functional and ready to go for MacOS, though, I believe.

[youaodu]

Thank you for your contribution. I will add the shortcut key Alt+V based on yours, so that the function of pasting pictures from the clipboard can be realized in Windows.
#4107

[jacob314]

[scottdensmore]

Approved