Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/RtlZeroMemory/Rezi/llms.txt

Use this file to discover all available pages before exploring further.

The Rezi backend detects terminal capabilities from environment variables to negotiate optimal rendering features. This ensures compatibility across terminal emulators and CI environments.

​
Detection Strategy

Terminal capabilities are detected at backend initialization:
  1. Read environment variables (TERM, COLORTERM, TERM_PROGRAM, etc.)
  2. Parse terminal profile from detected values
  3. Apply overrides from explicit environment variables
  4. Negotiate with engine to enable supported features
Location: packages/node/src/backend/terminalProfile.ts

​
Environment Variables

​
Core Variables

VariablePurposeExample Values
TERMTerminal typexterm-256color, screen-256color, dumb
COLORTERMColor supporttruecolor, 24bit
TERM_PROGRAMTerminal emulatoriTerm.app, vscode, Apple_Terminal
TERM_PROGRAM_VERSIONEmulator version3.4.0

​
CI Detection

VariableMeaning
CIGeneric CI environment
GITHUB_ACTIONSGitHub Actions
GITLAB_CIGitLab CI
CIRCLECICircleCI
TRAVISTravis CI
JENKINS_URLJenkins
CI behavior: Rezi disables mouse and focus tracking in CI environments by default.

​
Explicit Overrides

VariablePurposeValues
ZRUI_TRUECOLORForce truecolor1 (enable) / 0 (disable)
ZRUI_MOUSEForce mouse events1 (enable) / 0 (disable)
ZRUI_UNICODEForce Unicode1 (enable) / 0 (disable)
ZRUI_EMOJI_WIDTHEmoji width policywide / narrow
ZRUI_EMOJI_WIDTH_PROBEEnable probing1 (enable)

​
Terminal Capabilities

interface TerminalCaps {
  truecolor: boolean;  // 24-bit RGB color support
  unicode: boolean;    // Unicode rendering support
  mouse: boolean;      // Mouse event support
  focus: boolean;      // Focus tracking support
}

​
Truecolor Detection

Enabled when:
  • COLORTERM=truecolor or COLORTERM=24bit
  • TERM_PROGRAM is a known truecolor emulator (iTerm2, VS Code, Hyper, Alacritty, Kitty, WezTerm)
  • TERM contains truecolor or 24bit
Disabled when:
  • TERM=dumb
  • ZRUI_TRUECOLOR=0
Fallback: 256-color palette

​
Unicode Detection

Enabled when:
  • LANG or LC_ALL contains UTF-8 or utf8
  • TERM is not dumb
Disabled when:
  • TERM=dumb
  • ZRUI_UNICODE=0
Fallback: ASCII-only rendering

​
Mouse Detection

Enabled when:
  • Terminal is interactive (isatty)
  • Not in CI environment
  • TERM is not dumb
Disabled when:
  • CI=true (any CI)
  • TERM=dumb
  • ZRUI_MOUSE=0
Protocols supported:
  • SGR mouse encoding (preferred)
  • UTF-8 mouse encoding (fallback)
  • X10 mouse encoding (legacy)

​
Focus Tracking Detection

Enabled when:
  • Mouse events enabled
  • Terminal supports focus events (most modern emulators)
Disabled when:
  • Mouse disabled
  • CI environment

​
Known Terminal Profiles

​
iTerm2 (macOS)

Detected by: TERM_PROGRAM=iTerm.app Capabilities:
  • Truecolor: Yes
  • Unicode: Yes
  • Mouse: Yes
  • Focus: Yes
Notes: One of the most feature-complete terminals

​
VS Code Integrated Terminal

Detected by: TERM_PROGRAM=vscode Capabilities:
  • Truecolor: Yes
  • Unicode: Yes
  • Mouse: Yes
  • Focus: Yes
Notes: Based on xterm.js

​
Alacritty

Detected by: TERM=alacritty or TERM_PROGRAM=Alacritty Capabilities:
  • Truecolor: Yes
  • Unicode: Yes
  • Mouse: Yes
  • Focus: Yes
Notes: GPU-accelerated terminal

​
Kitty

Detected by: TERM=xterm-kitty Capabilities:
  • Truecolor: Yes
  • Unicode: Yes
  • Mouse: Yes
  • Focus: Yes
Notes: Supports advanced graphics protocol

​
WezTerm

Detected by: TERM_PROGRAM=WezTerm Capabilities:
  • Truecolor: Yes
  • Unicode: Yes
  • Mouse: Yes
  • Focus: Yes

​
Linux Console

Detected by: TERM=linux Capabilities:
  • Truecolor: No (256 colors)
  • Unicode: Limited
  • Mouse: No
  • Focus: No

​
tmux/screen

Detected by: TERM=screen* or TERM=tmux* Capabilities:
  • Truecolor: Depends on COLORTERM
  • Unicode: Yes (if parent terminal supports)
  • Mouse: Yes (if parent terminal supports)
  • Focus: Yes (if parent terminal supports)
Notes: Acts as multiplexer; capabilities depend on parent terminal

​
CI Environments

Detected by: CI=true Capabilities:
  • Truecolor: No (256 colors for safety)
  • Unicode: Yes
  • Mouse: No
  • Focus: No
Notes: Conservative defaults for CI logs

​
Capability Negotiation

The backend negotiates capabilities with the engine: 
function negotiateCapabilities(
  detected: TerminalCaps,
  userConfig?: Partial<TerminalCaps>
): TerminalCaps {
  return {
    truecolor: userConfig?.truecolor ?? detected.truecolor,
    unicode: userConfig?.unicode ?? detected.unicode,
    mouse: userConfig?.mouse ?? detected.mouse,
    focus: userConfig?.focus ?? detected.focus,
  };
}
Priority:
  1. User config (explicit overrides)
  2. Environment variable overrides (ZRUI_*)
  3. Detected capabilities
  4. Safe defaults

​
Emoji Width Policy

Emoji width detection aligns TypeScript layout with native rendering:

​
Detection Strategy

function resolveEmojiWidthPolicy(): "wide" | "narrow" {
  // 1. Explicit override
  if (process.env.ZRUI_EMOJI_WIDTH === "wide") return "wide";
  if (process.env.ZRUI_EMOJI_WIDTH === "narrow") return "narrow";
  
  // 2. Terminal probing (if enabled)
  if (process.env.ZRUI_EMOJI_WIDTH_PROBE === "1") {
    return probeEmojiWidth();
  }
  
  // 3. Known terminal defaults
  if (process.env.TERM_PROGRAM === "iTerm.app") return "wide";
  if (process.env.TERM_PROGRAM === "vscode") return "narrow";
  
  // 4. Safe default
  return "wide";
}
Location: packages/node/src/backend/emojiWidthPolicy.ts

​
Probing (Experimental)

When ZRUI_EMOJI_WIDTH_PROBE=1:
  1. Write test emoji to terminal
  2. Query cursor position
  3. Measure cell width consumed
  4. Return "wide" if 2 cells, "narrow" if 1 cell
Caveats:
  • Requires interactive terminal
  • Adds ~10-50ms latency to startup
  • May not work in all emulators

​
Default Capabilities

When detection fails or no terminal is attached: 
const DEFAULT_TERMINAL_CAPS: TerminalCaps = {
  truecolor: true,
  unicode: true,
  mouse: true,
  focus: true,
};
Rationale: Optimistic defaults for modern terminals. Degrades gracefully if features unsupported.

​
Testing Terminal Detection

Test different profiles: 
# Force minimal capabilities
TERM=dumb npm start

# Force 256-color mode
TERM=xterm-256color COLORTERM= npm start

# Simulate CI environment
CI=true npm start

# Test specific emulator
TERM_PROGRAM=vscode npm start

Build docs developers (and LLMs) love

Get started for freeTalk to us