Layout Mods (reshaping the sidebar and session list)

What it is

A mod here is a layout preset, not a plugin and not a fork of the app. The mods platform reshapes one of two surfaces at a time:

• The projects sidebar — the left rail. Bundled presets Compact Rail (a slim icon rail) and Labeled Rail (the rail, roomier, with project names beside each icon).
• The session list — the rail of sessions. Bundled preset Calm List, plus row size (roomier or compact) and status-badge options.

Applying a preset is a starting point: you can tune it with the surface's own knobs, and your tuning sits on top of whatever preset is active. Exactly one preset may be active per surface at a time, and the two surfaces are independent — resetting or reverting one never disturbs the other.

Where to find it

Settings → Appearance → Layout Mods. The tab appears once the layout-mods feature is on; on a build where it is off, the switch is at Settings → Lab → Layout Mods.

How it behaves

• Preset ⊕ your tweaks, over the standard layout. The resolver merges three layers — the standard layout, the active preset's settings, and your own overrides — and validates each against the surface's schema, falling back to the standard layout for anything that does not check out.
• Every knob is a closed choice. Knobs are booleans or short enums (variants, densities), never free-form numbers, so a preset can only express a value that was designed and checked.
• Safe Mode always wins. Turning on Safe Mode restores the standard layout regardless of any preset, and is the reliable way out if a layout looks wrong but nothing has crashed.
• A crash reverts and tells you. If a surface throws while a preset or your tuning is applied, that surface clears its preset and its overrides and raises a single Inbox alert — you are never left with a blank sidebar. (A purely visual problem throws nothing, which is exactly why Safe Mode exists alongside the automatic revert.)

For agents

• Settings: modsPlatformEnabled (default false), activeLayoutModBySurface, layoutOverridesBySurface, and modsSafeMode — all in src/shared/types/settings/mods-settings.ts.
• Surfaces: MOD_SURFACES (sidebar, session-list) in src/shared/mods/mod-surfaces.ts. Bundled presets: Compact Rail / Labeled Rail (sidebar) and Calm List (session list) in src/shared/mods/bundled-mods.ts.
• UI card: src/renderer/src/features/settings/AppearanceLayoutModsCard.tsx. Contract: mods-platform-contract (nine stability invariants — gate is single-source, the resolver is total, Safe Mode wins, one active mod per surface).

Related

• sidebar-items-visibility.md — which sidebar rows show and in what order.
• session-list-sort-and-filter.md — ordering and filtering the session list.
• safe-mode.md — the general "start clean" recovery mode.