feat(ui): add Windows clipboard image support and Alt+V paste workaround

[sgeraldes]

Summary

This PR adds Windows support for clipboard image pasting and introduces an alternative paste keybinding (Alt+V) to work around terminal interception issues. Previously, clipboard image functionality was only available on macOS, limiting Windows users from pasting images directly into the CLI.

Problem Statement

1. Missing Windows Support

• Clipboard image detection (clipboardHasImage()) and saving (saveClipboardImage()) only worked on macOS (darwin platform)
• Windows users could not paste images from clipboard, forcing them to save images to files manually first
• The platform check in clipboardUtils.ts:52 explicitly excluded Windows: if (process.platform !== 'darwin')

2. Terminal Keybinding Interception

• Modern terminals like Windows Terminal intercept Ctrl+V and convert it to a generic paste event
• This bypasses the application's custom clipboard handling logic that checks for images vs text
• Users had no alternative way to trigger the clipboard image detection flow

Solution

1. Windows Clipboard Integration

Implemented PowerShell-based clipboard access using .NET Framework APIs:

clipboardHasImage() implementation (clipboardUtils.ts:16-27):

Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.Clipboard]::ContainsImage()

• Uses System.Windows.Forms.Clipboard.ContainsImage() to detect images
• Returns boolean indicating presence of clipboard image

saveClipboardImage() implementation (clipboardUtils.ts:66-98):

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing
$image = [System.Windows.Forms.Clipboard]::GetImage()
$image.Save($path, [System.Drawing.Imaging.ImageFormat]::Png)

• Retrieves image using Clipboard.GetImage()
• Saves as PNG format to .gemini-clipboard/ directory
• Escapes backslashes in Windows paths for PowerShell string interpolation (path.replace(/\/g, '\\') at clipboardUtils.ts:69)
• Verifies file creation and non-zero size before returning path

2. Alternative Paste Keybinding

Added Alt+V (Command+V on Mac) to PASTE_CLIPBOARD command (keyBindings.ts:195-198):

[Command.PASTE_CLIPBOARD]: [
  { key: 'v', ctrl: true },   // Existing: Ctrl+V
  { key: 'v', command: true }, // New: Alt+V (Win) / Cmd+V (Mac)
],

Why this works:

• Alt+V is not commonly intercepted by terminal emulators
• Provides consistent behavior across terminals
• Maintains backward compatibility with Ctrl+V
• On macOS, command modifier (Cmd+V) also serves as an alternative

Technical Details

Platform Detection Flow:

1. Check if process.platform === 'win32' → Windows PowerShell path
2. Else check if process.platform === 'darwin' → macOS AppleScript path
3. Otherwise → return false/null (unsupported platform)

Error Handling:

• All clipboard operations wrapped in try-catch blocks
• PowerShell failures return false/null gracefully
• File system errors (permissions, disk full) handled silently
• Debug logging for troubleshooting (debugLogger.warn)

File Management:

• Images saved to .gemini-clipboard/ subdirectory within target directory
• Unique filenames: clipboard-{timestamp}.png
• Existing cleanup function cleanupOldClipboardImages() removes files older than 1 hour

Testing

Updated Test Suite (clipboardUtils.test.ts):

• Modified platform checks from darwin-only to darwin || win32
• Added 10-second timeout for Windows PowerShell calls (line 51)
• Tests verify:
  • Boolean return type on supported platforms
  • null return on unsupported platforms
  • Graceful error handling with invalid paths
  • No thrown exceptions

Manual Testing:

• ✅ Clipboard image paste on Windows 10/11 with PowerShell 5.1+
• ✅ Alt+V keybinding in Windows Terminal, ConEmu, and Command Prompt
• ✅ Backward compatibility with Ctrl+V on terminals that don't intercept it
• ✅ macOS clipboard functionality unchanged

Files Changed

• packages/cli/src/ui/utils/clipboardUtils.ts (+50 lines)
• packages/cli/src/config/keyBindings.ts (+3 lines)
• packages/cli/src/ui/utils/clipboardUtils.test.ts (+10/-24 lines)

Breaking Changes

None. This is a backward-compatible enhancement.

Alternative Approaches Considered

1. Node.js native clipboard modules: Rejected due to additional dependencies and potential compatibility issues
2. Electron clipboard API: Not applicable (CLI tool, not Electron app)
3. Different keybinding (Ctrl+Shift+V): Rejected because many terminals use this for paste-as-plain-text
4. Prompt user for workaround: Rejected as it degrades UX; automated solution preferred

Dependencies

• Windows: Requires PowerShell 5.0+ (ships with Windows 10+)
• macOS: No changes to existing osascript dependencies

Follow-up Work

• [ ] Consider adding Linux clipboard support (via xclip/wl-clipboard)
• [ ] Document the Alt+V keybinding in user-facing documentation
• [ ] Add telemetry to track clipboard image paste usage across platforms

---

This PR resolves the Windows clipboard limitation and improves the paste experience for users across all terminal emulators. The implementation is robust, well-tested, and maintains full backward compatibility.

[google-cla[bot]]

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.

[gemini-code-assist[bot]]

Summary of Changes

Hello @sgeraldes, I'm Gemini Code Assist[^1]! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the CLI's usability for Windows users by introducing native support for pasting images directly from the clipboard. It addresses the previous limitation where image pasting was exclusive to macOS and resolves issues with modern terminals intercepting standard paste commands. The changes provide a robust and consistent image pasting experience across supported platforms, improving workflow for users who frequently incorporate images.

Highlights

• Windows Clipboard Image Support: Implemented PowerShell-based clipboard access to enable image detection and saving on Windows, previously only available on macOS. This allows Windows users to paste images directly into the CLI.
• Alternative Paste Keybinding: Introduced Alt+V (or Cmd+V on Mac) as an alternative paste keybinding to bypass terminal interception of Ctrl+V, ensuring custom clipboard handling works reliably across various terminal emulators.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with :thumbsup: and :thumbsdown: on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

[^1]: Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

[sgeraldes]

Thanks for the detailed review and the fix commits! I've applied the changes:

• Added error logging in both Windows and macOS catch blocks
• Fixed the path escaping to escape single quotes instead of backslashes
• Added the new Windows path escaping test

Ready for another look when you have a chance!

[sgeraldes]

Rebased on latest main to resolve merge conflicts. All review feedback has been addressed and the PR is ready for another look!

[jacob314]

You will need to run the scripts to update documentation to reflect the keybindings. After that the tests should pass.

[jackwotherspoon]

@sgeraldes if you are able to run npm run docs:keybindings it should resolve things so we can get this awesome contribution merged in 😄

[jacob314]

Closing as I've landed this exact change with the trivial test fix in https://github.com/google-gemini/gemini-cli/pull/15218