Themes

By default, fx draws its interface and code in shades of gray with blue links, and it shows diffs without green or red. A theme changes these colors. Choose one of the two built-in themes, or load a theme file that you write or take from VS Code.

fx ships two themes, fx-dark and fx-light, which you select with dark and light. Every other theme comes from a file that you add, as described in Add a theme.

Choose a theme

Set theme in ~/.fx/settings.json, or run fx config set from a terminal:

theme takes one of three kinds of value:

Run fx config unset theme to return to the default. To try a theme for one run, set FX_THEME, which takes the same values and overrides the setting:

A project's .fx.json can't set a theme. Setting NO_COLOR turns color off whatever the theme says; see environment variables.

With no theme set, fx asks the terminal for its background color to learn whether it is light or dark. If the terminal doesn't answer, fx reads COLORFGBG when it is set, and otherwise assumes a dark terminal. A theme can't change your terminal's own background. It sets the colors fx draws on top of it.

Setting light or dark, or naming a theme, also turns on green and red line numbers and signs in diffs. With no theme set, fx draws diffs in gray.

Add a theme

fx loads named themes from ~/.fx/themes/. Save a theme file there as <name>.json, then set theme to <name>. A name has 1 to 64 letters, digits, hyphens, underscores, or periods, and the file can be up to 1 MiB.

fx reads two file formats and detects which one a file uses:

• fx's own format, described in Write a theme.
• VS Code color themes, described in Use a VS Code theme.

fx loads a theme file when it starts and again when the terminal switches between light and dark. After you edit a file, restart fx to see the change.

Write a theme

This file, saved as ~/.fx/themes/midnight.json, changes links, inline code, warnings, diffs, and code colors:

{
  "type": "dark",
  "colors": {
    "link": "#58A6FF",
    "inline_code": "#A5D6FF",
    "warning": "#D29922",
    "diff_added": "#3FB950",
    "diff_removed": "#F85149",
    "diff_added_marker": "#3FB950",
    "diff_removed_marker": "#F85149"
  },
  "syntax": {
    "keyword": "#FF7B72",
    "string": "#A5D6FF",
    "number": "#79C0FF",
    "comment": { "fg": "#8B949E", "italic": true },
    "function": "#D2A8FF",
    "variable": "#FFA657",
    "operator": "#FF7B72"
  }
}

Select it with fx config set theme midnight.

Every key is optional. A slot that the file leaves out keeps the built-in color for the file's type, so a short file changes only what it names. fx ignores slot names it doesn't know, as long as the value is a valid color, so a file written for a newer fx still loads.

Colors

A color is a hex string such as "#58A6FF" or "#5AF", or an object with these fields:

An object needs fg or bg. An fx theme file can't use hex colors with an alpha channel, such as "#58A6FFCC". In a terminal without 24-bit color, fx uses the nearest of the 256 standard terminal colors.

Several slots are bold in the built-in themes. A plain hex string sets only the color and drops the bold, so write { "fg": "#58A6FF", "bold": true } to keep it.

Interface slots

Put these in colors.

Code slots

Put these in syntax. They color code blocks in replies and shell commands in tool calls.

Use a VS Code theme

fx reads a VS Code color theme as it is. Save the theme's JSON file in ~/.fx/themes/, for example as github-dark.json, and set theme to its name. fx treats a file as a VS Code theme when it has a tokenColors array, or a colors object with a key that contains a period, such as editor.background.

Before you save the file, remove any comments and trailing commas. fx reads strict JSON. fx doesn't follow include, so if a theme inherits from another file, save a merged copy.

fx maps the theme's workbench colors onto its own slots. In this table, the editor foreground is editor.foreground, then foreground. Each row uses the first key that the theme defines.

Code colors come from the theme's tokenColors. For each code slot, fx picks the best matching entry for these scopes:

An exact scope beats a prefix match, and a later entry beats an earlier one with the same match. fx skips compound scopes, which contain a space, and it keeps bold and italic from fontStyle. Colors with an alpha channel are blended over editor.background.

A slot that the theme doesn't map keeps the built-in color, so parts of fx stay gray. To change one, copy the file and add a colors entry for it, or write a fx theme file instead.

The theme's type can be light, dark, hc, or hc-light, and any other value makes the theme invalid. Without type, fx reads the brightness of editor.background, and treats the theme as dark when that color is missing.

Light and dark variants

fx applies a named theme only when the theme's type matches the terminal's current mode. A dark theme in a light terminal is not adjusted or inverted. If the types differ, fx looks for a sibling file. For a name that ends in -dark, -light, _dark, or _light, fx tries the same name with the opposite ending, so github-dark pairs with github-light. When no sibling matches, fx uses the built-in theme for the terminal's mode.

fx checks again when the terminal switches between light and dark, so a pair of files follows your terminal. A theme set to light or dark doesn't follow it.

Troubleshoot a theme

fx doesn't show an error when it can't use a theme. It falls back to the built-in theme for the terminal's mode. Check these in order:

1. The file is ~/.fx/themes/<name>.json, and theme is <name> without .json.
2. The file is valid strict JSON, with no comments or trailing commas, and an fx theme file uses #rgb or #rrggbb for every color. Check it with jq . ~/.fx/themes/<name>.json.
3. The file's type matches your terminal's mode, or a -dark and -light pair exists. An fx theme file without type counts as dark.
4. You restarted fx after editing the file.

To see why fx skipped a theme, write the theme trace to a file and read it:

Each line starts with a timestamp and [theme]. At startup, fx writes nothing when it uses the theme as it is. These lines explain a fallback or a switch: