Clipboard

Active contributors: aymanbagabas, meowgorithm

Purpose

Bubble Tea exposes the OSC 52 escape sequence as a pair of Cmds that read and write the system clipboard without requiring native OS bindings. OSC 52 is widely supported (xterm, iTerm2, kitty, alacritty, Windows Terminal, ghostty, tmux when configured) but not universal.

Writing

cmd := tea.SetClipboard("hello, world")

SetClipboard(s) (in clipboard.go) returns a Cmd that produces an internal setClipboardMsg. The runtime intercepts this in eventLoop and writes OSC 52 ; c ; <base64> via Program.execute.

For X11/Wayland's primary selection (the middle-click clipboard), use SetPrimaryClipboard(s) which targets OSC 52 ; p ; ….

Reading

return m, tea.ReadClipboard

ReadClipboard is a sentinel Cmd that asks the terminal for its clipboard contents. The reply arrives as a ClipboardMsg:

case tea.ClipboardMsg:
    text := msg.Content
    sel := msg.Selection // 'c' for system, 'p' for primary

ReadPrimaryClipboard works the same way for the primary selection.

Caveats

• Permission: many terminals require explicit user approval before letting an application read the clipboard. iTerm2 prompts; xterm's disallowedWindowOps may block it entirely.
• Tmux: requires set -g set-clipboard on to forward OSC 52 to the host terminal.
• SSH: works as long as the underlying terminal multiplexer / server forwards escape sequences. There is no need for an X11 forwarding setup.
• Apple Terminal: writes work, reads do not — Apple Terminal does not respond to OSC 52 read queries.
• Size: terminals enforce per-write limits (often 100 KB). Large pastes silently fail in some terminals.

How it flows

sequenceDiagram
    participant U as Update
    participant L as eventLoop
    participant P as Program
    participant T as Terminal
    U->>L: tea.SetClipboard("text") returns Cmd
    L->>P: setClipboardMsg("text")
    P->>T: OSC 52 ; c ; base64("text")
    Note over T: User can paste anywhere
    U->>L: tea.ReadClipboard
    L->>P: readClipboardMsg{}
    P->>T: OSC 52 ; c ; ?
    T-->>P: OSC 52 ; c ; base64(...)
    P-->>U: ClipboardMsg{Content, Selection:'c'}

Related pages

• Commands — how command dispatch works.
• Input handling — OSC 52 replies are translated by the input layer.