tui schema (1-150)

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

TUI configuration — terminal dashboard settings.

Field path	Type	Required	Default	Canonical description
`tui`	`section`	optional		TUI configuration — terminal dashboard settings.
└ `tui.graphics`	`map`	optional		Graphics rendering configuration.
└ `tui.graphics.enabled`	`bool`	optional	true	Whether bitmap graphics rendering is enabled.
└ `tui.graphics.tmux_passthrough`	`bool`	optional	true	Wrap kitty APC payloads in tmux passthrough.
└ `tui.graphics.force`	`bool`	optional	false	Force kitty graphics regardless of detection.
└ `tui.graphics.animations`	`bool`	optional	true	Enable kitty looping/animation path.
└ `tui.graphics.target_fps`	`u16`	optional	30	Target wall-clock animation frame rate for bitmap graphics.
└ `tui.graphics.mode`	`string`	optional	auto	Image transport: auto, memory, or stream.
└ `tui.graphics.line_height`	`f64`	optional	1.0	Line-height multiplier for multi-row image segments.
└ `tui.graphics.batch_uploads`	`bool`	optional	true	Batch kitty graphics upload writes within one upload pass.
└ `tui.graphics.perf_logging`	`bool`	optional	false	Persist sampled TUI kitty-graphics perf events to the daemon perf_events store and emit verbose graphics/perf lines to tui.log. Default off to avoid daemon.db bloat; enable for benchmarking/optimization.
└ `tui.graphics.detailed_perf_telemetry`	`bool`	optional	true	Enable detailed per-category graphics performance telemetry.
└ `tui.graphics.image_source_cache`	`bool`	optional	true	Cache decoded/scaled background source images in memory.
└ `tui.graphics.scaled_background_cache`	`bool`	optional	true	Quantize scalable background render sizes into reusable cache buckets.
└ `tui.graphics.scaled_background_cache_max_px`	`u32`	optional	1280	Longest rendered edge for scaled background cache buckets.
└ `tui.graphics.surface_upload_dedupe`	`bool`	optional	true	Skip re-upload when surface bitmap bytes are unchanged.
└ `tui.graphics.cross_surface_image_sharing`	`bool`	optional	false	Reuse one uploaded image across surfaces with identical bitmaps (distinct per-surface placements). Opt-in upload-layer sharing for many identical-background panels; pairs with scaled_background_cache. Default false.
└ `tui.graphics.active_animation_only`	`bool`	optional	true	Only redraw on animation timer ticks when animated surfaces are visible.
└ `tui.graphics.show_fps`	`bool`	optional	false	Show real-time FPS counter in the status bar.
└ `tui.graphics.render_scale`	`u8`	optional	2	Bitmap raster scale multiplier for kitty graphics surfaces.
└ `tui.graphics.gpu_rendering`	`bool`	optional	false	Enable offscreen GPU compositing for eligible graphics surfaces.
└ `tui.graphics.gpu_backend`	`string`	optional	default	Requested backend for offscreen GPU compositing.
└ `tui.graphics.format`	`string`	optional	pnga	Lossless Kitty upload encoding: pnga (default), rgba (raw f=32), or auto (PNG with verified-local raw backgrounds).
└ `tui.graphics.delete_retained_on_retire`	`bool`	optional	false	Diagnostic mitigation: full-delete retained images when a surface retires. Slower; default false.
└ `tui.graphics.quality`	`f64`	optional	1.0	Graphics quality level 0.0–1.0 (1.0 = lossless).
└ `tui.graphics.compression`	`f64`	optional		Deprecated alias for quality. quality = 1.0 - compression.
└ `tui.graphics.disable_on_drag`	`bool`	optional	false	Temporarily disable kitty graphics during mouse drag resize.
└ `tui.graphics.disable_on_scroll`	`bool`	optional	false	Temporarily disable kitty graphics during scroll events.
└ `tui.graphics.disable_on_resize`	`bool`	optional	true	Temporarily disable kitty graphics during terminal resize.
└ `tui.graphics.resize_debounce_ms`	`u64`	optional	1000	Debounce in ms before restoring graphics after terminal resize.
└ `tui.graphics.defer_initial_frames`	`u32`	optional	0	Number of initial frames to render in text-only mode before enabling bitmap graphics. Default 0 (disabled).
└ `tui.graphics.animation_overrides`	`map[string, bool]`	optional		Per-element animation overrides keyed by element type (borders, background, status_icons, etc.).
└ `tui.graphics.draw_behind_cell_background`	`bool`	optional	true	Offset negative z-index to render behind non-default cell backgrounds.
└ `tui.graphics.max_uploads_per_frame`	`usize`	optional	4	Maximum native-animation plus regular-bitmap full kitty graphics uploads per frame. 0 = unlimited. Limits main-thread blocking.
└ `tui.graphics.max_batch_wire_bytes`	`usize`	optional	262144	Maximum wire bytes per batch write before flushing. 0 = unlimited.
└ `tui.graphics.max_retained_total_bytes`	`usize`	optional	33554432	Maximum total retained-image bytes across all surfaces before cross-surface LRU eviction. Raising it avoids delete<->upload eviction thrash/flicker with many agents open. 0 = unlimited.
└ `tui.graphics.animation_upload_throttle`	`bool`	optional	true	Enable per-frame upload budgeting and batch chunking for animation frames.
└ `tui.graphics.cursor`	`map`	optional		Kitty graphics cursor glow effect configuration.
└ `tui.graphics.cursor.color`	`string`	optional		Glow color source (hex or null for auto).
└ `tui.graphics.cursor.radius`	`u32`	optional	3	Glow spread radius in cells.
└ `tui.graphics.cursor.radius_y`	`u32`	optional	1	Vertical glow spread radius in cells.
└ `tui.graphics.cursor.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.sparkline`	`map`	optional		Kitty graphics sparkline configuration.
└ `tui.graphics.sparkline.enabled`	`bool`	optional	true	Whether bitmap sparklines are enabled.
└ `tui.graphics.sparkline.style`	`string`	optional	smooth	Sparkline rendering style: smooth, stepped, bar.
└ `tui.graphics.sparkline.glow`	`bool`	optional	false	Enable glow effect on sparkline segments.
└ `tui.graphics.sparkline.glow_radius`	`u32`	optional	2	Glow spread radius for sparkline segments.
└ `tui.graphics.sparkline.glow_intensity`	`f64`	optional	0.3	Glow intensity for sparkline segments.
└ `tui.graphics.tint`	`string`	optional		Background tint color: hex (#rrggbb), match_border, or colorN.
└ `tui.graphics.tint_intensity`	`f64`	optional	0.15	Background tint blend intensity 0.0–1.0.
└ `tui.graphics.background_style`	`string`	optional	none	Background fill style: none, solid, or gradient.
└ `tui.graphics.background_opacity`	`f64`	optional	1.0	Background alpha multiplier for bitmap panel fills.
└ `tui.graphics.background_contrast`	`f64`	optional	1.08	Alternate background gradient brightness multiplier.
└ `tui.graphics.background_angle`	`f64`	optional	35.0	Gradient direction in degrees for bitmap panel fills.
└ `tui.graphics.background_animate`	`bool`	optional	false	Scroll the background gradient when animations are enabled.
└ `tui.graphics.background_animation_speed`	`f64`	optional	0.25	Background animation speed in cycles per second.
└ `tui.graphics.animation_speed`	`f64`	optional	0.25	Border animation speed in cycles per second, using the same units as background_animation_speed.
└ `tui.graphics.animation_frames`	`u16`	optional	96	Number of temporal phase buckets per animation cycle; speed controls cycle duration. Values above 255 require 16-bit-capable clients.
└ `tui.graphics.animation_style`	`string`	optional	pulse	Border animation style: pulse or rotating_gradient.
└ `tui.graphics.border_animation_style`	`string`	optional		Border-specific animation style override: pulse or rotating_gradient. Overrides animation_style for border perimeters only.
└ `tui.graphics.border_spacing`	`u32`	optional	100	Bias for how far strokes sit toward the outer edge of a border cell.
└ `tui.graphics.line_thickness`	`f64`	optional	1.0	Stroke thickness multiplier for bitmap borders.
└ `tui.graphics.pattern`	`string`	optional	solid	Stroke pattern: solid, diagonal_stripes, checkerboard, dashed, dotted, houndstooth, bevel, etched.
└ `tui.graphics.pattern_size`	`u32`	optional	3	Stroke pattern tile size in pixels at 1x scale.
└ `tui.graphics.pattern_opacity`	`f64`	optional	0.72	Alternate pattern alpha multiplier.
└ `tui.graphics.pattern_contrast`	`f64`	optional	0.86	Alternate pattern brightness multiplier.
└ `tui.graphics.glow`	`bool`	optional	false	Enable glow effect on bitmap borders.
└ `tui.graphics.glow_radius`	`u32`	optional	4	Glow spread radius in pixels at 1x scale.
└ `tui.graphics.glow_intensity`	`f64`	optional	0.35	Glow intensity multiplier.
└ `tui.graphics.pulse_low`	`f64`	optional	0.0	Minimum normalized oscillation point for animated border effects.
└ `tui.graphics.pulse_high`	`f64`	optional	1.0	Maximum normalized oscillation point for animated border effects.
└ `tui.graphics.shadow_intensity`	`f64`	optional	0.0	Drop-shadow intensity behind the bitmap stroke.
└ `tui.graphics.stroke_intensity`	`f64`	optional	0.0	Outline/stroke intensity around the bitmap stroke.
└ `tui.graphics.corner_radius`	`u32`	optional	4	Rounded corner radius in pixels at 1x scale.
└ `tui.graphics.title_gap_terminator`	`string`	optional	tick	Terminator style used when carving title gaps from top border runs: none, tick, tack, box, pill.
└ `tui.graphics.header_decoration_style`	`string`	optional	none	Text decoration style for header/title kitty surfaces: none, glow, box, pill, glass_pill.
└ `tui.graphics.header_decoration_thickness`	`f64`	optional	0.5	Thickness multiplier for header decoration strokes, relative to border thickness.
└ `tui.graphics.header_decoration_radius`	`u32`	optional	3	Corner radius for header decoration box/pill containers.
└ `tui.graphics.header_decoration_glow_radius`	`u32`	optional	2	Glow spread radius for header text glow decoration.
└ `tui.graphics.header_decoration_opacity`	`f64`	optional	0.6	Opacity multiplier for header decoration surfaces.
└ `tui.graphics.span_glow_enabled`	`bool`	optional	true	Enable span-level glow effects on header/footer text elements.
└ `tui.graphics.span_glow_radius`	`u32`	optional	2	Glow spread radius for span-level glow effects in cells.
└ `tui.graphics.span_glow_intensity`	`f64`	optional	0.35	Opacity/intensity multiplier for span-level glow effects.
└ `tui.graphics.span_glow_bleed_x`	`u16`	optional	2	Extra columns the glow image extends beyond text cells on each side.
└ `tui.graphics.span_glow_bleed_y`	`u16`	optional	1	Extra rows the glow image extends beyond text cells on each side.
└ `tui.graphics.foreground_color`	`string`	optional		Foreground color override for text/chrome in this role (hex or colorN).
└ `tui.graphics.background_color`	`string`	optional		Background color override for panel fills in this role (hex or colorN).
└ `tui.graphics.background_overlay`	`string`	optional	none	Composable overlay effect on top of background: none or scanlines.
└ `tui.graphics.background_overlay_opacity`	`f64`	optional	0.15	Overlay opacity/intensity 0.0–1.0.
└ `tui.graphics.background_image`	`string \| list[string]`	optional		Background image path or list of paths for rotation.
└ `tui.graphics.background_position`	`string`	optional	center	Background image position anchor: center, top, bottom, left, right, etc..
└ `tui.graphics.background_scale`	`string`	optional	fit_width	Background image scale mode: fit_width, fit_height, fit_longest, fit_shortest.
└ `tui.graphics.background_width`	`string`	optional		Explicit background image width: <n>px or <n>cols. Preserves aspect ratio.
└ `tui.graphics.background_height`	`string`	optional		Explicit background image height: <n>px, <n>rows, or <n>cols. Preserves aspect ratio.
└ `tui.graphics.background_scale_factor`	`f64`	optional	1.0	Additional scale factor applied after scale mode.
└ `tui.graphics.background_offset_x`	`f64`	optional	0.0	Horizontal offset as percentage of container width.
└ `tui.graphics.background_offset_y`	`f64`	optional	0.0	Vertical offset as percentage of container height.
└ `tui.graphics.background_offset_x_image`	`f64`	optional	0.0	Horizontal offset as percentage of rendered image width.
└ `tui.graphics.background_offset_y_image`	`f64`	optional	0.0	Vertical offset as percentage of rendered image height.
└ `tui.graphics.background_rotation`	`string`	optional	cycle	Rotation mode for multi-image backgrounds: cycle or random.
└ `tui.graphics.blend_mode`	`string`	optional	split	Border join blend mode: split or overlap.
└ `tui.graphics.blending_mode`	`string`	optional	normal	Composition blending mode for multi-layer surfaces: normal, multiply, screen, overlay, add.
└ `tui.graphics.merge_into_previous_layer`	`bool`	optional	true	Composite this layer into the same raster as preceding layers.
└ `tui.graphics.draw_above_cell_backgrounds`	`bool`	optional	false	Render this layer above kitty cell backgrounds.
└ `tui.graphics.color`	`string`	optional	auto	Base color override: auto, hex (#rrggbb), or theme color (colorN).
└ `tui.graphics.focused_color`	`string`	optional		Focused-state color override.
└ `tui.graphics.selected_color`	`string`	optional		Selected-state color override.
└ `tui.graphics.active_color`	`string`	optional		Active-state color override.
└ `tui.graphics.material`	`map`	optional		Single-pass inset material; preserves semantic tint and alpha. Not desktop backdrop blur.
└ `tui.graphics.material.kind`	`string`	optional	none	Finish: none, glass, satin, chrome, paper.
└ `tui.graphics.material.depth`	`u8`	optional	18	Inset shadow strength, saturating percent.
└ `tui.graphics.material.sheen`	`u8`	optional	12	Directional reflection strength, saturating percent.
└ `tui.graphics.material.grain`	`u8`	optional	2	Stable microtexture strength, saturating percent.
└ `tui.graphics.material.width`	`u16`	optional	18	Inset falloff width in logical raster pixels.
└ `tui.graphics.material.motion`	`u8`	optional	0	Reflection/depth motion percent; requires background_animate and enabled animations. Zero stays static.
└ `tui.graphics.inner_glow`	`map`	optional		Inner glow effect config for inner_glow background style.
└ `tui.graphics.inner_glow.radius`	`u32`	optional	8	Glow spread radius in pixels.
└ `tui.graphics.inner_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.inner_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.radial_glow`	`map`	optional		Radial glow effect config for radial_glow background style.
└ `tui.graphics.radial_glow.anchor`	`string`	optional	center	Glow center anchor: center, top, top_right, right, bottom_right, bottom, bottom_left, left, top_left.
└ `tui.graphics.radial_glow.radius`	`string`	optional	half_longest	Radius spec: half_width, half_height, half_longest, half_shortest, or absolute(N).
└ `tui.graphics.radial_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.radial_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.scanline`	`map`	optional		CRT scanline effect config for scanlines background style.
└ `tui.graphics.scanline.spacing`	`u32`	optional	3	Vertical spacing between scanlines in pixels.
└ `tui.graphics.scanline.intensity`	`f64`	optional	0.5	Scanline darkness intensity 0.0–1.0.
└ `tui.graphics.scanline.warp`	`f64`	optional	0.3	Sinusoidal warp curvature amount 0.0–1.0.
└ `tui.graphics.padding`	`map`	optional		Inner padding in cells inside the border.
└ `tui.graphics.padding.top`	`u16`	optional	0	Cells of padding above content.
└ `tui.graphics.padding.bottom`	`u16`	optional	0	Cells of padding below content.
└ `tui.graphics.padding.left`	`u16`	optional	0	Cells of padding left of content.
└ `tui.graphics.padding.right`	`u16`	optional	0	Cells of padding right of content.
└ `tui.graphics.disable_on_scroll`	`bool`	optional		Temporarily fall back to ASCII on scroll.
└ `tui.graphics.min_height`	`u16`	optional	1	Minimum button height in cells. 1 = compact pill mode, 3+ = bordered mode.
└ `tui.graphics.button_decoration_style`	`string`	optional	pill	Compact button decoration style: none, glow, box, pill, glass_pill. Used for 1-2 row buttons.
└ `tui.graphics.animation_phase_offset`	`f32`	optional	0.0	Additive phase offset for animation cycle 0.0–1.0.
└ `tui.graphics.overrides`	`map[string, map]`	optional		Per-instance style overrides keyed by instance name. Each value accepts the same fields as the parent style.
└ `tui.graphics.active_overrides`	`map`	optional		Active/selected-state style overrides.
└ `tui.graphics.inactive_overrides`	`map`	optional		Inactive-state style overrides for tab roles.
└ `tui.graphics.focused_overrides`	`map`	optional		Focused-state style overrides.
└ `tui.graphics.panel`	`map`	optional		Primary outer-panel bitmap border style overrides.
└ `tui.graphics.panel.tint`	`string`	optional		Background tint color: hex (#rrggbb), match_border, or colorN.
└ `tui.graphics.panel.tint_intensity`	`f64`	optional	0.15	Background tint blend intensity 0.0–1.0.
└ `tui.graphics.panel.background_style`	`string`	optional	none	Background fill style: none, solid, or gradient.
└ `tui.graphics.panel.background_opacity`	`f64`	optional	1.0	Background alpha multiplier for bitmap panel fills.
└ `tui.graphics.panel.background_contrast`	`f64`	optional	1.08	Alternate background gradient brightness multiplier.
└ `tui.graphics.panel.background_angle`	`f64`	optional	35.0	Gradient direction in degrees for bitmap panel fills.
└ `tui.graphics.panel.background_animate`	`bool`	optional	false	Scroll the background gradient when animations are enabled.
└ `tui.graphics.panel.background_animation_speed`	`f64`	optional	0.25	Background animation speed in cycles per second.