pi-mono-master
  • English

      • Themes

      Pi supports fully customizable color themes. Themes control every color in the terminal UI.

      Loading Locations

      Themes are loaded from multiple locations, in order of precedence (later wins):

      SourceLocationDescription
      Built-inBundled with PiDefault dark and light themes
      Global~/.pi/agent/themes/User-wide custom themes
      Project.pi/themes/Project-specific themes
      Packagesthemes field in packageThemes from installed packages
      CLI--theme <path>Load a theme file from any path

      Set the active theme in settings:

      {
  "theme": "my-custom-theme"
}

      Theme Structure

      A theme is a JSON file with a name and 51 required color tokens organized under vars and colors:

      {
  "name": "my-theme",
  "vars": {
    "primary": "#7c3aed",
    "secondary": "#a78bfa"
  },
  "colors": {
    "text": "#e4e4e7",
    "textMuted": "#a1a1aa",
    "border": "#3f3f46",
    "background": "#09090b",
    ...
  }
}

      The vars object defines reusable color variables. The colors object maps color tokens to values.

      Color Token Categories

      Core UI (11 tokens)

      TokenDescription
      textPrimary text color
      textMutedSecondary/dimmed text
      textInverseText on inverted backgrounds
      borderDefault border color
      borderFocusedFocused element border
      backgroundMain background
      backgroundHoverHovered element background
      backgroundSelectedSelected element background
      primaryPrimary accent color
      primaryHoverPrimary accent hover state
      errorError text and indicators

      Backgrounds & Content (11 tokens)

      TokenDescription
      headerTextHeader text color
      headerBorderHeader border color
      inputTextInput field text
      inputPlaceholderInput placeholder text
      inputBorderInput field border
      inputBackgroundInput field background
      autocompleteTextAutocomplete suggestion text
      autocompleteSelectedSelected autocomplete item
      scrollbarThumbScrollbar thumb color
      scrollbarTrackScrollbar track color
      badgeBadge/tag color

      Markdown (10 tokens)

      TokenDescription
      markdownHeadingHeading text
      markdownBoldBold text
      markdownItalicItalic text
      markdownCodeInline code
      markdownCodeBackgroundCode block background
      markdownLinkLink text
      markdownLinkHoverLink hover state
      markdownBlockquoteBlockquote text
      markdownBlockquoteBorderBlockquote border
      markdownListMarkerList bullet/number

      Tool Diffs (3 tokens)

      TokenDescription
      diffAddedAdded line background
      diffRemovedRemoved line background
      diffContextContext line background

      Syntax Highlighting (9 tokens)

      TokenDescription
      syntaxKeywordKeywords (if, return, function)
      syntaxStringString literals
      syntaxNumberNumber literals
      syntaxCommentComments
      syntaxFunctionFunction names
      syntaxVariableVariable names
      syntaxOperatorOperators
      syntaxTypeType names
      syntaxPunctuationPunctuation and brackets

      Thinking Levels (6 tokens)

      TokenDescription
      thinkingOffThinking off indicator
      thinkingMinimalMinimal thinking indicator
      thinkingLowLow thinking indicator
      thinkingMediumMedium thinking indicator
      thinkingHighHigh thinking indicator
      thinkingXhighExtra-high thinking indicator

      Bash Mode (1 token)

      TokenDescription
      bashModeIndicatorBash mode active indicator

      Color Formats

      Color values support four formats:

      FormatExampleDescription
      Hex"#7c3aed"Standard hex color (3, 6, or 8 digits)
      Xterm 256"141"Xterm 256-color palette index (as string)
      Variable reference"$primary"References a vars value
      Empty string""Inherit / use terminal default

      Variable references allow you to define a color once in vars and reuse it across multiple tokens:

      {
  "vars": {
    "accent": "#7c3aed"
  },
  "colors": {
    "primary": "$accent",
    "markdownLink": "$accent",
    "borderFocused": "$accent"
  }
}

      Hot Reload

      Theme files are watched for changes during a session. When you edit and save a theme file, the changes are applied immediately without restarting Pi. This makes it easy to iterate on colors in real time.

      Creating a Custom Theme

      1. Create a theme file in your global themes directory:
      mkdir -p ~/.pi/agent/themes
      1. Start with the built-in dark theme as a base and save it as a new file:
      {
  "name": "my-theme",
  "vars": {
    "accent": "#f59e0b",
    "accentDim": "#b45309",
    "bg": "#1c1917",
    "bgLight": "#292524",
    "fg": "#e7e5e4",
    "fgDim": "#a8a29e",
    "border": "#44403c"
  },
  "colors": {
    "text": "$fg",
    "textMuted": "$fgDim",
    "textInverse": "$bg",
    "border": "$border",
    "borderFocused": "$accent",
    "background": "$bg",
    "backgroundHover": "$bgLight",
    "backgroundSelected": "$bgLight",
    "primary": "$accent",
    "primaryHover": "$accentDim",
    "error": "#ef4444",

    "headerText": "$fg",
    "headerBorder": "$border",
    "inputText": "$fg",
    "inputPlaceholder": "$fgDim",
    "inputBorder": "$border",
    "inputBackground": "$bgLight",
    "autocompleteText": "$fgDim",
    "autocompleteSelected": "$accent",
    "scrollbarThumb": "$border",
    "scrollbarTrack": "",
    "badge": "$accent",

    "markdownHeading": "$accent",
    "markdownBold": "$fg",
    "markdownItalic": "$fgDim",
    "markdownCode": "$accent",
    "markdownCodeBackground": "$bgLight",
    "markdownLink": "$accent",
    "markdownLinkHover": "$accentDim",
    "markdownBlockquote": "$fgDim",
    "markdownBlockquoteBorder": "$border",
    "markdownListMarker": "$accent",

    "diffAdded": "#22c55e",
    "diffRemoved": "#ef4444",
    "diffContext": "$bgLight",

    "syntaxKeyword": "#c084fc",
    "syntaxString": "#86efac",
    "syntaxNumber": "#fdba74",
    "syntaxComment": "$fgDim",
    "syntaxFunction": "#93c5fd",
    "syntaxVariable": "$fg",
    "syntaxOperator": "#fca5a5",
    "syntaxType": "#67e8f9",
    "syntaxPunctuation": "$fgDim",

    "thinkingOff": "$fgDim",
    "thinkingMinimal": "#94a3b8",
    "thinkingLow": "#60a5fa",
    "thinkingMedium": "#a78bfa",
    "thinkingHigh": "#f472b6",
    "thinkingXhigh": "#fb923c",

    "bashModeIndicator": "#f59e0b"
  }
}
      1. Activate the theme in your settings:
      {
  "theme": "my-theme"
}
      1. Adjust colors and save. Changes apply immediately via hot reload.
      Tip

      Use vars to define your palette, then reference variables with $name in colors. This makes it easy to adjust a single accent color and have it propagate throughout the theme.