Clipboard wrap

Why wrap exists

Copy inside a program is often an OSC 52 escape: the process prints a special sequence, and a capable terminal puts the decoded text on the clipboard. Apple Terminal does not implement OSC 52. Nested tmux, SSH, docker exec, and kubectl exec can also swallow or never deliver that sequence to the outer terminal.

matcha wrap sits **between you and the command**. It allocates a local pseudo-terminal, runs your command there, watches the output for OSC 52 (plain and tmux-wrapped), and writes the text to the **local OS clipboard**. The outer terminal never has to understand OSC 52.

What wrap does

matcha wrap docker exec -it my-container bash
matcha wrap kubectl exec -it my-pod -- bash
matcha wrap ssh user@host

• Forwards the child command’s output to your screen (minus consumed OSC 52)
• Syncs the inner terminal size with your window (Unix; Windows ConPTY does not forward live resize)
• Restores your terminal modes if the wrapped process dies with modes still latched (dropped SSH, SIGTERM)
• On Unix, a single quoted command line, or a name that is only a shell alias, is run via $SHELL -i -c so aliases and word-splitting work

Matcha’s own TUI can also emit OSC 52. That is a separate route from wrap. MATCHA_CLIPBOARD_NO_OSC52=1 turns off Matcha’s emission; it does not stop wrap from intercepting a child’s sequences.

When to use it

Use wrap when you need a shell **inside** a container, pod, or SSH host, and copy from that program should paste locally — especially on Apple Terminal, or whenever /doctor reports OSC 52 as unsupported or unverified.

If you already SSH in without wrap, Matcha may show a one-time hint to use wrap. /doctor can offer matcha doctor fix ssh-wrap (an alias for your shell). That hint does not hide the Doctor recommendation. Turn the hint off under /settings → **Show contextual hints** → **SSH wrap**, or set ssh_wrap = false under [ui.contextual_hints] in $MATCHA_HOME/config.toml.

Run wrap

From the **local** machine, prefix the command you would have typed:

matcha wrap ssh user@host
matcha wrap docker exec -it my-container bash
matcha wrap kubectl exec -it my-pod -- bash

Quoted one-liners (Unix) go through your shell:

matcha wrap "ssh user@host"

Then copy as usual in the inner program. The sequence is consumed; you should not see a Base64 blob on screen. Paste on the local machine.

If PTY setup fails, wrap prints a warning and runs the command **without** clipboard forwarding so the session still starts.

Diagnose first with matcha doctor or /doctor. Look at the Clipboard section: **native**, **tmux**, and **OSC 52**. After wrap is active, Doctor can show the OSC 52 sink as on.