feat(cli): support /copy in remote sessions using OSC52

[ismellpillows]

Summary

/copy now works reliably over SSH/tmux/screen/WSL by emitting an OSC-52 clipboard sequence to the user’s local terminal. Local behavior is unchanged (still uses clipboardy). The implementation is UTF-8 safe, respects terminal payload limits, and handles multiplexer passthrough correctly.

Details

• Heuristics: Prefer OSC-52 when attached to a TTY and in SSH, tmux, screen, WSL, or Windows Terminal. Otherwise use clipboardy.
• TTY selection: Write to /dev/tty when available (avoids interleaving with piped stdout), else fall back to stdout, else stderr.
• Payload limits: Cap total sequence at 100,000 bytes → max 74,994 UTF-8 bytes for content. Truncate on UTF-8 boundaries before base64; trim base64 to a /4 boundary.
• tmux passthrough: Wrap in DCS and double ESC inside payload.
• screen passthrough: Wrap in DCS and chunk payload (conservative 240-byte chunks) to avoid truncation on older screen.
• Backpressure: Stream writes are drained before returning.
• Robustness: No behavior change to the CLI interface; /copy still copies the last message and takes no arguments. Prints a single warning if truncation occurs. No noisy logs otherwise.

Related Issues

Fixes #5244
Fixes #13354
Related to #9978
Replaces #5416
Replaces #9966

How to Validate

In all cases, generate a response, then run /copy and paste locally (⌘V/Ctrl+V). The pasted text should match the last message.

1. Local macOS/Linux/Windows (no SSH)

   • Run /copy.
   • Expect: system clipboard updated via clipboardy.

2. SSH → remote (no tmux)

   • From a local terminal that supports OSC-52 (iTerm2/Kitty/WezTerm/Windows Terminal/hterm/most Alacritty builds), SSH to a box and run /copy.
   • Expect: paste locally.
   • Note: iTerm2 may require enabling “Applications in terminal may access clipboard”.

3. SSH → remote inside tmux

   • tmux new -s test, run /copy.
   • Expect: paste locally (tmux passthrough verified).
   • Note: tmux 3.3+ requires adding setw -g allow-passthrough on to ~/.tmux.conf

4. SSH → remote inside screen

   • screen, run /copy.
   • Expect: paste locally (screen passthrough + chunking verified).

5. VS Code Integrated Terminal (Remote-SSH)

   • Open Remote-SSH terminal, run /copy.
   • Expect: paste locally (requires OSC-52 support in the terminal).

6. ChromeOS Secure Shell (hterm)

   • SSH from ChromeOS Secure Shell, run /copy.
   • Expect: paste on ChromeOS.

7. Windows Terminal / WSL

   • From Windows Terminal, SSH or run inside WSL; run /copy.
   • Expect: paste in Windows.

8. Piped stdout (ensure we don’t lose OSC)

   • Run the CLI with output piped (e.g., gemini ... | cat), then /copy.
   • Expect: paste locally (we write to /dev/tty).

9. Large payload

   • Copy a generated message >100kB.
   • Expect: clipboard contains truncated content; single stderr warning: “copied text truncated … bytes … OSC-52 limit.”

10. Non-TTY / dumb terminal

• In CI or TERM=dumb, run /copy.
• Expect: falls back to clipboardy (or no-op if unsupported by environment); no OSC emitted.

[gemini-code-assist]

Summary of Changes

Hello @ismellpillows, I'm Gemini Code Assist¹! 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 /copy command within the CLI by introducing robust support for OSC 52 escape sequences. This change enables seamless clipboard integration across a wide array of remote and multiplexed terminal environments, including SSH, tmux, and WSL, where direct clipboard access is typically challenging. The update intelligently detects the operating context, applies appropriate escape sequence wrapping and safety measures, and ensures a reliable user experience for copying text, while preserving existing local clipboard functionality.

Highlights

• OSC 52 Support for Remote Sessions: The /copy command now utilizes OSC 52 escape sequences to enable reliable clipboard functionality in remote environments such as SSH, tmux, GNU screen, WSL, and Windows Terminal, detecting these contexts via environment variables.
• Robust TTY Selection: The implementation prioritizes writing to /dev/tty to prevent escape sequences from corrupting piped stdout, falling back to process.stdout or process.stderr if /dev/tty is unavailable. Dedicated /dev/tty streams are properly closed to avoid file descriptor leaks.
• Payload Safety and Limits: OSC 52 sequences are capped at 100,000 bytes, with the actual UTF-8 data limited to approximately 75KB. Content is truncated on UTF-8 boundaries and base64 encoded, ensuring correctness and preventing terminal issues with large inputs.
• Multiplexer Passthrough: Specific handling is included for tmux (DCS passthrough, doubling ESC characters) and GNU screen (DCS wrapping, chunking payloads into 240-byte segments) to ensure maximum compatibility and avoid historical truncation issues.
• Stream Correctness and Reliability: A new writeAll helper function is introduced to handle stream writes robustly, incorporating error handling and waiting for drain events to prevent partial writes under backpressure.
• Backwards-Compatible Fallback: When not in a remote or multiplexer environment, or if no TTY is available, the system gracefully falls back to using clipboardy for local clipboard operations, maintaining existing functionality.

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 👍 and 👎 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.

Footnotes

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. ↩

[gemini-code-assist]

Code Review

This pull request introduces OSC52 support for the /copy command, which is a great enhancement for users working in remote shells and terminal multiplexers. The implementation is thorough, considering various environments like SSH, tmux, screen, and WSL, and includes robust TTY handling and payload size management. I've found one area in the UTF-8 truncation logic that could be improved for correctness and efficiency. My feedback is detailed in the comment below.

[lutzky]

I think this replaces #9966 too, which was just closed.

[scidomino]

I tested this by running it locally in tmux and I couldn't get it to work. /copy didn't change my clipboard. Is there something I'm doing wrong?

[ismellpillows]

I tested this by running it locally in tmux and I couldn't get it to work. /copy didn't change my clipboard. Is there something I'm doing wrong?

Thanks! Some terminals may not support OSC52 or may require you to enable it. More likely, tmux 3.3+ requires adding setw -g allow-passthrough on to ~/.tmux.conf. Just added this information to the validation instructions.

[ismellpillows]

@scidomino Can you review this when you have a chance? Let me know if you need anything from me.

[scidomino]

@scidomino Can you review this when you have a chance? Let me know if you need anything from me.

@ismellpillows I approved but there is a merge conflict. Please resolve.

[scidomino]

Nevermind, I resolved it myself.