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

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

• session-title-style.md — the sibling control that decides how a session is named.
• session-menu-customization.md — the other per-session appearance control in the same settings area.
• settings/appearance.md — the settings reference where the auto-color rules live.