Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat(styling): underline every hyperlink (#3643)

Maximilian Roos79824f7122b7
diff --git a/.claude/skills/writing-user-outputs/SKILL.md b/.claude/skills/writing-user-outputs/SKILL.md
index 2736a846d..801dc97b8 100644
--- a/.claude/skills/writing-user-outputs/SKILL.md
+++ b/.claude/skills/writing-user-outputs/SKILL.md
@@ -736,6 +736,30 @@ eprintln!("{}", hint_message(cformat!("Run <underline>wt list</> to see worktree
eprintln!("{}", hint_message("Run 'wt list' to see worktrees"));
```
+## Hyperlinks
+
+Every OSC 8 link is underlined. Link text is sized to fit a column (`#3604`,
+`:11486`) and reads as ordinary content, and color already carries state (the
+CI verdict, dim for a port nothing answers on), so the underline is what marks
+a run of text as clickable.
+
+`worktrunk::styling::hyperlink(url, text)` emits the link and its underline
+together, which is what keeps the rule true at every call site. It closes with
+`[24m`, leaving a surrounding color or dim intact.
+
+```rust
+// GOOD - the helper carries the underline
+let cell = hyperlink(url, &format!(":{port}"));
+// GOOD - a caller's own style wraps the link
+format!("{style}{}{style:#}", hyperlink(url, text))
+// BAD - hand-assembled sequences, unmarked link
+format!("{}{text}{}", osc8::Hyperlink::new(url), osc8::Hyperlink::END)
+```
+
+Text that isn't a link stays plain. On a terminal without OSC 8 support `wt
+list` prints the dev-server URL in full, unadorned, because there's nothing
+there to click.
+
## Design Principles
- **`cformat!` for styling** — Never manual escape codes (`\x1b[...`)
diff --git a/docs/content/list.md b/docs/content/list.md
index f594244e3..a078657f6 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -505,7 +505,7 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s
A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.
-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both links are OSC 8, which a terminal that doesn't support them discards, leaving the same text unclickable.
+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.
### Claude Code mode
diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.md
index 377a67f32..807765bf5 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/list.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md
@@ -522,7 +522,7 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s
A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.
-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both links are OSC 8, which a terminal that doesn't support them discards, leaving the same text unclickable.
+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.
### Claude Code mode
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 377a67f32..807765bf5 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -522,7 +522,7 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s
A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.
-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both links are OSC 8, which a terminal that doesn't support them discards, leaving the same text unclickable.
+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.
### Claude Code mode
diff --git a/src/cli/list.rs b/src/cli/list.rs
index 5eb05958f..fd9b566f0 100644
--- a/src/cli/list.rs
+++ b/src/cli/list.rs
@@ -17,7 +17,7 @@ pub enum ListSubcommand {
A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.
-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both links are OSC 8, which a terminal that doesn't support them discards, leaving the same text unclickable.
+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.
## Claude Code mode
diff --git a/src/commands/list/ci_status/mod.rs b/src/commands/list/ci_status/mod.rs
index 7b0f578d9..a5670abe1 100644
--- a/src/commands/list/ci_status/mod.rs
+++ b/src/commands/list/ci_status/mod.rs
@@ -500,21 +500,16 @@ impl PrStatus {
/// Wrap `text` in this status's style, optionally as an OSC 8 hyperlink
/// to the PR/pipeline URL.
+ ///
+ /// The status color goes outside the link, which supplies its own
+ /// underline and closes it without disturbing that color.
fn styled(&self, text: &str, include_link: bool) -> String {
- if let (true, Some(url)) = (include_link, &self.url) {
- let style = self.style().underline();
- format!(
- "{}{}{}{}{}",
- style,
- osc8::Hyperlink::new(url),
- text,
- osc8::Hyperlink::END,
- style.render_reset()
- )
- } else {
- let style = self.style();
- format!("{style}{text}{style:#}")
- }
+ let style = self.style();
+ let body = match (include_link, &self.url) {
+ (true, Some(url)) => worktrunk::styling::hyperlink(url, text),
+ _ => text.to_string(),
+ };
+ format!("{style}{body}{style:#}")
}
/// Format CI status for a cell `max_width` columns wide.
@@ -835,10 +830,10 @@ mod tests {
// Number fits → PR reference, hyperlinked when supported
assert_snapshot!(pr.format_cell(4, false), @"#123");
- assert_snapshot!(pr.format_cell(4, true), @r"]8;;https://github.com/owner/repo/pull/123\#123]8;;\");
+ assert_snapshot!(pr.format_cell(4, true), @r"]8;;https://github.com/owner/repo/pull/123\#123]8;;\");
// Number wider than the column → bare # indicator, still hyperlinked
assert_snapshot!(pr.format_cell(3, false), @"#");
- assert_snapshot!(pr.format_cell(3, true), @r"]8;;https://github.com/owner/repo/pull/123\#]8;;\");
+ assert_snapshot!(pr.format_cell(3, true), @r"]8;;https://github.com/owner/repo/pull/123\#]8;;\");
// No number (branch workflow or pre-number cache entry) → bare # indicator
let branch = PrStatus {
diff --git a/src/commands/list/layout.rs b/src/commands/list/layout.rs
index e6c665220..2fdb3c532 100644
--- a/src/commands/list/layout.rs
+++ b/src/commands/list/layout.rs
@@ -620,11 +620,7 @@ struct PendingColumn<'a> {
/// nothing.
pub(crate) fn format_url_cell(url: &str, include_link: bool) -> String {
if include_link && let Some(port) = parse_port_from_url(url) {
- return format!(
- "{}:{port}{}",
- osc8::Hyperlink::new(url),
- osc8::Hyperlink::END
- );
+ return worktrunk::styling::hyperlink(url, &format!(":{port}"));
}
url.to_string()
}
diff --git a/src/commands/list/model/item.rs b/src/commands/list/model/item.rs
index ec8138144..43cf8a2e2 100644
--- a/src/commands/list/model/item.rs
+++ b/src/commands/list/model/item.rs
@@ -980,6 +980,44 @@ mod tests {
assert_eq!(url_cell(Some(true)), plain, "a live port should not dim");
}
+ /// Underline is the statusline's only cue that a reference is clickable:
+ /// link text is tuned for width (`#123`, `:17913`) and reads as ordinary
+ /// content, and color is already spoken for by CI state. So every link on
+ /// the line carries one, whichever segment emitted it.
+ #[test]
+ fn test_statusline_links_are_underlined() {
+ use crate::commands::list::ci_status::{CiSource, CiStatus, PrRef};
+
+ let mut item = ListItem::new_branch("abc123".to_string(), "feature".to_string());
+ item.url = Some("http://127.0.0.1:17913".to_string());
+ item.url_active = Some(true);
+ item.pr_status = Some(Some(PrStatus {
+ ci_status: CiStatus::Passed,
+ source: CiSource::PullRequest,
+ is_stale: false,
+ is_priming: false,
+ url: Some("https://github.com/owner/repo/pull/123".to_string()),
+ number: Some(PrRef::pr(123)),
+ review_state: None,
+ title: None,
+ body: None,
+ author: None,
+ comment_count: None,
+ updated_at: None,
+ }));
+
+ let line = item.format_statusline();
+ for (url, text) in [
+ ("https://github.com/owner/repo/pull/123", "#123"),
+ ("http://127.0.0.1:17913", ":17913"),
+ ] {
+ assert!(
+ line.contains(&worktrunk::styling::hyperlink(url, text)),
+ "{text} should render as an underlined link in {line:?}"
+ );
+ }
+ }
+
#[test]
fn test_list_item_counts() {
// New items have no counts computed yet
diff --git a/src/commands/statusline.rs b/src/commands/statusline.rs
index 53e18a680..151352dbd 100644
--- a/src/commands/statusline.rs
+++ b/src/commands/statusline.rs
@@ -1022,7 +1022,7 @@ fn filter_redundant_branch(segments: Vec<StatuslineSegment>, dir: &str) -> Vec<S
/// Get git status as prioritized segments for the current worktree.
///
-/// CI status and the dev-server URL render as clickable OSC 8 hyperlinks.
+/// CI status and the dev-server URL render as underlined OSC 8 hyperlinks.
fn git_status_segments(worktree: &WorkingTree) -> Result<Vec<StatuslineSegment>> {
use super::list::columns::ColumnKind;
diff --git a/src/styling/hyperlink.rs b/src/styling/hyperlink.rs
index 3db521c05..626531771 100644
--- a/src/styling/hyperlink.rs
+++ b/src/styling/hyperlink.rs
@@ -1,10 +1,31 @@
//! OSC 8 hyperlink support for terminal output.
+use color_print::cformat;
use osc8::Hyperlink;
// Re-export for direct use
pub use supports_hyperlinks::{Stream, on as supports_hyperlinks};
+/// Render `text` as an underlined OSC 8 hyperlink to `url`.
+///
+/// Every link worktrunk emits goes through here, so the underline is a
+/// property of being a link rather than a rule each call site remembers. Link
+/// text is sized to fit a column (`#3604`, `:11486`) and reads as ordinary
+/// content, and color is already spoken for by state (the CI verdict, dim for
+/// a port nothing answers on), so the underline is what marks the text as
+/// clickable.
+///
+/// Closing with `[24m` rather than a full reset keeps a surrounding color or
+/// dim intact, so a caller can wrap the result in either without the link
+/// punching a hole in it.
+pub fn hyperlink(url: &str, text: &str) -> String {
+ cformat!(
+ "<underline>{}{text}{}</>",
+ Hyperlink::new(url),
+ Hyperlink::END
+ )
+}
+
/// Strip OSC 8 hyperlinks while preserving other ANSI sequences (colors).
///
/// OSC 8 terminal hyperlinks are great for terminal output (clickable links!), but can cause
@@ -55,6 +76,27 @@ pub fn strip_osc8_hyperlinks(s: &str) -> String {
mod tests {
use super::*;
+ /// The underline brackets the link and closes with `[24m`, so a caller's
+ /// color or dim survives the link untouched.
+ #[test]
+ fn test_hyperlink_underlines_the_link_text() {
+ let linked = hyperlink("https://example.com", "#123");
+
+ assert_eq!(
+ linked,
+ format!(
+ "\u{1b}[4m{}#123{}\u{1b}[24m",
+ Hyperlink::new("https://example.com"),
+ Hyperlink::END
+ )
+ );
+ assert_eq!(
+ strip_osc8_hyperlinks(&linked),
+ "\u{1b}[4m#123\u{1b}[24m",
+ "stripping the link leaves the underline and nothing else"
+ );
+ }
+
#[test]
fn test_strip_osc8_hyperlinks_removes_hyperlink() {
// OSC 8 format: ESC ] 8 ; params ; URL ST TEXT ESC ] 8 ; ; ST
diff --git a/src/styling/mod.rs b/src/styling/mod.rs
index fd73d94ef..88e10ad9c 100644
--- a/src/styling/mod.rs
+++ b/src/styling/mod.rs
@@ -36,7 +36,7 @@ pub use format::{
wrap_styled_text,
};
pub use highlighting::format_toml;
-pub use hyperlink::{Stream, strip_osc8_hyperlinks, supports_hyperlinks};
+pub use hyperlink::{Stream, hyperlink, strip_osc8_hyperlinks, supports_hyperlinks};
pub use line::{StyledLine, StyledString, truncate_visible};
pub use suggest::{suggest_command, suggest_command_in_dir};
diff --git a/tests/integration_tests/statusline.rs b/tests/integration_tests/statusline.rs
index 80368b561..64d3af8d5 100644
--- a/tests/integration_tests/statusline.rs
+++ b/tests/integration_tests/statusline.rs
@@ -521,7 +521,7 @@ url = "http://{{ branch }}.localhost:3000"
let output = run_statusline(&repo, &[], None);
// Shows `?` because writing project config creates uncommitted file
- assert_snapshot!(output, @r" main ?^| @+2 ]8;;http://main.localhost:3000\:3000]8;;\");
+ assert_snapshot!(output, @r" main ?^| @+2 ]8;;http://main.localhost:3000\:3000]8;;\");
}
#[rstest]
@@ -542,7 +542,7 @@ url = "http://{{ branch }}.localhost:3000"
// Run statusline from feature worktree
let output = run_statusline_from_dir(&repo, &[], None, &feature_path);
- assert_snapshot!(output, @r" feature _ ]8;;http://feature.localhost:3000\:3000]8;;\");
+ assert_snapshot!(output, @r" feature _ ]8;;http://feature.localhost:3000\:3000]8;;\");
}
/// The URL segment lands after the CI reference and before the model in Claude
@@ -562,7 +562,7 @@ url = "http://{{ branch }}.localhost:3000"
let output = run_statusline(&repo, &["--format=claude-code"], Some(&json));
claude_code_snapshot_settings().bind(|| {
- assert_snapshot!(output, @r" [PATH] main ?^| @+2 ]8;;http://main.localhost:3000\:3000]8;;\ Opus");
+ assert_snapshot!(output, @r" [PATH] main ?^| @+2 ]8;;http://main.localhost:3000\:3000]8;;\ Opus");
});
}