Links
Open a link in a pane with Ctrl+click, choose the click and the opener, and see which terminals pass the click to TUIOS.
Ctrl+click on a link in a pane opens it. This works on every platform, macOS included.
TUIOS finds two kinds of link:
- An OSC 8 link is a link that a program marked, such as
ls --hyperlink,gcc,delta,ghor an agent CLI. Its text and its target can be different. - A bare URL is plain text that starts with
http://,https://,ftp://,ftps://,file://,ssh://orgit://.
Open a link
| Gesture | Does |
|---|---|
| Hover a link | Underline it and show its target in a label under the pointer |
| Ctrl+click | Open the link |
| Shift+click | Also open the link. Most terminals keep this click for their own selection, so it often does not reach TUIOS |
| Ctrl+drag | Move the pane, as before. A link opens only when the pointer does not move |
The label shows the real target, also when the text on the screen is different. After a click, the dock names the host, for example Opening github.com.
A URL that wraps onto the next row is one link. A URL whose start or end is off the screen also opens whole: TUIOS reads the rest of it from the scrollback or from the rows under the view.
Hints mode opens links from the keyboard. Ctrl+B F, then Ctrl and a label, opens that URL. Hints mode and the pointer use the same URL detector, so they find the same links.
Links to a window Added in v0.10.0
A program in a pane can print a link to another TUIOS window. The address is tuios://window/<id>, as an OSC 8 link. <id> is the short id of the window from the rail or from tuios list-windows. TUIOS refuses an id of fewer than 8 characters.
- Ctrl+click on
tuios://window/<id>focuses that window. When the window is in another session of the same daemon, TUIOS switches to that session first. The hover label says so. - Ctrl+click on
tuios://window/<id>/closeopens a confirmation that names the pane. Only a click on its close row closes the pane. A click anywhere else keeps the pane.
printf '\e]8;;tuios://window/%s\e\\go to the build\e]8;;\e\\\n' 7e02c4a1TUIOS does not send a tuios:// link to your terminal, so your terminal never opens one.
Link rules Added in v0.13.1
A link rule turns text that is not a URL into a link, such as a ticket ID that opens its page in an issue tracker. It works like WezTerm's implicit hyperlinks.
[[links.rules]]
regex = '\b([A-Z][A-Z0-9_]+-[1-9][0-9]*)\b'
url = "https://jira.example.com/browse/$1"regexis a regular expression in Go syntax.urlis the address a match opens.$0is the whole match, and$1,$2and so on are its groups. A named group is${name}. A group followed by a letter, a digit or_needs braces: write${1}_x. TUIOS warns about aurlthat names a group the regex does not have.- A match is a link like a bare URL: the hover underline and label, the click,
link_opener, and hints mode. - Rules apply when
linksisall, as bare URLs do. A real URL wins when a rule matches text inside it, and an earlier rule wins over a later one. - A rule that does not compile, or that matches empty text, is skipped with a warning.
Keep the host fixed
Keep the scheme and the host fixed in url, and put groups in the path or the query only, as in the example. A group before the path, such as https://example.com$1, lets the text on screen choose the host. The address a rule builds goes through the same check as every link: one that is not http, https, mailto, ftp or ftps, or that holds a byte a bare URL cannot hold, makes no link.
Where a URL ends
- A URL ends at a space, a quote, a backtick or an angle bracket.
- A
)or a]ends the URL when the URL did not open it. A pair that the URL opens stays in it, as inhttps://en.wikipedia.org/wiki/Go_(language). - TUIOS removes
.,;:!?from the end.
So the markdown badge [](https://a.example/c) gives two URLs.
Settings
[appearance]
links = "all" # off, marked (OSC 8 only), all
link_click = "both" # both, ctrl, shift, off
link_opener = "" # for example "firefox --new-tab" or "open -a Safari %s"| Key | Default | What it does |
|---|---|---|
links | "all" | The links TUIOS finds. marked finds only OSC 8 links. off finds none |
link_click | "both" | The click that opens a link. both is Ctrl+click and Shift+click. off turns the click off |
link_opener | "" | The command that opens a web link. TUIOS puts the URL where %s is, or at the end |
All three work with tuios set-config and are on the settings page.
If link_opener is empty, TUIOS uses $BROWSER, then the system opener:
| System | Opener |
|---|---|
| macOS | open |
| Windows | rundll32 |
| WSL | wslview |
| Other systems | xdg-open |
TUIOS runs no shell. It gives the URL to the opener as one argument.
When the link does not open
TUIOS watches the opener for 3 seconds. If the opener fails in that time, the dock shows "The link did not open. The address is on your clipboard." The log (Ctrl+B D l) keeps what the opener wrote to stderr.
If TUIOS cannot start the opener, the dock names the command and TUIOS copies the URL. If link_opener does not parse, the dock tells you to change it.
Which machine opens the link
- A local client opens the link on your machine.
- Under
ssh, TUIOS does not use the system opener, because it would open the browser on the remote machine. TUIOS puts the URL on your clipboard. Set$BROWSERorlink_openerto a command that forwards the URL, if you have one. - A remote client (
tuios ssh, the web client) puts the URL on your clipboard. - A Linux machine with no
DISPLAYand noWAYLAND_DISPLAYhas no desktop. TUIOS puts the URL on your clipboard.
In all these cases, TUIOS also sends each link to your terminal as OSC 8. Use the link click of your terminal to open it on your machine.
OSC 8 to your terminal
TUIOS draws each pane into its own frame, so your terminal sees the output of TUIOS and not the output of the program. TUIOS writes every link in the focused pane as OSC 8:
- An OSC 8 link keeps its URI and its
id=. - A bare URL gets an
id=from TUIOS, so a URL that wraps to the next row is one link.
Your terminal can then show and open the real target. In a pane that is not focused, TUIOS writes the OSC 8 links of the program, and your terminal finds the bare URLs itself.
Safety
- Only
http,https,mailto,ftpandftpslinks go to the opener. TUIOS copies other links, such asjavascript:,data:or the scheme of an application. - A
file://link opens in an editor pane only when the file is on this machine. A folder opens in the rail's files section. Afile://link with the name of another host does not open. - TUIOS refuses an address with control characters or spaces.
- TUIOS does not ask before it opens a link. The hover label and the scheme list protect you instead.
Terminals
A terminal sends a click to TUIOS only when the terminal does not use the click itself. Most terminals keep Shift+click for their own selection when a program reads the mouse. That is why Ctrl+click is the main click.
| Terminal | Shift+click gets to TUIOS | Ctrl+click gets to TUIOS | The terminal opens OSC 8 links |
|---|---|---|---|
| kitty | No. kitty opens the URL under the pointer | Yes | Yes, with Shift+click or Ctrl+Shift+click |
| Ghostty | No. Ghostty extends its selection | Yes. On a link, Ghostty opens it | Yes |
| WezTerm | No. Shift bypasses mouse reporting | Yes | Yes |
| Alacritty | No. Alacritty opens a hinted URL | Yes | Yes, with Shift+click |
| foot | No. Shift bypasses mouse reporting | Yes | Yes, in URL mode (Ctrl+Shift+O) |
| iTerm2 | Yes | Yes | Yes |
| Windows Terminal | No. Shift bypasses mouse mode | Yes | Yes, with Ctrl+click when it gets the click |
| xterm | No. Shift bypasses mouse reporting | Yes | No |
On macOS, Ctrl+click opens a link in Ghostty, kitty, WezTerm and Terminal.app. Cmd+click does not open a link in any of them while TUIOS reads the mouse.
Shift+click in Ghostty
A program can ask Ghostty for Shift+click with XTSHIFTESCAPE, or you can set mouse-shift-capture = true. TUIOS does not ask, because that takes Shift selection away from you.
Related
Finding a pane
Jump to a pane by its label, or find any pane in any session by its name, folder, command or screen text.
Paste buffers
Keep your recent yanks, paste one again with Ctrl+B ], choose one from a list, and use the same buffers from the CLI and the tmux shim.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.