tui schema (3901-4037)

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.themes.ghostty.shader.surfaces.modal.border`	`string`	optional		Border light: none, halo, comet, breathe, neon, wave, glow, pulse, gradient, corners, rainbow, electric, marching, double, lightcycle, glyphs, constellation, frost, coals, sketch, membrane, beam, lead, brush, filament, ribbon, pearls, fiber.
└ `tui.themes.ghostty.shader.surfaces.modal.tint`	`string`	optional		Hex tint, accent or secondary.
└ `tui.themes.ghostty.shader.surfaces.modal.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.surfaces.modal.inactive`	`map`	optional		Look while the pane is not focused.
└ `tui.themes.ghostty.shader.surfaces.modal.inactive.material`	`string`	optional		Interior material while unfocused.
└ `tui.themes.ghostty.shader.surfaces.modal.inactive.border`	`string`	optional		Border light while unfocused.
└ `tui.themes.ghostty.shader.surfaces.modal.inactive.strength`	`integer`	optional		Strength percentage while unfocused, 0-300.
└ `tui.themes.ghostty.shader.surfaces.toast`	`map`	optional		Toast notifications.
└ `tui.themes.ghostty.shader.surfaces.toast.material`	`string`	optional		Interior material: none, aurora, glass, crt, nebula, holo, backlight, sheen, plasma, starfield, matrix, synthwave, ocean, embers, snow, circuit, topo, bokeh, grid, lava, fireflies, sonar, hex, sand, stained, cells, rain, vortex, fireworks, chrome, opal, caustics, ink, neural, watercolor, silk, kaleido.
└ `tui.themes.ghostty.shader.surfaces.toast.border`	`string`	optional		Border light: none, halo, comet, breathe, neon, wave, glow, pulse, gradient, corners, rainbow, electric, marching, double, lightcycle, glyphs, constellation, frost, coals, sketch, membrane, beam, lead, brush, filament, ribbon, pearls, fiber.
└ `tui.themes.ghostty.shader.surfaces.toast.tint`	`string`	optional		Hex tint, accent or secondary.
└ `tui.themes.ghostty.shader.surfaces.toast.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.surfaces.toast.inactive`	`map`	optional		Look while the pane is not focused.
└ `tui.themes.ghostty.shader.surfaces.toast.inactive.material`	`string`	optional		Interior material while unfocused.
└ `tui.themes.ghostty.shader.surfaces.toast.inactive.border`	`string`	optional		Border light while unfocused.
└ `tui.themes.ghostty.shader.surfaces.toast.inactive.strength`	`integer`	optional		Strength percentage while unfocused, 0-300.
└ `tui.themes.ghostty.shader.surfaces.popup`	`map`	optional		Popup menus.
└ `tui.themes.ghostty.shader.surfaces.popup.material`	`string`	optional		Interior material: none, aurora, glass, crt, nebula, holo, backlight, sheen, plasma, starfield, matrix, synthwave, ocean, embers, snow, circuit, topo, bokeh, grid, lava, fireflies, sonar, hex, sand, stained, cells, rain, vortex, fireworks, chrome, opal, caustics, ink, neural, watercolor, silk, kaleido.
└ `tui.themes.ghostty.shader.surfaces.popup.border`	`string`	optional		Border light: none, halo, comet, breathe, neon, wave, glow, pulse, gradient, corners, rainbow, electric, marching, double, lightcycle, glyphs, constellation, frost, coals, sketch, membrane, beam, lead, brush, filament, ribbon, pearls, fiber.
└ `tui.themes.ghostty.shader.surfaces.popup.tint`	`string`	optional		Hex tint, accent or secondary.
└ `tui.themes.ghostty.shader.surfaces.popup.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.surfaces.popup.inactive`	`map`	optional		Look while the pane is not focused.
└ `tui.themes.ghostty.shader.surfaces.popup.inactive.material`	`string`	optional		Interior material while unfocused.
└ `tui.themes.ghostty.shader.surfaces.popup.inactive.border`	`string`	optional		Border light while unfocused.
└ `tui.themes.ghostty.shader.surfaces.popup.inactive.strength`	`integer`	optional		Strength percentage while unfocused, 0-300.
└ `tui.themes.ghostty.shader.events`	`map`	optional		Event pulse styles by event kind: info, success, attention, error, operator.
└ `tui.themes.ghostty.shader.events.info`	`map`	optional		Routine messages and unclassified feed events.
└ `tui.themes.ghostty.shader.events.info.effect`	`string`	optional		Pulse effect: none, ripple, flare, sweep, firework.
└ `tui.themes.ghostty.shader.events.info.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.events.info.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.events.info.duration_ms`	`integer`	optional		Pulse duration in milliseconds, 200-4000.
└ `tui.themes.ghostty.shader.events.success`	`map`	optional		Completions, merges and releases.
└ `tui.themes.ghostty.shader.events.success.effect`	`string`	optional		Pulse effect: none, ripple, flare, sweep, firework.
└ `tui.themes.ghostty.shader.events.success.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.events.success.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.events.success.duration_ms`	`integer`	optional		Pulse duration in milliseconds, 200-4000.
└ `tui.themes.ghostty.shader.events.attention`	`map`	optional		Questions, approvals, choices and blocked work.
└ `tui.themes.ghostty.shader.events.attention.effect`	`string`	optional		Pulse effect: none, ripple, flare, sweep, firework.
└ `tui.themes.ghostty.shader.events.attention.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.events.attention.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.events.attention.duration_ms`	`integer`	optional		Pulse duration in milliseconds, 200-4000.
└ `tui.themes.ghostty.shader.events.error`	`map`	optional		Failures and errors.
└ `tui.themes.ghostty.shader.events.error.effect`	`string`	optional		Pulse effect: none, ripple, flare, sweep, firework.
└ `tui.themes.ghostty.shader.events.error.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.events.error.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.events.error.duration_ms`	`integer`	optional		Pulse duration in milliseconds, 200-4000.
└ `tui.themes.ghostty.shader.events.operator`	`map`	optional		Your own sent messages.
└ `tui.themes.ghostty.shader.events.operator.effect`	`string`	optional		Pulse effect: none, ripple, flare, sweep, firework.
└ `tui.themes.ghostty.shader.events.operator.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.events.operator.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.events.operator.duration_ms`	`integer`	optional		Pulse duration in milliseconds, 200-4000.
└ `tui.themes.ghostty.shader.states`	`map`	optional		Live agent-state auras on agent panes and the sidebar: working, attention, error, done, waiting.
└ `tui.themes.ghostty.shader.states.working`	`map`	optional		Running with recent tool activity.
└ `tui.themes.ghostty.shader.states.working.effect`	`string`	optional		Aura effect: none, shimmer, heartbeat, glitch, glow.
└ `tui.themes.ghostty.shader.states.working.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.states.working.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.states.attention`	`map`	optional		Waiting, blocked, paused or stalled.
└ `tui.themes.ghostty.shader.states.attention.effect`	`string`	optional		Aura effect: none, shimmer, heartbeat, glitch, glow.
└ `tui.themes.ghostty.shader.states.attention.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.states.attention.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.states.error`	`map`	optional		Failed.
└ `tui.themes.ghostty.shader.states.error.effect`	`string`	optional		Aura effect: none, shimmer, heartbeat, glitch, glow.
└ `tui.themes.ghostty.shader.states.error.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.states.error.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.states.done`	`map`	optional		Completed.
└ `tui.themes.ghostty.shader.states.done.effect`	`string`	optional		Aura effect: none, shimmer, heartbeat, glitch, glow.
└ `tui.themes.ghostty.shader.states.done.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.states.done.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.states.waiting`	`map`	optional		Attention that has persisted for 20 s.
└ `tui.themes.ghostty.shader.states.waiting.effect`	`string`	optional		Aura effect: none, shimmer, heartbeat, glitch, glow.
└ `tui.themes.ghostty.shader.states.waiting.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.states.waiting.strength`	`integer`	optional		Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.unfocused`	`string`	optional		Treatment of panes other than the focused one: dim, frost, deep, fade, phosphor, cool, sketch, hologram, recede, fog, wet, sepia, derez, blur. Defaults to the preset's.
└ `tui.themes.ghostty.shader.input`	`map`	optional		Pointer, click and keystroke effects; omitted parts come from the preset.
└ `tui.themes.ghostty.shader.input.pointer`	`string`	optional		Light following the pointer: none, glow, lantern, reticle, lens, magnify, spotlight, magnet, prism, haze.
└ `tui.themes.ghostty.shader.input.click`	`string`	optional		Click effect: none, shockwave, burst, ping, derez, ink, bloom, shatter, swirl. Scrolling sends speed lines whenever one is set.
└ `tui.themes.ghostty.shader.input.keys`	`string`	optional		Keystroke effect at the text cursor or focused input: none, sparks, glitch, ripple, flash, heat.
└ `tui.themes.ghostty.shader.input.color`	`string`	optional		Hex colour, accent or secondary.
└ `tui.themes.ghostty.shader.input.lens`	`map`	optional		A magnifying lens over the pointer, on any look. Ctrl+Alt+Z shows or hides it.
└ `tui.themes.ghostty.shader.input.lens.mode`	`string`	optional	pointer	When it shows: pointer (while the pointer moves), toggle (from Ctrl+Alt+Z), always, or off.
└ `tui.themes.ghostty.shader.input.lens.zoom`	`int`	optional	180	Magnification percentage, 120-400.
└ `tui.themes.ghostty.shader.input.lens.radius`	`int`	optional	4	Radius in text rows, 1-12.
└ `tui.themes.ghostty.shader.input.hover`	`string`	optional	both	What answers the pointer: controls (buttons light, tabs and links underline), panes (the border nearest the pointer lights), both, or none.
└ `tui.themes.ghostty.shader.text`	`map`	optional		Arriving text and the freshest arrival; omitted parts come from the preset.
└ `tui.themes.ghostty.shader.text.reveal`	`string`	optional	sweep	How a new chat message draws in: sweep (row by row behind a caret of light), dissolve, glow, or none.
└ `tui.themes.ghostty.shader.text.fresh`	`string`	optional	halo	How the freshest arrival is marked: halo (a glow round its box that settles), sheen (and a band of light across it), or none.
└ `tui.themes.ghostty.shader.text.strength`	`int`	optional	100	Strength percentage, 0-300.
└ `tui.themes.ghostty.shader.captions`	`bool`	optional	true	Briefly name the event behind each pulse in the footer.
└ `tui.themes.ghostty.shader.source_highlight`	`bool`	optional	true	Flash the row or input that caused a pulse before it spreads.
└ `tui.theme_name`	`string`	optional		Selected theme name from themes registry.
└ `tui.shader_name`	`string`	optional		Selected Ghostty shader look: a built-in look, a tui.ghostty.shaders entry, or off. Replaces the theme/config shader; caco tui --shader sets it for one launch.
└ `tui.terminal`	`map`	optional		Host-terminal background via OSC 11.
└ `tui.terminal.background`	`string`	optional		Host-terminal background color (hex, e.g. #1b1d22) emitted via OSC 11; theme-aware when unset.
└ `tui.attach`	`map`	optional		Tmux attachment mode configuration.
└ `tui.attach.local_mode`	`string`	optional	attach_session	Attachment mode for local agents: capture_pane_tick, attach_session, tail_logs.
└ `tui.attach.remote_mode`	`string`	optional	capture_pane_tick	Attachment mode for remote agents: capture_pane_tick, attach_session, tail_logs.
└ `tui.attach.preview_local`	`bool`	optional	true	Auto-preview local agent tmux panes when visible.
└ `tui.attach.preview_remote`	`bool`	optional	true	Auto-preview remote agent tmux panes when visible. Uses persistent SSH connections.
└ `tui.attach.remote_preview_debounce_ms`	`integer`	optional	1500	Debounce in ms before remote tmux capture.
└ `tui.attach.detach_debounce_local`	`integer`	optional	60	Keep-warm seconds before detaching local agent PTY sessions on panel hide.
└ `tui.attach.detach_debounce_remote`	`integer`	optional	300	Keep-warm seconds before detaching remote (SSH) agent PTY sessions on panel hide.
└ `tui.shell`	`map`	optional		Shell configuration for interactive shell split panes.
└ `tui.shell.program`	`string`	optional		Shell program path (falls back to $SHELL or /bin/bash).
└ `tui.shell.args`	`list[string]`	optional	["-l"]	Arguments passed to the shell.
└ `tui.editor`	`map`	optional		Editor input mode for TUI text fields.
└ `tui.editor.mode`	`string`	optional	normal	Editing mode: normal or vim.
└ `tui.beads`	`map`	optional		Beads list display configuration (parent).
└ `tui.beads.compact`	`bool`	optional	false	Render the beads list as one compact single-row entry per bead (true) or an expanded two-line-per-bead view (false). Defaults to false (expanded) since; set true for the single-row column table.
└ `tui.skip_exit_confirmation`	`bool`	optional	false	Skip the Ctrl+c exit confirmation dialog.
└ `tui.tab_style`	`string`	optional	pill	Tab bar style for tabbed panels: pill, block, underline.
└ `tui.bottom_panel`	`map`	optional		Bottom panel layout configuration.
└ `tui.bottom_panel.full_width`	`bool`	optional	true	Whether the bottom panel spans the entire terminal width.
└ `tui.sidebar`	`map`	optional		Navigation sidebar layout and panel styling.
└ `tui.sidebar.layout`	`string`	optional		Layout mode: flat or tree. Overrides gfx-conditional fields.
└ `tui.sidebar.layout_gfx_active`	`string`	optional	flat	Layout when kitty graphics are active.
└ `tui.sidebar.layout_gfx_inactive`	`string`	optional	tree	Layout when kitty graphics are inactive.
└ `tui.sidebar.panel`	`map`	optional		Panel styling for flat layout nav panels.
└ `tui.sidebar.panel.border_visibility`	`map`	optional		Which borders to draw.
└ `tui.sidebar.panel.border_visibility.top`	`bool`	optional	true	Draw top border.
└ `tui.sidebar.panel.border_visibility.bottom`	`bool`	optional	true	Draw bottom border.
└ `tui.sidebar.panel.border_visibility.left`	`bool`	optional	false	Draw left border.
└ `tui.sidebar.panel.border_visibility.right`	`bool`	optional	false	Draw right border.
└ `tui.sidebar.truncate`	`bool`	optional	true	Enable smart truncation of sidebar subpanel rows.
└ `tui.initial_view`	`string`	optional	last_state	Initial view on TUI startup: last_state, saved_view_name:<name>, saved_view_index:<n>.
└ `tui.reload_config`	`string`	optional	live	Config reload mode: live or on_tui_restart.
└ `tui.show_workspace_tabs`	`bool`	optional	true	Show workspace tab bar in the header.
└ `tui.ui_snapshot_cache_max_age_hours`	`integer`	optional	48	Maximum age in hours before an old fully-fresh TUI UI snapshot cache may be replaced by a newer degraded-but-usable live snapshot.
└ `tui.lenses`	`list[map]`	optional	Recent builtin lens	Config-defined TUI lenses, including builtin recent_agents and split-layout view refs.
└ `tui.lenses.name`	`string`	required		Display name shown under the Lenses sidebar group.
└ `tui.lenses.kind`	`string`	optional	builtin	Lens kind: builtin or layout.
└ `tui.lenses.builtin`	`string`	optional		Builtin lens implementation such as recent_agents.
└ `tui.lenses.all_projects`	`bool`	optional	true for global, false for project	Whether a global lens is shown for all projects; project-level lenses are clamped false.
└ `tui.lenses.default_count`	`usize`	optional	12	Initial Recent lens agent count.
└ `tui.lenses.default_layout`	`string`	optional	grid	Initial Recent layout: grid, columns, rows, or tabs.
└ `tui.lenses.layout`	`map`	optional		Nested hsplit/vsplit/ref lens layout tree.
└ `tui.tmux`	`map`	optional		Bundled Cacophony tmux configuration for managed agent sessions. When present, agents launch with `tmux -f <materialized file>` instead of the host system/user tmux.conf.
└ `tui.tmux.config`	`string`	optional		Inlined multiline tmux configuration literal. When absent, the bundled Cacophony default (custom statusline, C-a leader, extended-keys, passthrough graphics) is used.