---
title: Session Auto-Color Rules (keyword-based or project-inherited automatic session coloring)
---

# Session Auto-Color Rules

## What it is

**Auto-Color Rules** automatically assign a color bar to sessions based on user-defined rules, so you never have to color-code sessions by hand. Two modes, mutually exclusive:

- **Match project color** (toggle ON): every session inherits the color of its parent project. Keyword rules are ignored entirely.
- **Keyword rules** (toggle OFF): an ordered list of keyword-to-color mappings. When a session is created or renamed, the title is checked against each keyword in order; the first case-insensitive substring match wins and sets the session's color bar.

**Priority (top wins, no exceptions):**
1. **Manual color** -- if you've set a color on a session by hand, auto-color never overwrites it.
2. **Project color** -- when the toggle is ON, the session inherits its project's color.
3. **Keyword rules** -- when the toggle is OFF, rules are evaluated top-to-bottom, first match wins.

## Where to find it

### Where it lives in the UI

**Settings > Sessions > Auto-Color Rules** subsection.

- A **Match project color** toggle at the top.
- Below it, a **Keyword rules** card with drag-to-reorder rows. Each row has a color swatch (click to pick), a text field for the keyword, and a delete button. An "Add Rule" button appends a new row.
- An **Apply to Existing Sessions** button at the bottom retroactively applies the current rules to all sessions that don't already have a color.

When Match project color is ON, the keyword rules card is visually dimmed and non-interactive.

## How it behaves

### How to use it

1. Open **Settings > Sessions** and scroll to **Auto-Color Rules**.
2. To use project colors: flip **Match project color** ON. Every session will inherit its project's color (if the project has one set).
3. To use keyword rules: leave the project toggle OFF. Click **Add Rule**, type a keyword (e.g. "bugfix"), and click the color swatch to pick a color. Drag rows to reorder priority.
4. Click **Apply to Existing Sessions** to retroactively color sessions that match but were created before you set up rules.

## For agents

### How it works (technical)

- Settings stored in `AppSettings` as `autoColorMatchProject` (boolean) and `autoColorRules` (ordered array of `{id, keyword, color}`).
- The engine function `maybeApplyAutoColor(sessionId, title)` runs synchronously after every session rename across all 8 rename sites (title orchestrator, manual rename, council, email inbound, quick replies).
- Colors are `#rrggbb` hex strings validated by `sessionColorSchema`. The color appears as the 3px vertical bar on the session row in the sidebar.
- Backfill via the `SESSION_AUTO_COLOR_BACKFILL` IPC channel queries all sessions with null color and applies the current rules.
- Empty keywords are skipped. Matching is case-insensitive substring.

## Related

No sibling page is linked from this one, so the way onward is the library's own map: [INDEX.md](INDEX.md) lists every page and area, and is the quickest route to the neighbouring session-appearance and sidebar topics.