Package org.aesh.terminal.tty

Class TerminalColorDetector

java.lang.Object
org.aesh.terminal.tty.TerminalColorDetector
public final class TerminalColorDetector extends Object
Utility class to detect terminal color capabilities.

This detector can query the terminal to determine:

  • Color depth (8, 16, 256, or true color)
  • Background theme (light or dark)
  • Actual foreground and background RGB colors

Detection methods:

  • Environment variables (COLORTERM, TERM)
  • terminfo/infocmp database (max_colors capability)
  • OSC 10/11 queries for actual terminal colors

The detector supports caching to avoid repeated detection overhead. Use detectCached(Connection) for cached detection.

Author:
Ståle W. Pedersen

  • Method Details

    • detectCached

      public static TerminalColorCapability detectCached(Connection connection)
      Detect terminal color capabilities using cached result if available.

      This method returns a cached result if one exists and hasn't expired. Otherwise, it performs full detection and caches the result.

      Parameters:
      connection - the terminal connection
      Returns:
      detected color capabilities (may be cached)

    • clearCache

      public static void clearCache()
      Clear the cached color capability.

      Call this when the terminal environment may have changed (e.g., after a theme switch).

    • getCached

      public static TerminalColorCapability getCached()
      Get the cached color capability without performing detection.
      Returns:
      the cached capability, or null if not cached

    • detect

      public static TerminalColorCapability detect(Connection connection)
      Detect terminal color capabilities using all available methods.

      This method combines environment variable detection, terminfo database, and optional OSC terminal queries for the most complete detection.

      Parameters:
      connection - the terminal connection
      Returns:
      detected color capabilities

    • detect

      public static TerminalColorCapability detect(Connection connection, boolean queryTerminal)
      Detect terminal color capabilities.
      Parameters:
      connection - the terminal connection
      queryTerminal - if true, send OSC queries to the terminal to detect actual colors (may cause brief flicker on some terminals)
      Returns:
      detected color capabilities

    • detectColorDepth

      public static ColorDepth detectColorDepth(Connection connection)
      Detect only the color depth without querying the terminal for colors. This is a fast, non-blocking operation.
      Parameters:
      connection - the terminal connection
      Returns:
      the detected color depth

    • detectThemeFromEnvironment

      public static TerminalTheme detectThemeFromEnvironment()
      Detect terminal theme from environment variables.
      Returns:
      the detected theme, or UNKNOWN if not detectable

    • queryForegroundColor

      public static int[] queryForegroundColor(Connection connection, long timeoutMs)
      Query the terminal for its foreground color using OSC 10.
      Parameters:
      connection - the terminal connection
      timeoutMs - timeout in milliseconds
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported

    • queryBackgroundColor

      public static int[] queryBackgroundColor(Connection connection, long timeoutMs)
      Query the terminal for its background color using OSC 11.
      Parameters:
      connection - the terminal connection
      timeoutMs - timeout in milliseconds
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not supported

    • isOscColorQuerySupported

      public static boolean isOscColorQuerySupported()
      Check if the terminal likely supports OSC color queries.

      This is a heuristic based on the TERM environment variable and known terminal emulators. For more accurate detection, use Device.supportsOscQueries() or Connection.supportsOscQueries().

      Returns:
      true if OSC queries are likely supported
      See Also:

    • isTmuxPassthroughLikely

      public static boolean isTmuxPassthroughLikely()
      Check if tmux passthrough is likely enabled.

      Tmux 3.3+ supports allow-passthrough option which enables OSC queries to be passed through to the underlying terminal. This method checks for hints that passthrough might be enabled.

      Detection methods:

      • TMUX_PASSTHROUGH environment variable (custom, set by user)
      • Check if running in a modern tmux version (3.3+)
      • Check if a known OSC-capable outer terminal is detected

      Note: This is a best-effort heuristic. The only reliable way to know if passthrough is enabled is to attempt an OSC query.

      Returns:
      true if tmux passthrough is likely enabled

    • shouldUseTmuxPassthrough

      public static boolean shouldUseTmuxPassthrough()
      Check if we should use tmux DCS passthrough wrapping for OSC queries.

      This returns true when:

      • We are running inside tmux
      • AND we detect a known OSC-capable outer terminal (like Alacritty, Kitty, etc.)

      When passthrough is used, OSC sequences are wrapped in DCS (Device Control String) sequences that tmux will forward to the outer terminal.

      Returns:
      true if tmux passthrough wrapping should be used

    • isRunningInTmux

      public static boolean isRunningInTmux()
      Check if running inside tmux.
      Returns:
      true if running inside tmux

    • isRunningInScreen

      public static boolean isRunningInScreen()
      Check if running inside GNU Screen.
      Returns:
      true if running inside screen

    • isRunningInMultiplexer

      public static boolean isRunningInMultiplexer()
      Check if running inside any terminal multiplexer (tmux or screen).
      Returns:
      true if running inside a multiplexer

    • detectFast

      public static TerminalColorCapability detectFast(Connection connection)
      Get a fast, non-blocking color capability based only on environment detection (no terminal queries).
      Parameters:
      connection - the terminal connection (may be null)
      Returns:
      detected color capabilities