Environment variables

AiCIPPYTUI reads these values from process.env. Bun loads .env automatically. With Node.js, use the shell or Node’s environment-file support.

AiCIPPYTUI parses most registered values on first use and caches the result. Set each value before the read time in the tables below. Registered boolean values treat true, 1, on, and yes as true without case sensitivity. Other explicit values are false.

The tables list explicit AiCIPPYTUI settings. Terminal and clipboard detection also read host variables such as TERM, TMUX, ZELLIJ, SSH variables, DISPLAY, and WAYLAND_DISPLAY. Those values describe the host environment. They are not AiCIPPYTUI configuration keys. Read Terminal capabilities for detection.

Stable configuration#

Variable	Type	Default	Read time	Purpose
`XDG_CONFIG_HOME`	`string`	`""`	First configuration lookup	Base directory for user-specific configuration files
`XDG_DATA_HOME`	`string`	`""`	First data lookup	Base directory for user-specific data files
`ATUI_PALETTE_IDLE_TIMEOUT_MS`	`number`	`300`	First palette query	Silence in milliseconds before palette fallback
`AICIPPYTUI_FORCE_WCWIDTH`	presence	unset	Renderer creation	Use wcwidth for character width calculations
`AICIPPYTUI_FORCE_UNICODE`	presence	unset	Renderer creation	Force Mode 2026 Unicode support
`AICIPPYTUI_FORCE_NOZWJ`	presence	unset	Renderer creation	Use the no_zwj width method
`AICIPPYTUI_GRAPHICS`	`string`	unset, automatic	Renderer creation	Control Kitty and Sixel detection
`AICIPPYTUI_IMAGE_PROTOCOL`	`string`	`"auto"`	Renderer creation	Select `auto`, `kitty`, `sixel`, or `blocks`
`AICIPPYTUI_FORCE_EXPLICIT_WIDTH`	`string`	unset	Renderer creation	Force or disable explicit-width detection
`AICIPPYTUI_NOTIFICATION_PROTOCOL`	`string`	unset, automatic	Renderer creation	Override the terminal notification protocol
`AICIPPYTUI_NOTIFICATIONS`	`string`	unset, enabled	Renderer creation	Disable terminal notification detection
`ATUI_USE_CONSOLE`	`boolean`	`true`	Renderer console activation	Enable global `console.*` capture
`ATUI_USE_ALTERNATE_SCREEN`	`boolean`	unset	Renderer creation	Override `screenMode`
`ATUI_OVERRIDE_STDOUT`	`boolean`	unset	Renderer creation	Override `externalOutputMode`
`CELL_ASPECT_RATIO`	`number`	computed	`ThreeCliRenderer` creation	Override the Three.js cell aspect ratio

AICIPPYTUI_FORCE_WCWIDTH, AICIPPYTUI_FORCE_UNICODE, and AICIPPYTUI_FORCE_NOZWJ are native presence flags. Any value, including 0 or false, enables the override. Leave the variable unset to disable it.

AICIPPYTUI_GRAPHICS recognizes only lowercase false or 0 to disable graphics detection. Lowercase true or 1 keeps automatic detection. Other values do not change automatic behavior. AICIPPYTUI_IMAGE_PROTOCOL is case-insensitive. Invalid values keep auto. Forcing an unsupported protocol can produce incorrect output.

AICIPPYTUI_FORCE_EXPLICIT_WIDTH=true or 1 forces explicit-width support. false or 0 disables it and skips OSC 66 queries on older terminals.

AICIPPYTUI_NOTIFICATION_PROTOCOL accepts osc9, osc777, osc99, and none without case sensitivity. 0, false, and off also disable notifications. 1, true, and on keep automatic detection. Use an override only when terminal detection selects the wrong protocol. AICIPPYTUI_NOTIFICATIONS=0, false, or off disables notifications without changing other capability detection.

ATUI_PALETTE_IDLE_TIMEOUT_MS bounds palette detection when a terminal reports OSC support but does not answer color queries. ATUI_USE_CONSOLE=false disables global console.* capture. The consoleMode renderer option changes only the overlay surface.

When set, ATUI_USE_ALTERNATE_SCREEN overrides screenMode. A true value forces "alternate-screen". Any other explicit value forces "main-screen". When set, ATUI_OVERRIDE_STDOUT overrides externalOutputMode. A true value captures stdout only in "split-footer". Any other explicit value forces passthrough.

Diagnostics#

Variable	Type	Default	Read time	Purpose
`ATUI_TS_STYLE_WARN`	`string`	`false`	First style lookup	Warn about missing Tree-sitter syntax styles
`ATUI_DEBUG_FFI`	`boolean`	`false`	First FFI use	Enable FFI debug logging
`ATUI_TRACE_FFI`	`boolean`	`false`	First FFI use	Enable FFI tracing
`ATUI_SHOW_STATS`	`boolean`	`false`	Renderer creation	Show the renderer stats overlay at startup
`SHOW_CONSOLE`	`boolean`	`false`	Renderer creation	Open the built-in console overlay at startup
`ATUI_DUMP_CAPTURES`	`boolean`	`false`	Renderer exit handler	Dump captured stdout and console caches from that handler
`ATUI_NO_NATIVE_RENDER`	`boolean`	`false`	Renderer creation	Skip the Zig native frame renderer

ATUI_TS_STYLE_WARN behaves like a presence string. Any explicit nonempty value, including false, enables warnings.

ATUI_NO_NATIVE_RENDER does not stop the render loop. In "split-footer" mode, output flushing can still write ANSI cursor movement and clear sequences. ATUI_DUMP_CAPTURES runs from the renderer exit handler. Calling renderer.destroy() directly does not trigger that dump by itself.

Build-time and startup values#

Variable	Type	Default	Required timing	Purpose
`AICIPPYTUI_LIBC`	`string`	unset, glibc	Before the first Core import	Select `glibc` or `musl` on Linux
`ATUI_ASSET_ROOT`	`string`	`""`	Before bundled Core code executes	Relocate AiCIPPYTUI runtime assets
`ATUI_TREE_SITTER_WORKER_PATH`	`string`	`""`	Before the first Tree-sitter worker starts	Override the parser worker entry

`AICIPPYTUI_LIBC`#

On Linux, an unset value, an empty value, or glibc selects the glibc package. The value musl selects the musl package. Any other nonempty value throws. Set the value before the first Core import. A standalone Bun build can define process.env.AICIPPYTUI_LIBC at build time so tree shaking keeps only the target branch. See Runtime and platform support and Standalone executables.

`ATUI_ASSET_ROOT`#

ATUI_ASSET_ROOT relocates the native library, parser worker, default parser assets, and Tree-sitter WASM. The value must be an absolute directory. Put every file beneath it with the exact key from getNodeAssets().

Set the variable before importing or executing bundled Core code. An empty value is unset. When a nonempty root is set, every requested asset must exist beneath it. A missing asset throws, and AiCIPPYTUI does not use a package-relative fallback. See Standalone executables.

`ATUI_TREE_SITTER_WORKER_PATH`#

Set the worker path before the first TreeSitterClient starts its worker. Setting it after Core import is valid if no Tree-sitter worker started. An explicit client workerPath option takes precedence over this variable.

Security-sensitive diagnostics#

Variable	Type	Default	Read time	Purpose
`ATUI_DEBUG`	`boolean`	`false`	Renderer creation	Retain raw input sequences for debugging
`ATUI_STDIN_LOG`	`string`	`""`	Renderer creation	Write the raw stdin byte stream to a file
`ATUI_GHOSTTY_LOG_LEVEL`	`string`	`""`	Native initialization	Forward scoped Ghostty logs through the normal AiCIPPYTUI logger

ATUI_STDIN_LOG=/tmp/aicippytui-stdin.bin records stdin before parsing. The renderer truncates the file when it starts and writes to it synchronously. The binary data can contain passwords and other sensitive input. Use this option only for short debugging sessions, and protect the recorded file. Treat ATUI_DEBUG input captures and ATUI_DUMP_CAPTURES output as sensitive data too.

ATUI_GHOSTTY_LOG_LEVEL accepts error, warn, info, or debug (err and warning are aliases). The selected level includes all more severe messages. Unset or invalid values disable Ghostty logs. Standard-library logs outside the recognized Ghostty scopes are always discarded.

Remote sessions#

A renderer with remote: true forwards no local environment keys to native terminal detection by default. Add only the required names to forwardEnvKeys. This rule prevents local terminal overrides from changing an unrelated remote terminal.

See Troubleshooting for errors related to native loading, runtime assets, terminal overrides, and Tree-sitter workers.