본문으로 건너뛰기

Hints

Rio's hints system allows you to quickly interact with text patterns in your terminal by displaying keyboard shortcuts over matching content. This feature allows for quick interaction with terminal content through keyboard shortcuts.

How it works​

When you activate hint mode, Rio scans the visible terminal content for patterns you've configured (like URLs, file paths, or email addresses) and displays keyboard shortcuts over each match. You can then press the corresponding keys to perform actions on the matched text.

Default hints​

Rio ships with one rule out of the box that matches three kinds of clickable text. The default regex is ported verbatim from ghostty and uses oniguruma syntax (lookbehinds, lookaheads supported):

  1. Schemed URLs — http://, https://, file:, ssh:, mailto:, magnet:, ipfs://, gemini://, gopher://, git://, news:, ipns:, ftp://, tel:. IPv6 literals and bracketed parentheses inside URLs are handled.
  2. Rooted or explicitly-relative paths — /abs/path, ./rel, ../rel, ~/Desktop, .config/foo, $HOME/x, $XDG_CONFIG_HOME/x. Mid-word slashes (the /bar inside foo/bar) are rejected via lookbehind. Paths with internal spaces are matched when they contain a dotted filename segment (e.g. ~/My\ Documents/notes.md).
  3. Bare relative paths with a dotted filename — src/main.rs, lib/foo.zig:42:10. A dotted segment is required, so ambiguous strings like foo/bar aren't matched.

When you click a path-like match (or use the keyboard hint), rio resolves it against the terminal's working directory (reported by your shell via OSC 7), expands ~/ and $VAR/, and dispatches the absolute path to the OS opener (open/xdg-open/cmd /c start) only if the file exists. URL-scheme matches are passed through unchanged.

To get OSC 7 working from your shell:

# bash/zsh — emit OSC 7 on every prompt
PROMPT_COMMAND='printf "\033]7;file://%s%s\033\\" "$HOSTNAME" "$PWD"'
# fish
function osc7_cwd --on-event fish_prompt
    printf "\033]7;file://%s%s\033\\" $hostname (pwd)
end

OSC 8 hyperlinks (escape-sequence-marked links emitted by tools like ls --hyperlink=auto or modern shell prompts) are detected separately and always underlined while visible — no modifier required.

Basic Usage​

  1. Activate hint mode: Press the configured key binding (default varies by hint type)
  2. Navigate: Type the letters shown over the hint you want to select
  3. Execute: The configured action (copy, open, paste, etc.) will be performed

Configuration​

Hints are configured in your rio.toml file under the [hints] section:

[hints]
# Characters used for hint labels (should be easy to type)
alphabet = "jfkdls;ahgurieowpq"

# URL hint example
[[hints.rules]]
regex = "(https://|http://|ftp://)[^\u{0000}-\u{001F}\u{007F}-\u{009F}<>\"\\s{-}\\^⟨⟩`\\\\]+"
hyperlinks = true
post-processing = true
persist = false

[hints.rules.action]
command = "xdg-open"  # Linux/BSD
# command = "open"    # macOS  
# command = { program = "cmd", args = ["/c", "start", ""] }  # Windows

[hints.rules.mouse]
enabled = true
mods = []

[hints.rules.binding]
key = "O"
mods = ["Control", "Shift"]

Customizing Hint Colors​

Hint label colors can be customized in the [colors] section of your configuration:

[colors]
hint-foreground = '#181818'  # Text color for hint labels
hint-background = '#f4bf75'  # Background color for hint labels

Configuration Options​

Global Settings​

  • alphabet: String of characters used for hint labels. Should contain easily accessible keys.

Per-Hint Settings​

  • regex: Regular expression pattern to match
  • hyperlinks: Whether to treat matches as hyperlinks (enables special handling)
  • post-processing: Apply post-processing to clean up matched text
  • persist: Keep hint mode active after selection (useful for multiple selections)

Actions​

You can configure different types of actions:

Built-in Actions​

[hints.rules.action]
action = "Copy"     # Copy to clipboard
# action = "Paste"  # Paste the matched text
# action = "Select" # Select the matched text

External Commands​

[hints.rules.action]
command = "xdg-open"  # Simple command

# Or with arguments
command = { program = "code", args = ["--goto"] }

Key Bindings​

[hints.rules.binding]
key = "O"
mods = ["Control", "Shift"]

Mouse Support​

[hints.rules.mouse]
enabled = true
mods = ["Control"]  # Modifier keys required for mouse activation

Example Configurations​

URL Opener​

[[hints.rules]]
regex = "(https://|http://)[^\u{0000}-\u{001F}\u{007F}-\u{009F}<>\"\\s{-}\\^⟨⟩`\\\\]+"
hyperlinks = true
post-processing = true

[hints.rules.action]
command = "xdg-open"

[hints.rules.binding]
key = "O"
mods = ["Control", "Shift"]

File Path Copier​

[[hints.rules]]
regex = "/?(?:[\\w.-]+/)*[\\w.-]+"
post-processing = true

[hints.rules.action]
action = "Copy"

[hints.rules.binding]
key = "F"
mods = ["Control", "Shift"]

Email Composer​

[[hints.rules]]
regex = "[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}"

[hints.rules.action]
command = { program = "thunderbird", args = ["-compose", "to="] }

[hints.rules.binding]
key = "E"
mods = ["Control", "Shift"]

Performance​

Rio's hints system includes optimized rendering with damage tracking to ensure smooth performance:

  • Damage Tracking: Only re-renders areas where hint labels have changed.
  • Efficient Cleanup: Properly marks hint label areas for re-rendering when cleared.
  • Minimal Overhead: Hints are only processed when activated.