Add OSC 8 hyperlinks to task hashes in progress output

[ewels]

Summary

This PR adds support for OSC 8 terminal hyperlinks to make task hashes clickable in the progress output. When a task's work directory is available and cleanup is not enabled, the task hash is rendered as a clickable hyperlink that opens the work directory. Hyperlinks are also added to the pipeline repo commit hash if possible.

Works in most terminal emulators (tested in iTerm2 and VSCode). Gracefully ignores the ANSI codes in rubbish terminal emulators and treats as normal text (tested in MacOS Terminal). Uses native protocol handling, so iTerm2 loads work directories in Finder (MacOS) and VSCode shows them in the file explorer side bar.

Links only activate when the cmd key is held on hover (alt in VSCode).

CleanShot.2026-02-04.at.09.56.40.mp4

Key Changes

• AnsiLogObserver: Added hyperlink() static method to wrap text in OSC 8 escape sequences, with automatic file:// prefix for local paths
• AnsiLogObserver: Modified line() method to render task hashes as hyperlinks when workDir is available and cleanup is disabled
• ProgressRecord: Added workDir field to track the current task's work directory URI
• WorkflowStats: Updated markSubmitted(), markStatusChange(), and markCached() methods to populate the workDir field from task metadata
• Tests: Added comprehensive test coverage for hyperlink generation and conditional rendering based on cleanup settings

Implementation Details

• Uses BEL (\007) as the String Terminator for better terminal compatibility
• Automatically converts local paths (starting with /) to file:// URIs
• Preserves URLs with existing schemes (s3://, gs://, az://) as-is
• Hyperlinks are only rendered when cleanup is disabled, since work directories are removed when cleanup is enabled
• Gracefully handles null or empty URLs by returning plain text

https://claude.ai/code/session_014AStcyMzd39iegXhfQL1yK

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	b27ad75
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/698c83146c42db0007bcde25

[adamrtalbot]

I think the workDir part extremely useful but understand the remote Git stuff is more complicated. Can we break out the workDir code into a separate PR so we can merge it sooner?

[bentsherman]

@ewels can we also add this to the Nextflow version that is printed so that it links to the GitHub release:

nextflow/modules/nextflow/src/main/groovy/nextflow/cli/CmdRun.groovy

Line 440 in 887443e

log.debug "N E X T F L O W ~ version ${BuildInfo.version}"

[ewels]

Yeah absolutely can 👍🏻 I wondered about doing that in the initial work but was worried I was overdoing it 😅 I'll add that in, give me a second.

[pditommaso]

To tell the true not sure the added complexity is worth. I need to give a better look

[ewels]

To tell the true not sure the added complexity is worth. I need to give a better look

I've added a whole bunch of links in this PR. If you're worried about complexity, I can do what @adamrtalbot suggested and make a stripped back PR that just links the task hashes to their work directories.

I can 100000% guarantee that the task hash link feature is worth it. I've pretty much had my arm bitten off by a lot of people in the past 2 days since I made that video at the top of this PR.

[bentsherman]

I think I agree, let's try just the work dir path for now and revert the other links (including the one I requested...)

[ewels]

Ok I reverted most of the changes and rebased. PR code change should be as clean as possible now.

[adamrtalbot]

My main motivation for asking the workDir feature to be broken out is I want it NOW.

[ewels]

@pditommaso does this look ok now? 🙏🏻

[pditommaso]

I'm trying this but it's not showing anything for me

[ewels]

I'm trying this but it's not showing anything for me

Yup, that's expected (and a good thing). My guess is that you're using the MacOS terminal app @pditommaso - this doesn't support these style of hyperlinks, so it's doing the "graceful ignoring" thing I mentioned:

Works in most terminal emulators (tested in iTerm2 and VSCode). Gracefully ignores the ANSI codes in rubbish classic terminal emulators and treats as normal text (tested in MacOS Terminal).

If you try in iTerm2, Ghostty, VSCode or basically any other terminal emulator, it should work.

[pditommaso]

My guess is that you're using the MacOS terminal app

Got it

[pditommaso]

Then then what's going to be the link behaviour for s3:// or gs:// and similar paths ?

[ewels]

Then then what's going to be the link behaviour for s3:// or gs:// and similar paths ?

It depends on your local system and what you have configured to handle those URI schemes. The terminal emulator delegates the "open" action to your OS.

For example, on macOS if you have Cyberduck installed (as I do, I'm oldschool 😎), it will register as a handler for s3:// and gs:// URIs, so clicking the link would open that bucket path in Cyberduck. On Linux, it'll depends on the xdg-open configuration.

I think I'm right in saying that if nothing is registered for the scheme, the click will simply do nothing. It'll still display correctly, it's just not an active link. It's the same as if you pasted an s3:// URI into any other context on your system.

[ewels]

Note that this delegation is actually kind of cool, it's the reason that it works so well out of the box in VSCode. The VSCode terminal intercepts the action and handles itself instead of bubbling it up to the OS, meaning that it opens the file in VSCode instead of Finder.

[pditommaso]

Ok, understand. Let me give a quick try I believe we can make without the need to add a new workDir field

[pditommaso]

In principle the task work dir could be inferred by the session.workDir + stats.hash, however there's the edge case when different executors uses different work dir that's not covered by this. Then let's current approach

[PeterKnealeCMRI]

❤️