---
title: Chat Depth (Flat / Soft / Glass dial for message styling)
---

# Chat Depth (Flat / Soft / Glass dial for message styling)

## What it is

**Chat Depth** is a setting that controls how three-dimensional the chat/message area looks — how much soft shadow, translucency, and "glassy" top-edge sheen the message bubbles, the "N actions" activity pill, and the composer box have. It is a 3-way dial:

- **Flat** — no added depth. The classic, fully-flat look (what Omniscio looked like before this setting existed).
- **Soft** — _the default._ Gentle, tasteful depth: a faint drop shadow for lift plus a subtle light sheen along the top edge of each bubble.
- **Glass** — the most three-dimensional: stronger shadow, more pronounced sheen, for a glassy, lifted feel.

It is **independent of your visual theme**. Chat Depth changes how much _depth_ the chat has; the theme changes the _colors_. Every theme gets the depth you pick — the depth styling pulls from each theme's own surface/accent colors, so it always looks coherent. (The separate **Liquid Glass** theme — see [visual-themes.md](visual-themes.md) — restyles the whole window's panels; Chat Depth specifically tunes the message area and composes on top of whatever theme is active.)

Because the default is **Soft**, the chat looks gently richer out of the box. If you want the exact old fully-flat look back, set Chat Depth to **Flat**.

## Where to find it

The dial is in Settings → Appearance, in the Chat Depth card just below Font Size and above Visual
Theme. There is nothing to save: clicking Flat, Soft or Glass restyles the message area the moment
you click, in the main window and in any popped-out session windows.

## How it behaves

### How to use it

1. Open **Settings → Appearance**.
2. Find the **Chat Depth** card (just below Font Size, above Visual Theme).
3. Click **Flat**, **Soft**, or **Glass**. The chat restyles instantly — no reload. The change applies to the main window and to any popped-out session windows.

That's the whole feature — one dial, applied live.

## For agents

### How it works

Chat Depth is a single setting, `chatDepth` (one of `'flat' | 'soft' | 'glass'`, default `'soft'`), defined as a source-of-truth list in [/src/shared/chat-depth.ts](/src/shared/chat-depth.ts) and added to `AppSettings` + its Zod schema (mirroring the existing `fontSize` setting). Selecting a value writes a `data-chat-depth="…"` attribute on the document root (`<html>`) — done in [/src/renderer/src/App.tsx](/src/renderer/src/App.tsx) for the main window and [/src/renderer/src/DetachedSessionApp.tsx](/src/renderer/src/DetachedSessionApp.tsx) for pop-out session windows.

The actual look lives in CSS. [/src/renderer/src/styles/globals.css](/src/renderer/src/styles/globals.css) defines two depth tokens (`--msg-shadow`, `--msg-highlight`) whose values change per rung via `html[data-chat-depth='flat' | 'soft' | 'glass']`, and a shared `.msg-surface` class that consumes them as a composed `box-shadow`. The message bubble, the activity pill, and the composer carry `.msg-surface`, so flipping the dial re-styles all of them at once. The dial is the **single authority** for depth — no theme is allowed to set `--msg-*`, so the two settings never fight.

Two deliberate engineering choices:

- **No live `backdrop-blur` on individual message bubbles.** Real per-bubble blur is expensive on long, scrolling chats, it is restricted on the scroll-virtualized message elements (a documented performance trap), and on a flat backdrop it looks like almost nothing. The "glass" feel is achieved instead with shadow + translucency + the top sheen, which is cheap, smooth, and actually reads better. Live blur stays where it pays off — the app panels (via the Liquid Glass theme) and the composer.
- **Depth styling is paint-only** (`box-shadow`, never `transform`/`filter` on the scroll-measured bubble element), so it can't disturb the chat's scroll positioning.

The behavior and its invariants are locked by the contract at `/.claude/memory/contracts/chat-depth-contract.md` and tests `tests/unit/shared/chat-depth.test.ts` + `tests/unit/shared/chat-depth-css.test.ts`.

## Related

The colours of the chat are a separate choice, made with the Visual Theme picker described on the
[visual themes](visual-themes.md) page — Chat Depth composes on top of whichever theme is active.
The other Appearance setting that changes how chat messages render is
[agent message display](agent-message-display.md).

- [visual-themes.md](visual-themes.md) — the **Visual Theme** picker in the same Appearance pane (colors, including the frosted **Liquid Glass** theme); Chat Depth composes on top of whichever theme is active
- [agent-message-display.md](agent-message-display.md) — another Appearance setting that changes how chat messages render (structured agent prose inline vs folded)