Markdown links in responses are not clickable in terminal (Ghostty) — need raw URL fallback or OSC 8 hyperlinks

Prediction confirmed — root cause identified

TL;DR — root cause of labelled markdown links not being clickable in the TUI.

The mechanism below was stated as a falsifiable prediction before the test that confirms it, and the test came back positive.

Test: plain Ctrl+click on a bare URL, one variable changed.

| session | plain Ctrl+click on bare URL | Shift+Ctrl+click |
|---|---|---|
| normal | opens | opens |
| CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1 | stops working | opens |

Linux, Ghostty 1.3.1, Claude Code 2.1.220.

Why this settles it

While an application holds mouse reporting, the terminal does not act on unmodified clicks — demonstrated directly with shell repros under Claude Code's exact mode set (?1049h ?1000h ?1006h ?1004h), where plain Ctrl+click emits a mouse report (^[[<0;21;3M) to the application and opens nothing, for ST-terminated OSC 8, BEL-terminated OSC 8, and bare URLs alike.

So in a normal session, the thing opening bare URLs on plain Ctrl+click cannot be the terminal. It must be Claude Code. Disabling MOUSE_CLICKS removes exactly that handler, and the capability disappears with it.

Root cause

Claude Code's internal Ctrl+click handler resolves regex-style targets (bare URLs, file paths) but does not resolve OSC 8 hyperlink regions.

Consequences, all consistent with the reports on this issue:

• A labelled [text](url) link is skipped by the internal handler, so plain Ctrl+click does nothing.
• Shift bypasses the application entirely (Ghostty's mouse-shift-capture = false), reaching the terminal's own OSC 8 handler — which works, since the sequence Claude Code emits is well-formed.
• Bare URLs and file paths appear to "work normally", which is what makes labelled links look broken rather than merely requiring a different modifier.
• CLAUDE_CODE_DISABLE_MOUSE=1 and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 both "fix" it by stopping the application from capturing clicks at all, letting the terminal handle everything.

Ruled out by direct test along the way: the terminal (Ghostty services both OSC 8 forms correctly), the mode combination, the alternate screen in isolation, the BEL vs ST terminator, and terminal-capability detection (FORCE_HYPERLINK has no effect either way — see also #72998).

Fix

Teach the internal click handler to resolve OSC 8 hyperlink regions — the renderer already tracks them per-cell (hyperlinkPool in the 2.1.220 binary), so the destination is available at click time; it simply isn't consulted for labelled links.

This likely also explains the divergent gesture reports in #69446, #69700 and #73766: which gesture appears to "work" depends on whether the target happens to be one the internal handler recognises.

Meanwhile

Shift+Ctrl+click (Linux) / Shift+⌘+click (macOS) opens labelled links today, with no configuration changes and no loss of TUI or mouse behaviour. Worth documenting even after a fix.

---

Platform asymmetry — an open question

One observation qualifies the root cause above. Reported as data only; no mechanism offered.

Same Claude Code version, different platforms, different behaviour:

| machine | Claude Code | Ghostty | plain Ctrl+click on a labelled link |
|---|---|---|---|
| Arch Linux | 2.1.220 | 1.3.1 | nothing (needs Shift+Ctrl+click) |
| macOS | 2.1.220 | 1.2.3 | opens |

Independently, #69446 reports macOS on Ghostty 1.3.1 with Claude Code 2.1.181, where plain Ctrl+click also opens links (while plain ⌘-click does not). So the macOS result is not specific to the older Ghostty on my Mac — it holds at 1.3.1 too, which argues against a Ghostty version difference being the explanation.

Why this qualifies the root cause

The conclusion above is that Claude Code's internal click handler resolves bare URLs and file paths but not OSC 8 regions — confirmed on Linux by the CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1 prediction (plain Ctrl+click on a bare URL stops working when the handler is disabled).

That conclusion is well supported on Linux. It does not by itself explain why the same Claude Code build behaves differently on macOS. Two possibilities, and I have tested neither:

1. The click never reaches Claude Code on macOS (the OS or terminal consumes Ctrl+click before it is forwarded), so the terminal's own OSC 8 handler services it.
2. Claude Code's click handling is platform-conditional.

I have no evidence distinguishing these, and am not going to speculate further.

What is solid regardless of the platform question

• On Linux, labelled markdown links do not open on plain Ctrl+click; bare URLs and file paths do.
• Shift+Ctrl+click opens everything, on both platforms, with no configuration changes.
• The OSC 8 sequence Claude Code emits is well-formed; Ghostty services it correctly when it receives the click.
• When a labelled link does not open, its URL is not visible anywhere on screen and cannot be copied.

The platform split may itself be the most useful clue for whoever picks this up, since it suggests the divergence is in click delivery or platform-specific handling rather than in link rendering.

Claude Code already emits clickable OSC 8 hyperlinks for markdown links when it detects a terminal that supports them — Ghostty is on that list — and falls back to showing link text (url) when it doesn't. In Ghostty you need to hold Cmd while clicking the link text to open it.

If you're running inside tmux, over SSH, or in another wrapper that hides the terminal identity, detection can fail; set FORCE_HYPERLINK=1 in your environment to force hyperlinks on (and FORCE_HYPERLINK=0 to force the plain text (url) rendering instead). Terminal config reference: https://code.claude.com/docs/en/terminal-config

Closing as already available — if links still aren't clickable in plain Ghostty (no tmux/ssh) on the current release, please reopen with a screenshot and we'll treat it as a bug.

🤖 Generated with Claude Code

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.