[FEATURE] OSC 8 Hyperlinks for Clickable File Paths

[vwieczorek]

Problem Statement

When Claude Code outputs file paths like /Users/user/project/src/foo.ts:42, they are not clickable in terminals that support hyperlinks (Kitty, iTerm2, WezTerm, Windows Terminal).

This happens because:

1. Paths are output as plain text without the file:// scheme
2. ANSI color codes wrapped around paths break terminal pattern matching
3. The path:line format isn't recognized as a clickable URL

Users must manually copy paths or use terminal-specific workarounds (like Kitty's hints kitten) to navigate to files.

Proposed Solution

Emit file paths using the OSC 8 hyperlink escape sequence, which is the terminal standard for embedded hyperlinks:

\033]8;;file:///absolute/path/to/file.ts\033\\file.ts:42\033]8;;\033\\

This makes paths clickable with a single click (or Cmd/Ctrl+click depending on terminal config). Many modern CLI tools already do this (ls, exa/eza, fd, bat).

Reference: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

Alternative Solutions

• Workaround I currently use: Kitty's hints kitten (Cmd+Shift+F to select paths) - works but requires extra keystrokes
• file:// prefix only: Would partially help but less robust than OSC 8
• Opt-in config: Could be a setting if terminal compatibility is a concern

Use Case Example

1. I ask Claude Code to find a bug in my project
2. Claude outputs: "The issue is in /Users/victor/project/src/auth.ts:142"
3. Currently: I manually copy the path or use hints kitten
4. With this feature: I Cmd+click the path and it opens in my editor

This is especially valuable when Claude references multiple files in a single response.

Additional Context

OSC 8 terminal support (https://github.com/Alhadis/OSC8-Adoption):

• Kitty, iTerm2 (3.1+), WezTerm, Windows Terminal
• GNOME Terminal (VTE 0.50+), foot, Konsole
• Alacritty (recent versions)

Related but distinct from #609 (URL text wrapping) - this is about file paths not being hyperlinks at all.

Environment: macOS, Kitty terminal with detect_urls yes, allow_hyperlinks yes

[sleepo581]

This is critical

It's not clear what is selected

[jhob101]

This is critical

It's not clear what is selected

Yep, this is my big issue with it too. Massive problem when you can't see what's selected and makes referencing files, which we do all the time, really cumbersome to use.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[mash]

Here's a solution for the visitors.
I personally use Ghostty and wanted the links in Claude Code to become clickable.

https://github.com/mash/osc8wrap

[MarcinOrlowski]

@mash Clickable links in that form as you demonstrated are not a challenge. Custom links were you see not the url but its label (like HTML <a href="URL">LABEL</a>) is. It's very useful think in terminal and i use it heavily. I already do have custom status linke but I'd cram more info there if some of my links could be OSC 8 links (with short label and url not exposed directly).

i.e. try to run this directly in compatible terminal

"🏁 \x1b]8;id=link1;https://google.com\x07\x1b[4;38;2;46;171;12mGoogle\x1b[0m\x1b]8;;\x07 · 🌐 \x1b]8;id=link2;https://github.com\x07\x1b[4;38;2;46;171;12mGitHub\x1b[0m\x1b]8;;\x07 · 🪲 \x1b]8;id=link3;https://example.com\x07\x1b[4;38;2;230;159;28mExample\x1b[0m\x1b]8;;\x07"

and then try to return this from statusline - will not work.

[ShravanSunder]

it would be great if file paths are clickable as well. when the text claude outputs has file links it, should also be compatable with osc 8. this will help a lot to review or follow the file

[him0]

I ran into an issue with OSC 8 hyperlinks where the sequence did not work in the Claude Code statusline, and I was able to narrow it down to the choice of terminator.

What didn’t work (ST / ESC )

// Using ST (String Terminator)
return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;

What works (BEL / 0x07)

// Using BEL terminator
return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;

Technical notes

OSC 8 sequences support two possible terminators:

Terminator	Escape sequence	Compatibility
ST (String Terminator)	\x1b\ (ESC )	Not reliably handled in some environments
BEL	\x07	Historically supported, more widely compatible

In the Claude Code statusline rendering path, the ST terminator does not appear to be interpreted correctly. Switching to BEL makes the hyperlink work as expected.

Since many terminal emulators have long supported BEL as an OSC terminator, using BEL by default (or at least providing it as a fallback) may provide better compatibility, especially in statusline or intermediate rendering contexts (e.g. tmux-like pipelines).

Verified in practice

I have confirmed that this works correctly in a real statusline implementation:
https://github.com/him0/claude-code-statusline

[MarcinOrlowski]

Just tested and seems BEL is working workaround to make custom links work with status line. Thanks @him0

[senguttuvang]

Use Case: Paths with Spaces

Adding voice to this request with a specific use case: file paths containing spaces.

Current Behavior

When Claude Code outputs a path like:

Created: /Users/name/Projects/My Project/docs/file.md

The path breaks at the space — terminal treats Project/docs/file.md as a separate token. Not clickable.

Workaround (Ugly)

Current workaround via CLAUDE.md instructions:

Created: file:///Users/name/Projects/My%20Project/docs/file.md

Works, but the %20 encoding is visually noisy and harder to read.

Desired Behavior

Other CLI tools (e.g., Codex) output paths with OSC 8 hyperlinks:

• User sees: /Users/name/Projects/My Project/docs/file.md (clean, underlined, clickable)
• Hidden link: file:///Users/name/Projects/My%20Project/docs/file.md

Why This Matters

macOS conventions use Title Case with spaces for folders (Documentation, Source Code, project names). These are common in real-world projects. OSC 8 would let Claude Code display human-readable paths while maintaining clickability.

Terminal Support

Both iTerm2 and Ghostty fully support OSC 8 hyperlinks.

---

Co-Authored-By: Claude Code noreply@anthropic.com