Support native Cmd-click link opening on macOS with mouse capture enabled

[leonfox28]

idea / problem

On macOS, Cmd-click is the standard gesture for opening links in terminal apps. With Herdr's default [ui] mouse_capture = true, Cmd-clicking a visible HTTP(S) or OSC 8 link in an agent pane does not open it in Ghostty. Shift-Cmd-click works because Shift bypasses Herdr's mouse capture, but having to add Shift is easy to forget. Setting mouse_capture = false also restores host-terminal handling, but loses Herdr's mouse UI.

This remains reproducible on:

• Herdr 0.7.5 (stable)
• macOS 26.5.2
• Ghostty 1.3.1

Related: #156 documents the workaround, and #307 added Herdr-native modified-click URL opening. Current native handling uses Ctrl-click on macOS rather than the platform-standard Cmd-click.

requested change

When running on macOS, let Cmd-click on an HTTP(S) or OSC 8 link open it in the default browser while mouse_capture remains enabled. Ctrl-click can stay supported, and ordinary clicks should continue to drive Herdr's mouse UI.

why you want this

Agent output frequently includes documentation, issue, and PR links. Supporting Cmd-click would preserve normal macOS terminal muscle memory without requiring Shift-Cmd-click or disabling Herdr's mouse UI.

[e-schultz]

Additional real-world reproduction from a macOS user working in a remote Herdr workspace with plugin OSC 8 link handlers:

• Ghostty, both ssh float-box && herdr and local herdr --remote evan@float-box: plain click does nothing, Cmd-click is consumed locally, and Control-click does not produce a usable modified-left event.
• Warp remote attach: plain click shows the native Cmd-click hint, Cmd-click reaches macOS LaunchServices, and Control-click becomes a secondary/context-menu action.
• An xterm-based desktop client similarly consumes the gesture in its webview/editor context menu.

The remote plugin handler is registered and works when invoked with the same clicked URI context, so the failure is the activation gesture reaching Herdr—not OSC 8 parsing or plugin routing. This prevents custom-scheme plugin links from being usable without installing a per-Mac URL-handler application.

A portable outcome would let a plugin explicitly opt a matching private OSC 8 scheme into ordinary-click activation while preserving the current modified-click default for existing handlers and normal web links. The use case is navigating durable IDs inside a remote terminal workspace; the plain click should stay inside that Herdr session rather than escape to local LaunchServices.

[cesar32az]

Another data point, on Warp (macOS), local herdr, Claude Code in the pane:

With mouse capture on, 0.9.4/0.9.5 leave no way to open an OSC 8 link:

• Cmd-click: suppressed since 0.9.4 (fix: respect mouse capture when routing hyperlink clicks #5064), as documented.
• Ctrl-click: Warp turns it into a secondary click, so herdr gets a right-click and opens the pane context menu instead of the link.

Turning capture off brings back Cmd-click but loses tab clicks, split dragging, the right-click menu and selection, so it isn't a real alternative.

This hits Claude Code users in particular: links in its chat output (PRs, docs) stop being clickable inside herdr. Downgrading to 0.9.3 with capture on restores Cmd-click, which is what I'm running now.

A modifier macOS terminals don't remap, or an option to keep advertising labeled links to the outer terminal while capture stays on, would fix it.

[kehwar]

I opened a related discussion: #5347

[akbash-bot]

For the native Command-click failures reported here, JJ has built test artifacts from PR #5457 (commit 87c4378c). Could you try your terminal’s usual link shortcut with mouse capture enabled and confirm whether labeled links open while tabs and split resizing still work?

Download choices and safe test-session instructions are on the PR. This is experimental, not a release; both client and server need the build, and an older running server intentionally keeps the old suppression. You can test without replacing your installed binary or stopping regular sessions.

This restores terminal-native opening only for links not claimed by an enabled, available plugin. It does not add plain-click activation for remote plugin links or change macOS terminals’ handling of Ctrl-click.

Please leave your terminal/version, local or SSH setup, gesture, and result on issue #5272.

[brijmcq]

I would also like this behavior. I use Ghostty 1.3.1 on macOS, with Herdr 0.9.3 on both my Mac and a remote Linux host.

In the remote session, Ctrl-click opens links, but Command-click does not. I reproduced this with standalone links as well as PR links, so it is not specific to the plugin displaying them.

I want Command-click to open the link in my Mac’s browser while keeping Herdr’s mouse controls enabled. I use pane selection, tabs, and split resizing, so disabling mouse capture is not a good tradeoff. The same gesture for local and remote sessions would avoid switching habits.