pass OSC 8 hyperlinks through tmux to outer terminal #14

Merged

bryan merged 1 commit from tmux-osc8-hyperlink-passthrough into main

2026-04-23 15:24:46 +00:00

bryan commented

2026-04-23 15:21:03 +00:00

Owner

Summary

Tmux strips OSC 8 hyperlink escape sequences from program output by default. Programs like Claude Code emit URLs wrapped in \e]8;;URL\e\\TEXT\e]8;;\e\\ so the terminal can render them as rich hyperlinks — tmux was eating the wrapper and passing only TEXT downstream. For bare one-line URLs this still worked via Alacritty's URL-regex hints, but richer cases (display text ≠ target, URLs that wrap across the pane width) lost their linking.

Adding terminal-features ",*:hyperlinks" tells tmux the outer terminal understands OSC 8 and to pass the escapes through instead of stripping them.

Changes

dot-tmux.conf — add set -as terminal-features ",*:hyperlinks" alongside the existing terminal-overrides block.

Test plan

After source ~/.tmux.conf, tmux show -g terminal-features lists *:hyperlinks.
After detach + reattach, tmux display -p '#{client_termfeatures}' includes hyperlinks (the server-level setting is evaluated per-client at attach time, so source-file alone doesn't update an already-attached client).
PR URL from Claude Code is clickable inside tmux in Alacritty.

Notes

Alacritty uses Shift (not Option) to bypass tmux's mouse on capture when clicking URLs — this is Alacritty's cross-platform convention.
This is a robustness improvement, not a strict fix: Shift-click on the bare URL text was already working via Alacritty's URL-regex hint before this change. The value here is handling cases the regex can't (line-wrapped URLs, rich-text hyperlinks).

## Summary Tmux strips OSC 8 hyperlink escape sequences from program output by default. Programs like Claude Code emit URLs wrapped in `\e]8;;URL\e\\TEXT\e]8;;\e\\` so the terminal can render them as rich hyperlinks — tmux was eating the wrapper and passing only `TEXT` downstream. For bare one-line URLs this still worked via Alacritty's URL-regex hints, but richer cases (display text ≠ target, URLs that wrap across the pane width) lost their linking. Adding `terminal-features ",*:hyperlinks"` tells tmux the outer terminal understands OSC 8 and to pass the escapes through instead of stripping them. ## Changes - `dot-tmux.conf` — add `set -as terminal-features ",*:hyperlinks"` alongside the existing terminal-overrides block. ## Test plan - [x] After `source ~/.tmux.conf`, `tmux show -g terminal-features` lists `*:hyperlinks`. - [x] After detach + reattach, `tmux display -p '#{client_termfeatures}'` includes `hyperlinks` (the server-level setting is evaluated per-client at attach time, so `source-file` alone doesn't update an already-attached client). - [x] PR URL from Claude Code is clickable inside tmux in Alacritty. ## Notes - Alacritty uses **Shift** (not Option) to bypass tmux's `mouse on` capture when clicking URLs — this is Alacritty's cross-platform convention. - This is a robustness improvement, not a strict fix: Shift-click on the bare URL text was already working via Alacritty's URL-regex hint before this change. The value here is handling cases the regex can't (line-wrapped URLs, rich-text hyperlinks).

bryan added 1 commit

2026-04-23 15:21:03 +00:00

pass OSC 8 hyperlinks through tmux to outer terminal 2be89df841

Tmux strips OSC 8 hyperlink escape sequences by default, so clickable
URLs emitted by programs like Claude Code arrive at Alacritty as plain
text. Alacritty's URL-regex hint still matches bare URLs, so simple
cases remain clickable — but URLs that wrap across lines, or rich
hyperlinks with display text distinct from the target, lose their
linking.

Enable hyperlink passthrough so Alacritty sees real OSC 8 links.
Requires detach+reattach for an active client to pick up the new
terminal-features — source-file alone won't refresh client capabilities.

bryan changed title from ~~WIP: pass OSC 8 hyperlinks through tmux to outer terminal~~ to pass OSC 8 hyperlinks through tmux to outer terminal

2026-04-23 15:21:28 +00:00

bryan merged commit 14880e0009 into main

2026-04-23 15:24:46 +00:00

bryan referenced this pull request from a commit

2026-04-23 15:24:48 +00:00

pass OSC 8 hyperlinks through tmux to outer terminal (#14)