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

Themes

Themes are JSON files that define colors for the TUI.

Locations
Selecting a Theme
Creating a Custom Theme
Theme Format
Color Tokens
Color Values
Tips

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.

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.

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",
    "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.

Hot reload: When you edit the currently active custom theme file, Atomic reloads it automatically for immediate visual feedback.

Theme Format

{
  "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "text": "",
    ...
  },
  "workingIndicator": {
    "dark": "#70759f",
    "lift": "#7f849c",
    "muted": "#789bd0",
    "accent": "blue",
    "bright": "#b8d2ff",
    "peak": "#eef4ff"
  }
}

name is required, must be unique, and must not contain /.
vars is optional. Define reusable colors here, then reference them in colors or workingIndicator.
colors must define all 51 required tokens.
workingIndicator is optional and may override any subset of the six tones in the outward half of the ordinary ∀ ramp; Atomic derives omitted tones from selected background, accent, and text roles, then mirrors the palette back after peak. Explicit numeric values from 0 through 255 remain exact terminal palette indices. When a numeric index from 0 through 15 seeds an omitted tone, Atomic mixes from its built-in approximation of the common ANSI RGB value; the terminal still controls the actual appearance of the explicit index. Both explicit and derived tones update on theme hot reload.

The $schema field enables editor auto-completion and validation.

Color Tokens

Every theme must define all 51 color tokens. There are no optional colors.

Core UI (11 colors)

Token	Purpose
`accent`	Primary accent (logo, selected items, cursor)
`border`	Normal borders
`borderAccent`	Highlighted borders
`borderMuted`	Subtle borders (editor)
`success`	Success states
`error`	Error states
`warning`	Warning states
`muted`	Secondary text
`dim`	Tertiary text
`text`	Default text (usually `""`)
`thinkingText`	Thinking block text

Backgrounds & Content (11 colors)

Token	Purpose
`selectedBg`	Selected line background
`userMessageBg`	User message background
`userMessageText`	User message text
`customMessageBg`	Extension message background
`customMessageText`	Extension message text
`customMessageLabel`	Extension message label
`toolPendingBg`	Tool box (pending)
`toolSuccessBg`	Tool box (success)
`toolErrorBg`	Tool box (error)
`toolTitle`	Tool title
`toolOutput`	Tool output text

Markdown (10 colors)

Token	Purpose
`mdHeading`	Headings
`mdLink`	Link text
`mdLinkUrl`	Link URL
`mdCode`	Inline code
`mdCodeBlock`	Code block content
`mdCodeBlockBorder`	Code block fences
`mdQuote`	Blockquote text
`mdQuoteBorder`	Blockquote border
`mdHr`	Horizontal rule
`mdListBullet`	List bullets

Tool Diffs (3 colors)

Token	Purpose
`toolDiffAdded`	Added lines
`toolDiffRemoved`	Removed lines
`toolDiffContext`	Context lines

Syntax Highlighting (9 colors)

Token	Purpose
`syntaxComment`	Comments
`syntaxKeyword`	Keywords
`syntaxFunction`	Function names
`syntaxVariable`	Variables
`syntaxString`	Strings
`syntaxNumber`	Numbers
`syntaxType`	Types
`syntaxOperator`	Operators
`syntaxPunctuation`	Punctuation

Thinking Level Borders (6 colors)

Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):

Token	Purpose
`thinkingOff`	Thinking off
`thinkingMinimal`	Minimal thinking
`thinkingLow`	Low thinking
`thinkingMedium`	Medium thinking
`thinkingHigh`	High thinking
`thinkingXhigh`	Extra high thinking

Bash Mode (1 color)

Token	Purpose
`bashMode`	Editor border in bash mode (`!` prefix)

HTML Export (optional)

The export section controls colors for /export HTML output. If omitted, colors are derived from userMessageBg.

{
  "export": {
    "pageBg": "#18181e",
    "cardBg": "#1e1e24",
    "infoBg": "#3c3728"
  }
}

Color Values

Four formats are supported:

Format	Example	Description
Hex	`"#ff0000"`	6-digit hex RGB
256-color	`39`	xterm 256-color palette index (0-255)
Variable	`"primary"`	Reference to a `vars` entry
Default	`""`	Terminal’s default color

256-Color Palette

0-15: Basic ANSI colors (terminal-dependent)
16-231: 6×6×6 RGB cube (16 + 36×R + 6×G + B where R,G,B are 0-5)
232-255: Grayscale ramp

Terminal Compatibility

Atomic uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, Atomic falls back to the nearest approximation. Check truecolor support:

echo $COLORTERM  # Should output "truecolor" or "24bit"

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:

Start here

Customization

Reference

Programmatic Usage

Platform Setup

Development

Changelog

Themes

Themes

Table of Contents

Locations

Selecting a Theme

Creating a Custom Theme

Theme Format

Color Tokens

Core UI (11 colors)

Backgrounds & Content (11 colors)

Markdown (10 colors)

Tool Diffs (3 colors)

Syntax Highlighting (9 colors)

Thinking Level Borders (6 colors)

Bash Mode (1 color)

HTML Export (optional)

Color Values

256-Color Palette

Terminal Compatibility

Tips

Examples

​Themes

​Table of Contents

​Locations

​Selecting a Theme

​Creating a Custom Theme

​Theme Format

​Color Tokens

​Core UI (11 colors)

​Backgrounds & Content (11 colors)

​Markdown (10 colors)

​Tool Diffs (3 colors)

​Syntax Highlighting (9 colors)

​Thinking Level Borders (6 colors)

​Bash Mode (1 color)

​HTML Export (optional)

​Color Values

​256-Color Palette

​Terminal Compatibility

​Tips

​Examples

Themes

Table of Contents

Locations

Selecting a Theme

Creating a Custom Theme

Theme Format

Color Tokens

Core UI (11 colors)

Backgrounds & Content (11 colors)

Markdown (10 colors)

Tool Diffs (3 colors)

Syntax Highlighting (9 colors)

Thinking Level Borders (6 colors)

Bash Mode (1 color)

HTML Export (optional)

Color Values

256-Color Palette

Terminal Compatibility

Tips

Examples