Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix GUI: dispatch file:// and custom-scheme clicks to OS shell handler

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Fix Action

Fix / Workaround

Verification that the OS-level handler is fine: invoking the same phpstorm-open://... URL via Start-Process "<url>" in PowerShell does route through ShellExecute and opens PhpStorm at the correct file and line. So the OS dispatch works; only the GUI is not delegating.

Workarounds attempted

  • Custom protocol handler phpstorm-open:// registered in HKCU + wrapper that invokes phpstorm64.exe --line N. Works perfectly via Start-Process, but not via clicking in the GUI.
  • Markdown file:// link: opens internal viewer, not external app.
  • Operational workaround in use: emit the markdown link plus a Start-Process "<url>" command below, so the user can copy-paste to an external PowerShell.
RAW_BUFFERClick to expand / collapse

Summary

In the Claude Code desktop GUI (verified on Windows), clicking a markdown link with a file:// URL opens the file in Claude Code's built-in internal file viewer; clicking a markdown link with an OS-registered custom URL scheme (e.g. phpstorm-open://, jetbrains://) does nothing. There is no way to route these clicks to the OS default handler (Windows ShellExecute / macOS LSOpenCFURLRef / Linux xdg-open).

This blocks the natural workflow of clicking a link in Claude's response to:

  • open a source file at line N in an external editor (PhpStorm, VS Code),
  • open a PDF / .docx / image in its default Windows app,
  • trigger any OS-registered URL handler (custom internal tools, Zoom, Slack, Figma).

Expected behavior

When the user clicks a markdown link whose URL scheme is either file:// or any scheme registered with the OS, the GUI should hand the URL off to the OS shell (shell.openExternal() in Electron terms) instead of intercepting it. This is the standard Electron pattern.

Optional refinement: Cmd/Ctrl+click as a modifier to force external open while plain click keeps current behavior for file://, mirroring the VS Code extension FR #43708.

Current behavior (Windows GUI, verified 2026-05-28)

URL formWhat happens
https://... (markdown link)Opens in default browser.
file:///C:/path/file.md (markdown link)Opens in Claude Code internal viewer; not in the Windows default app. No setting to change.
phpstorm-open://... (custom scheme registered in HKCU\Software\Classes\phpstorm-open)Click does nothing.
Bare file path (no scheme)Not linkified.

Verification that the OS-level handler is fine: invoking the same phpstorm-open://... URL via Start-Process "<url>" in PowerShell does route through ShellExecute and opens PhpStorm at the correct file and line. So the OS dispatch works; only the GUI is not delegating.

Workarounds attempted

  • Custom protocol handler phpstorm-open:// registered in HKCU + wrapper that invokes phpstorm64.exe --line N. Works perfectly via Start-Process, but not via clicking in the GUI.
  • Markdown file:// link: opens internal viewer, not external app.
  • Operational workaround in use: emit the markdown link plus a Start-Process "<url>" command below, so the user can copy-paste to an external PowerShell.

Related

  • #13008 — OSC 8 hyperlinks for clickable file paths (about linkability of bare paths, not OS dispatch).
  • #43708 — VS Code extension: Ctrl+Shift+Click file:// to open externally (similar ask, different surface).

Environment

  • Claude Code (desktop GUI), version 2.1.142
  • OS: Windows

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

When the user clicks a markdown link whose URL scheme is either file:// or any scheme registered with the OS, the GUI should hand the URL off to the OS shell (shell.openExternal() in Electron terms) instead of intercepting it. This is the standard Electron pattern.

Optional refinement: Cmd/Ctrl+click as a modifier to force external open while plain click keeps current behavior for file://, mirroring the VS Code extension FR #43708.

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING