Themes

September 20, 2026 · View on GitHub

Atomic can create themes. Ask it to build one for your setup.

Themes

Themes are JSON files that define colors for the TUI.

On this page and its reference

This page covers selecting a theme and authoring your first one. The theme file format, every color token, and the accepted color values live in the Theme reference.

Locations

Atomic loads themes from:

Built-in: dark, light, catppuccin-frappe, catppuccin-latte, catppuccin-macchiato, catppuccin-mocha
Global: ~/.atomic/agent/themes/*.json (legacy ~/.pi/agent/themes/*.json)
Project: .atomic/themes/*.json (legacy .pi/themes/*.json, only after the project is trusted)
Packages: themes/ directories, atomic.themes, or legacy pi.themes entries in package.json
Settings: themes array with files or directories
CLI: --theme <path> (repeatable)

Disable discovery with --no-themes. --theme <path> loads a theme file; --use-theme <name> (see Initial Theme) selects an already-loaded theme for this run without saving it.

Selecting a Theme

Select a theme via /settings or in settings.json:

{
  "theme": "my-theme"
}

Use "theme": "light-theme/dark-theme" for automatic mode. Atomic chooses the first theme when the terminal reports a light color scheme and the second theme for dark terminals, and it follows terminal color-scheme changes when supported.

On first run, Atomic detects your terminal background and defaults to dark or light.

Main chat, attached workflow-stage chat, and the workflow graph canvas use the terminal's default background, including terminal transparency. Graph node interiors share that background; headers, footers, focused title tabs, and tool cards retain their theme colors.

Truncated workflow-node labels keep the focused tab's fill, text color, and weight through the ellipsis. The surrounding border and node body retain their own styling.

Initial Theme

Start an interactive run with a theme without changing the saved setting:

atomic --use-theme light

To follow terminal appearance, use the lightTheme/darkTheme form:

atomic --use-theme light/dark

The CLI value is the initial theme for that run only. Choosing another theme later in /settings applies it immediately and saves it normally; an unknown theme name reports the ordinary theme error.

Creating a Custom Theme

Create a theme file:

mkdir -p ~/.atomic/agent/themes
vim ~/.atomic/agent/themes/my-theme.json

Define the theme with all required colors (see Color Tokens):

{
  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "primary": "#00aaff",
    "secondary": 242
  },
  "colors": {
    "accent": "primary",
    "border": "primary",
    "borderAccent": "#00ffff",
    "borderMuted": "secondary",
    "success": "#00ff00",
    "error": "#ff0000",
    "warning": "#ffff00",
    "muted": "secondary",
    "dim": 240,
    "text": "",
    "thinkingText": "secondary",
    "selectedBg": "#2d2d30",
    "scrollbarThumb": "#555566",
    "userMessageBg": "#2d2d30",
    "userMessageText": "",
    "customMessageBg": "#2d2d30",
    "customMessageText": "",
    "customMessageLabel": "primary",
    "toolPendingBg": "#1e1e2e",
    "toolSuccessBg": "#1e2e1e",
    "toolErrorBg": "#2e1e1e",
    "toolTitle": "primary",
    "toolOutput": "",
    "mdHeading": "#ffaa00",
    "mdLink": "primary",
    "mdLinkUrl": "secondary",
    "mdCode": "#00ffff",
    "mdCodeBlock": "",
    "mdCodeBlockBorder": "secondary",
    "mdQuote": "secondary",
    "mdQuoteBorder": "secondary",
    "mdHr": "secondary",
    "mdListBullet": "#00ffff",
    "toolDiffAdded": "#00ff00",
    "toolDiffRemoved": "#ff0000",
    "toolDiffContext": "secondary",
    "syntaxComment": "secondary",
    "syntaxKeyword": "primary",
    "syntaxFunction": "#00aaff",
    "syntaxVariable": "#ffaa00",
    "syntaxString": "#00ff00",
    "syntaxNumber": "#ff00ff",
    "syntaxType": "#00aaff",
    "syntaxOperator": "primary",
    "syntaxPunctuation": "secondary",
    "thinkingOff": "secondary",
    "thinkingMinimal": "primary",
    "thinkingLow": "#00aaff",
    "thinkingMedium": "#00ffff",
    "thinkingHigh": "#ff00ff",
    "thinkingXhigh": "#ff0000",
    "bashMode": "#ffaa00"
  }
}

Select the theme via /settings.

Atomic automatically reloads the active custom theme when you edit its file, so you can see changes immediately.

Theme Format

Moved to Theme reference.

Color Tokens

Moved to Theme reference.

Color Values

Moved to Theme reference.

256-Color Palette

Moved to Theme reference.

Terminal Compatibility

Moved to Theme reference.

Tips

Dark terminals: Use bright, saturated colors with higher contrast.

Light terminals: Use darker, muted colors with lower contrast.

Color harmony: Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in vars, and reference consistently.

Testing: Check your theme with different message types, tool states, markdown content, and long wrapped text.

VS Code: Set terminal.integrated.minimumContrastRatio to 1 for accurate colors.

Examples

See the built-in themes: