terminal.c File Reference

Cross-platform unified color detection and terminal capabilities. More...

Go to the source code of this file.

Functions
bool	terminal_should_color_output (int fd)
	Determine if color output should be used.
terminal_color_mode_t	terminal_get_effective_color_mode (void)
	Get current color mode considering all overrides.
bool	terminal_is_stdin_tty (void)
	Check if stdin is connected to a TTY.
bool	terminal_is_stdout_tty (void)
	Check if stdout is connected to a TTY.
bool	terminal_is_stderr_tty (void)
	Check if stderr is connected to a TTY.
bool	terminal_is_interactive (void)
	Check if the session is fully interactive.
unsigned short int	terminal_get_effective_width (void)
	Get effective terminal width with fallback priority.
unsigned short int	terminal_get_effective_height (void)
	Get effective terminal height with fallback priority.
bool	terminal_is_piped_output (void)
	Check if stdout is piped or redirected.
bool	terminal_should_force_stderr (void)
	Determine if logs should be forced to stderr.
bool	terminal_can_prompt_user (void)
	Determine if interactive user prompts are appropriate.
int	terminal_choose_log_fd (log_level_t level)
	Choose output file descriptor for logging based on level and interactivity.
void	terminal_get_default_foreground_color (int theme, uint8_t *out_r, uint8_t *out_g, uint8_t *out_b)
	Get theme-aware default foreground color for the renderer.
void	terminal_get_default_background_color (int theme, uint8_t *out_r, uint8_t *out_g, uint8_t *out_b)
	Get theme-aware default background color for the renderer.
bool	terminal_should_use_control_sequences (int fd)
	Check if terminal control sequences should be used for the given fd.

Detailed Description

Cross-platform unified color detection and terminal capabilities.

Definition in file platform/terminal.c.

Function Documentation

terminal_can_prompt_user()

bool terminal_can_prompt_user

(

void

)

Determine if interactive user prompts are appropriate.

Returns

true if prompts can be shown, false if non-interactive/automated

Determines whether interactive user prompts (yes/no, passwords, confirmations) should be displayed. Returns false in non-interactive or automated contexts.

Use this to decide whether:

• Password prompts should be shown (or auto-cancel)
• Yes/No confirmations should wait for input (or use defaults)
• Known hosts prompts should be interactive (or auto-deny)

Logic:

1. If not fully interactive (stdin or stdout not TTY) → false
2. If in snapshot mode (–snapshot) → false
3. If ASCII_CHAT_QUESTION_PROMPT_RESPONSE set → false (automated responses)
4. Otherwise → true (interactive prompts OK)

Examples:

• ascii-chat client in terminal → true (can prompt)
• ascii-chat client --snapshot → false (non-interactive mode)
• echo data | ascii-chat client → false (stdin piped)
• ‘ASCII_CHAT_QUESTION_PROMPT_RESPONSE='y’ ascii-chat client→ false (automated) -ascii-chat client > output.txt` → false (stdout redirected)

Note

Combines checks for: TTY status, snapshot mode, automation env vars

Used by password prompts, known_hosts verification, user confirmations

When false, password prompts should auto-cancel with error

When false, yes/no prompts should use default value or deny

Definition at line 215 of file platform/terminal.c.

                                    {
  // Must be fully interactive (stdin and stdout are TTYs)
  if (!terminal_is_interactive()) {
    return false;
  }
 
  // Must not be in snapshot mode (non-interactive capture)
  if (GET_OPTION(snapshot_mode)) {
    return false;
  }
 
  // Must not have automated prompt responses configured
  const char *auto_response = SAFE_GETENV("ASCII_CHAT_QUESTION_PROMPT_RESPONSE");
  if (auto_response && *auto_response != '\0') {
    // NOLINTNEXTLINE(readability-simplify-boolean-expr) - Intentional check for configured automated responses
    return false;
  }
 
  // All checks passed, interactive prompts are appropriate
  return true;
}

References GET_OPTION, SAFE_GETENV, and terminal_is_interactive().

Referenced by prompt_unknown_host().

terminal_choose_log_fd()

int terminal_choose_log_fd

(

log_level_t

level

)

Choose output file descriptor for logging based on level and interactivity.

Parameters

level

Log level (determines default routing: WARN+ to stderr, others to stdout)

Returns

STDERR_FILENO or STDOUT_FILENO based on log level and terminal state

Routes logs appropriately:

• When terminal is NOT interactive (piped): ALL logs to stderr
• When force_stderr enabled: ALL logs to stderr
• Otherwise: WARN/ERROR/FATAL to stderr, others to stdout

This consolidates log routing logic used throughout the codebase.

Note

Use: int fd = terminal_choose_log_fd(LOG_INFO);

Common usage: platform_write_all(terminal_choose_log_fd(level), data, len);

Definition at line 237 of file platform/terminal.c.

                                              {
  // When force_stderr is enabled (client mode), send ALL logs to stderr
  // When terminal is NOT interactive (piped/redirected), send ALL logs to stderr
  // to keep stdout clean for piped data (JSON, frames, etc.)
  if (log_get_force_stderr() || !terminal_is_interactive()) {
    return STDERR_FILENO;
  }
 
  // In interactive mode, route based on level:
  // WARN and above (ERROR, FATAL) go to stderr
  // Others (DEV, DEBUG, INFO) go to stdout
  if (level >= LOG_WARN) {
    return STDERR_FILENO;
  }
 
  return STDOUT_FILENO;
}

References log_get_force_stderr(), LOG_WARN, and terminal_is_interactive().

Referenced by log_console_impl(), log_msg(), and log_plain_msg().

terminal_get_default_background_color()

void terminal_get_default_background_color	(	int	theme,
		uint8_t *	out_r,
		uint8_t *	out_g,
		uint8_t *	out_b
	)

Get theme-aware default background color for the renderer.

Get theme-aware default background color for pixel renderers.

Parameters

theme	Terminal theme (dark or light)
out_r	Pointer to store red component (0-255)
out_g	Pointer to store green component (0-255)
out_b	Pointer to store blue component (0-255)

Returns appropriate default background color based on terminal theme. Light theme uses white background, dark theme uses black background.

Definition at line 291 of file platform/terminal.c.

                                                                                                      {
  if (theme == 1) { // TERM_RENDERER_THEME_LIGHT
    *out_r = TERMINAL_COLOR_THEME_LIGHT_BG_R;
    *out_g = TERMINAL_COLOR_THEME_LIGHT_BG_G;
    *out_b = TERMINAL_COLOR_THEME_LIGHT_BG_B;
  } else { // TERM_RENDERER_THEME_DARK or TERM_RENDERER_THEME_AUTO
    *out_r = TERMINAL_COLOR_THEME_DARK_BG_R;
    *out_g = TERMINAL_COLOR_THEME_DARK_BG_G;
    *out_b = TERMINAL_COLOR_THEME_DARK_BG_B;
  }
}

References TERMINAL_COLOR_THEME_DARK_BG_B, TERMINAL_COLOR_THEME_DARK_BG_G, TERMINAL_COLOR_THEME_DARK_BG_R, TERMINAL_COLOR_THEME_LIGHT_BG_B, TERMINAL_COLOR_THEME_LIGHT_BG_G, and TERMINAL_COLOR_THEME_LIGHT_BG_R.

Referenced by term_renderer_feed().

terminal_get_default_foreground_color()

void terminal_get_default_foreground_color	(	int	theme,
		uint8_t *	out_r,
		uint8_t *	out_g,
		uint8_t *	out_b
	)

Get theme-aware default foreground color for the renderer.

Get theme-aware default foreground color for pixel renderers.

Parameters

theme	Terminal theme (dark or light)
out_r	Pointer to store red component (0-255)
out_g	Pointer to store green component (0-255)
out_b	Pointer to store blue component (0-255)

Returns appropriate default text color based on terminal theme. Both Linux and macOS renderers use this for consistent color selection.

Definition at line 269 of file platform/terminal.c.

                                                                                                      {
  if (theme == 1) { // TERM_RENDERER_THEME_LIGHT
    *out_r = TERMINAL_COLOR_THEME_LIGHT_FG_R;
    *out_g = TERMINAL_COLOR_THEME_LIGHT_FG_G;
    *out_b = TERMINAL_COLOR_THEME_LIGHT_FG_B;
  } else { // TERM_RENDERER_THEME_DARK or TERM_RENDERER_THEME_AUTO
    *out_r = TERMINAL_COLOR_THEME_DARK_FG_R;
    *out_g = TERMINAL_COLOR_THEME_DARK_FG_G;
    *out_b = TERMINAL_COLOR_THEME_DARK_FG_B;
  }
}

References TERMINAL_COLOR_THEME_DARK_FG_B, TERMINAL_COLOR_THEME_DARK_FG_G, TERMINAL_COLOR_THEME_DARK_FG_R, TERMINAL_COLOR_THEME_LIGHT_FG_B, TERMINAL_COLOR_THEME_LIGHT_FG_G, and TERMINAL_COLOR_THEME_LIGHT_FG_R.

Referenced by term_renderer_feed().

terminal_get_effective_color_mode()

terminal_color_mode_t terminal_get_effective_color_mode

(

void

)

Get current color mode considering all overrides.

Determines effective color mode by checking:

1. –color flag (force enable)
2. –color-mode option (none/16/256/truecolor)
3. Terminal capability detection

Returns

Effective terminal_color_mode_t to use

Definition at line 107 of file platform/terminal.c.

                                                              {
  // If colors are disabled entirely by terminal_should_color_output(), return NONE
  if (!terminal_should_color_output(STDOUT_FILENO)) {
    return TERM_COLOR_NONE;
  }
 
  // If --color-mode is set to specific value, use it
  terminal_color_mode_t color_mode = GET_OPTION(color_mode);
  if (color_mode != TERM_COLOR_AUTO) {
    return color_mode;
  }
 
  // Otherwise auto-detect from terminal capabilities
  // For now, return the detected color mode from terminal capabilities
  // This will be used by apply_color_mode_override() if needed
  return TERM_COLOR_AUTO; // Let the calling code handle auto-detection
}

References GET_OPTION, TERM_COLOR_AUTO, TERM_COLOR_NONE, and terminal_should_color_output().

terminal_get_effective_height()

unsigned short int terminal_get_effective_height

(

void

)

Get effective terminal height with fallback priority.

Returns height in priority order:

1. Option height if set to non-zero value
2. Detected terminal height
3. OPT_HEIGHT_DEFAULT fallback

Definition at line 179 of file platform/terminal.c.

                                                       {
  int height = GET_OPTION(height);
 
  // If height option is explicitly set to non-zero, use it
  if (height > 0) {
    return (unsigned short int)height;
  }
 
  // Try to detect actual terminal height
  terminal_size_t size;
  if (terminal_get_size(&size) == ASCIICHAT_OK && size.rows > 0) {
    return (unsigned short int)size.rows;
  }
 
  // Fallback to default
  return OPT_HEIGHT_DEFAULT;
}

References ASCIICHAT_OK, GET_OPTION, OPT_HEIGHT_DEFAULT, terminal_size_t::rows, and terminal_get_size().

Referenced by keyboard_help_render(), mirror_convert_frame(), protocol_start_connection(), server_connection_establish(), session_display_convert_to_ascii(), session_display_create(), session_render_loop(), session_settings_init(), splash_intro_start(), and update_banner_show_prompt().

terminal_get_effective_width()

unsigned short int terminal_get_effective_width

(

void

)

Get effective terminal width with fallback priority.

Returns width in priority order:

1. Option width if set to non-zero value
2. Detected terminal width
3. OPT_WIDTH_DEFAULT fallback

Definition at line 153 of file platform/terminal.c.

                                                      {
  int width = GET_OPTION(width);
 
  // If width option is explicitly set to non-zero, use it
  if (width > 0) {
    return (unsigned short int)width;
  }
 
  // Try to detect actual terminal width
  terminal_size_t size;
  if (terminal_get_size(&size) == ASCIICHAT_OK && size.cols > 0) {
    return (unsigned short int)size.cols;
  }
 
  // Fallback to default
  return OPT_WIDTH_DEFAULT;
}

References ASCIICHAT_OK, terminal_size_t::cols, GET_OPTION, OPT_WIDTH_DEFAULT, and terminal_get_size().

Referenced by keyboard_help_render(), mirror_convert_frame(), protocol_start_connection(), server_connection_establish(), session_display_convert_to_ascii(), session_display_create(), session_display_render_fps_overlay(), session_render_loop(), session_settings_init(), splash_intro_start(), and update_banner_show_prompt().

terminal_is_interactive()

bool terminal_is_interactive

(

void

)

Check if the session is fully interactive.

Returns

true if BOTH stdin AND stdout are TTYs, false otherwise

Determines whether the session is fully interactive (user at terminal). Returns true only when BOTH stdin and stdout are connected to TTYs.

Use this to decide whether:

• User prompts and interactive input should be shown
• Splash screens and animations should be displayed
• Frame padding should be enabled
• Password prompts are appropriate

Examples:

• ascii-chat mirror in terminal → true (interactive)
• ascii-chat mirror | less → false (stdout piped)
• cat file | ascii-chat client → false (stdin piped)
• ascii-chat client < input.txt > output.txt → false (both piped)

Note

Equivalent to: terminal_is_stdin_tty() && terminal_is_stdout_tty()

Used for enabling interactive features (prompts, padding, splash)

Snapshot mode is checked separately via GET_OPTION(snapshot_mode)

Definition at line 141 of file platform/terminal.c.

                                   {
  return terminal_is_stdin_tty() && terminal_is_stdout_tty();
}

References terminal_is_stdin_tty(), and terminal_is_stdout_tty().

Referenced by main(), options_init(), session_display_write_ascii(), session_render_loop(), session_server_like_run(), terminal_can_prompt_user(), terminal_choose_log_fd(), threaded_send_terminal_size_with_auto_detect(), ui_status_display(), and ui_status_display_interactive().

terminal_is_piped_output()

bool terminal_is_piped_output

(

void

)

Check if stdout is piped or redirected.

Returns

true if stdout is piped/redirected, false if connected to TTY

Determines whether standard output is being piped or redirected to a file. This is the logical inverse of terminal_is_stdout_tty().

Use this to decide whether:

• Logs should be forced to stderr (to avoid corrupting piped output)
• Frame padding should be disabled
• Clean, parseable output should be preferred

Examples:

• ascii-chat mirror > output.txt → true (redirected)
• ascii-chat client | grep pattern → true (piped)
• ascii-chat mirror in terminal → false (TTY)

Note

Equivalent to: !terminal_is_stdout_tty()

Common pattern: force stderr when piped to prevent data corruption

Definition at line 197 of file platform/terminal.c.

                                    {
  return !terminal_is_stdout_tty();
}

References terminal_is_stdout_tty().

Referenced by asciichat_shared_init(), log_init(), and terminal_should_force_stderr().

terminal_is_stderr_tty()

bool terminal_is_stderr_tty

(

void

)

Check if stderr is connected to a TTY.

Returns

true if stderr is a TTY, false otherwise

Determines whether standard error is connected to a terminal device. Returns false when stderr is piped or redirected to a file.

Use this to decide whether diagnostic messages should include colors.

Note

Wrapper around platform_isatty(STDERR_FILENO) for clarity

stderr is often a TTY even when stdout is piped

Definition at line 137 of file platform/terminal.c.

                                  {
  return platform_isatty(STDERR_FILENO) != 0;
}

References platform_isatty().

terminal_is_stdin_tty()

bool terminal_is_stdin_tty

(

void

)

Check if stdin is connected to a TTY.

Returns

true if stdin is a TTY (can read interactive input), false otherwise

Determines whether standard input is connected to a terminal device. Returns false when stdin is piped or redirected from a file.

Use this to decide whether interactive input (prompts, keyboard events) is possible.

Note

Wrapper around platform_isatty(STDIN_FILENO) for clarity

Returns false in non-interactive environments (CI, scripts, pipes)

Definition at line 129 of file platform/terminal.c.

                                 {
  return platform_isatty(STDIN_FILENO) != 0;
}

References platform_isatty().

Referenced by display_init(), session_client_like_run(), session_display_create(), session_render_loop(), terminal_is_interactive(), and threaded_send_terminal_size_with_auto_detect().

terminal_is_stdout_tty()

bool terminal_is_stdout_tty

(

void

)

Check if stdout is connected to a TTY.

Returns

true if stdout is a TTY (not piped/redirected), false otherwise

Determines whether standard output is connected to a terminal device. Returns false when stdout is piped or redirected to a file.

Use this to decide whether:

• Terminal control sequences (colors, cursor movement) should be used
• Output padding/formatting should be applied
• Progress bars or animations should be shown

Note

Wrapper around platform_isatty(STDOUT_FILENO) for clarity

Returns false in piped contexts (e.g., ascii-chat client | less)

Definition at line 133 of file platform/terminal.c.

                                  {
  return platform_isatty(STDOUT_FILENO) != 0;
}

References platform_isatty().

Referenced by session_client_like_run(), session_display_create(), session_render_loop(), terminal_is_interactive(), terminal_is_piped_output(), and threaded_send_terminal_size_with_auto_detect().

terminal_should_color_output()

bool terminal_should_color_output

(

int

fd

)

Determine if color output should be used.

Priority order:

1. If –color flag is set → ALWAYS use colors (force override)
2. If CLAUDECODE env var is set → NEVER use colors (LLM automation)
3. If output is not a TTY (piping) → NO colors
4. If –color-mode=none → NO colors (user choice)
5. Otherwise → Use colors

Parameters

fd	File descriptor to check (STDOUT_FILENO or STDERR_FILENO)

Returns

true if colors should be used, false otherwise

Definition at line 31 of file platform/terminal.c.

                                          {
  // Check color_mode setting - if explicitly set to NONE, disable colors
  int color_mode = GET_OPTION(color_mode);
  if (color_mode == COLOR_MODE_NONE) {
    return false; // Color mode explicitly disabled
  }
 
  // Get current color setting (auto/true/false)
  int color_setting = GET_OPTION(color);
 
  // Priority 1: --color=true - Force colors ON (overrides everything)
  if (color_setting == COLOR_SETTING_TRUE) {
    return true; // ALWAYS colorize
  }
 
  // Priority 2: --color=false - Force colors OFF (overrides everything)
  if (color_setting == COLOR_SETTING_FALSE) {
    return false; // NEVER colorize
  }
 
  // Priority 3: --color=auto (default) - Smart detection
  // Special case: Show colors for --help and --version even if not a TTY
  // Check for help/version in global argv (set by main.c early)
  if (g_argc > 1 && g_argv) {
    for (int i = 1; i < g_argc; i++) {
      if (strcmp(g_argv[i], "--help") == 0 || strcmp(g_argv[i], "-h") == 0 || strcmp(g_argv[i], "--version") == 0 ||
          strcmp(g_argv[i], "-v") == 0 || strcmp(g_argv[i], "--show-capabilities") == 0) {
        // For help/version/show-capabilities, use colors only if output is a TTY
        // (respect piping convention: no colors unless --color=true)
        int is_tty = platform_isatty(fd);
        if (!is_tty) {
          // Piping detected - fall through to check environment overrides
          break;
        }
 
        // It's a TTY - show colors for help. Check environment overrides.
        if (SAFE_GETENV("ASCII_CHAT_COLOR")) {
          return true; // ASCII_CHAT_COLOR env var forces colors
        }
 
        // CLAUDECODE environment variable (LLM automation) - disable colors
        if (SAFE_GETENV("CLAUDECODE")) {
          return false; // NO colors in Claude Code environment
        }
 
        // For help output to TTY, show colors by default
        return true;
      }
    }
  }
 
  // Check environment variable overrides
  if (SAFE_GETENV("ASCII_CHAT_COLOR")) {
    return true; // ASCII_CHAT_COLOR env var forces colors
  }
 
  // CLAUDECODE environment variable (LLM automation) - disable colors
  if (SAFE_GETENV("CLAUDECODE")) {
    return false; // NO colors in Claude Code environment
  }
 
  // Check if output is a TTY (pipe detection)
  // Default: Use colors only if we have TTY and no environment overrides
  return platform_isatty(fd);
}

References COLOR_MODE_NONE, COLOR_SETTING_FALSE, COLOR_SETTING_TRUE, g_argc, g_argv, GET_OPTION, platform_isatty(), and SAFE_GETENV.

Referenced by action_show_capabilities_immediate(), action_show_version(), colored_string(), colorize_log_message(), log_plain_msg(), and terminal_get_effective_color_mode().

terminal_should_force_stderr()

bool terminal_should_force_stderr

(

void

)

Determine if logs should be forced to stderr.

Returns

true if logs should go to stderr only, false if stdout is acceptable

Determines whether logging output should be forced to stderr instead of stdout. Returns true when stdout is piped/redirected (to avoid corrupting output data).

Use this to decide whether to call log_set_force_stderr(true).

Logic:

1. If stdout is piped/redirected → force stderr (true)
2. If in TESTING environment → allow stdout (false)
3. Otherwise → allow stdout (false)

Examples:

• ascii-chat mirror > frames.txt → true (don't corrupt frame data)
• ascii-chat mirror in terminal → false (stdout is fine)
• TESTING=1 ascii-chat mirror → false (tests may capture stdout)

Note

This prevents logs from corrupting piped ASCII frame data

TESTING environment variable bypasses this for test environments

Typical usage: if (terminal_should_force_stderr()) log_set_force_stderr(true);

Definition at line 201 of file platform/terminal.c.

                                        {
  // If stdout is piped/redirected, force logs to stderr to avoid corruption
  if (terminal_is_piped_output()) {
    // Unless in TESTING environment where test framework may capture stdout
    const char *testing = SAFE_GETENV("TESTING");
    if (testing && strcmp(testing, "1") == 0) {
      // NOLINTNEXTLINE(readability-simplify-boolean-expr) - Intentional logic for test environment override
      return false;
    }
    return true; // Force stderr when piped
  }
  return false; // stdout is TTY, no need to force stderr
}

References SAFE_GETENV, and terminal_is_piped_output().

Referenced by main(), session_client_like_run(), and session_display_create().

terminal_should_use_control_sequences()

bool terminal_should_use_control_sequences

(

int

fd

)

Check if terminal control sequences should be used for the given fd.

Parameters

fd	File descriptor to check

Returns

true if terminal control sequences should be used, false otherwise

This function determines whether to send terminal POSITIONING and CONTROL sequences (cursor home, clear screen, hide cursor, etc.) which should only be sent to TTY and never to pipes/redirected output.

Note: This does NOT control ANSI COLOR CODES, which are controlled by –color-mode option and may be sent to pipes if explicitly requested.

Definition at line 315 of file platform/terminal.c.

                                                   {
  if (fd < 0) {
    return false;
  }
  if (GET_OPTION(snapshot_mode)) {
    return false;
  }
  const char *testing_env = SAFE_GETENV("TESTING");
  if (testing_env != NULL) {
    return false;
  }
  return platform_isatty(fd) != 0;
}

References GET_OPTION, platform_isatty(), and SAFE_GETENV.

Referenced by ascii_write(), ascii_write_destroy(), and ascii_write_init().