Files
luxe/docs/guide/appearance.md
Evan Whittaker 3c69a90b06 A file lock waits out Windows removing the previous holder's lock; the site's header fits one row on a phone, the tools page draws its claims, and the README opens on the wordmark
- On Windows a lock directory being removed answers access denied, not already exists, so a
  second writer, such as two MCP servers signing in at once, failed instead of waiting.
- The header is Docs, Tools and the GitHub mark, one row down to 320px; /themes folds into the
  homepage's gallery and redirects there.
- The tools page has a terminal of measured rows beside its intro and a chart of whole-task cost
  against Luxe's 1x beside its table; Pi leaves the comparison.
- The README opens on a generated wordmark banner that carries its own colors.
2026-10-17 16:58:08 -05:00

10 KiB
Raw Blame History

title, summary, order, group
title summary order group
Appearance Themes, the statusline, icons and fonts, the conversation's layout, diffs and images. 2 Customize

Every setting on this page goes in ~/.config/luxe/config.json, or a project's .luxe/config.json. /reload applies a change without restarting, except to images.

Themes

/theme previews each theme as you move through the list. enter keeps one and saves it to your config; esc puts back the theme you had.

Luxe's own theme is luxe, a warm graphite with a brass accent. Every accent clears a 4.5:1 contrast ratio against the background, and body text 7:1. The others are dark versions of community favorites and of Omarchy's themes:

Luxe luxe
Editors jetbrains (Darcula), vscode (Visual Studio 2017 Dark), xcode (Default Dark)
Community aura, ayu, catppuccin, dracula, everforest, github (Dark Dimmed), gruvbox, kanagawa, monokai, noctis-bordo, nord, one-dark, panda, rose-pine, tokyo-night, vesper, zenburn
Omarchy ethereal, hackerman, last-horizon, lumon, matte-black, miasma, osaka-jade, retro-82, ristretto, solitude, vantablack
{ "theme": "nord" }

An unknown name falls back to luxe, and Luxe says so when the session opens. See them all on luxe.dev.

Code is colored by the theme too: in answers, tool cards, diffs and the preview, keywords take the theme's accentSecondary, strings its success, numbers its warning, functions its accent, types its info, and comments and punctuation its muted. Markdown wears the colors it does in an answer. A theme of your own, or your Omarchy theme, colors code with no extra setup, and the website's code blocks are colored the same way.

Change a few colors

colors overrides single colors on top of any theme. A value is #rrggbb, an ANSI color number (0 to 255), or "" for the terminal's own default.

{
  "colors": {
    "accent": "#7aa2f7",
    "diffAddBg": "#12331f",
    "diffDelBg": "#3a1620"
  }
}

The names are the ones a theme file uses; luxe.json lists every one.

One more name is optional: modePlan, the color plan mode wears on the composer and the menus and questions around it. Without it, Luxe picks the first of the theme's other colors that reads as different from its accent.

Make a theme

A theme is a JSON file in ~/.config/luxe/themes/, named for the file: themes/harbor.json is "theme": "harbor", and it appears in /theme with the built-ins. Its colors need only what it changes; everything else comes from luxe. vars names colors for the rest of the file to use.

{
  "vars": { "harbor": "#2f7d8c" },
  "colors": { "accent": "harbor", "borderAccent": "harbor" }
}

This is also how to have a light theme. Start from a copy of luxe.json for a complete one.

On Omarchy

Leave theme unset, or set it to omarchy, and Luxe wears your desktop's theme and changes with it, within a couple of seconds, in a running session. It uses, in order:

  1. A luxe.json in the current Omarchy theme. To give every theme one, write a template at ~/.config/omarchy/themed/luxe.json.tpl and Omarchy renders it from each theme's colors.
  2. Luxe's built-in theme of the same name, when both are dark.
  3. A theme made on the spot from the Omarchy theme's colors.toml, with text lifted until it is readable. This is how a light Omarchy theme comes out.

A theme you choose with /theme stays, whatever the desktop does, unless you choose omarchy. /theme saves to your own config, so a theme a project's .luxe/config.json sets still wins in that project.

Statusline

The statusline is the bar under the composer. Its modules are listed in the order they are drawn: the left half from the edge inward, the right half from the middle outward.

{
  "statusline": {
    "visibility": "auto",
    "style": "slab",
    "left": ["project", "branch", "pr", "todo", "changes"],
    "right": ["context", "cost", "tokens", "thinking", "model"],
    "thinking_colors": false
  }
}

Those are the defaults. Reorder a list to move modules, and leave one out to hide it. project, branch, pr, todo, changes, cwd and activity belong on the left, the rest on the right, and a module listed on the other side is not drawn. While auto-approve is on, an auto-approve badge sits on the right whatever the list says.

Module Shows
project The project's name
branch The Git branch, with * when there are uncommitted changes
pr The branch's pull request: #138 · 1 failing · 2 threads. Shown only when there is one.
todo The agent's checklist: 4/9 · Refine the workspace overview
changes How many files changed, and the key for the preview. Click it to open.
cwd The current directory, shortened
activity What the turn is doing, and for how long
context How full the context window is. Yellow past 75%, red past 90%.
cost What the session has cost, or on a subscription, what is left of the plan
tokens Tokens sent and received, and the input read from the cache
thinking The thinking level
model The model, or no model until you choose one
Key Values
visibility auto (shown when the dock is not beside the conversation), shown, hidden
style slab (each module on its own block) or flat (plain text). The dock's headings follow it.
thinking_colors true colors the thinking level from muted (off) to magenta (ultra)

When the bar runs out of room, it drops modules in this order: cwd, tokens, activity, cost, todo, changes, pr, branch, project, then context and thinking. The model goes last.

Icons and fonts

glyphs sets which icons Luxe draws. Every icon has a word beside it, so nothing is lost at any setting.

glyphs Draws Needs
auto nerd when Luxe can confirm your font has every icon, otherwise unicode
nerd Nerd Font icons A Nerd Font
nerd_wide The same icons, each given two cells A Nerd Font whose icons are drawn wide
unicode Plain shapes: ■ ► ▪ ○ ● UTF-8
ascii Plain punctuation: / + ~ = x UTF-8, for the rest of the screen
{ "glyphs": "nerd" }

auto asks fontconfig (fc-list) whether your fonts have every icon, and picks nerd in kitty, which brings its own. On macOS and Windows without fontconfig, it picks unicode; set nerd if you have a Nerd Font. If icons sit flush against the word beside them, you have the wide build of your Nerd Font: switch to its Mono build (see Fonts), or set nerd_wide.

Fonts that draw every character Luxe uses, measured against the font files:

Font Missing Width
JetBrains Mono ℹ︎ ↳︎ ↺︎ ⏸︎ ✔︎ ✖︎, filled in by your system 0.60 em
IosevkaTerm nothing 0.50 em
Adwaita Mono nothing 0.60 em
Monaspace ⏎︎, used only by luxe wire 0.62 em

Use IosevkaTerm's Term build: plain Iosevka lets some symbols overlap the next character.

The conversation

{
  "conversation": {
    "alignment": "full",
    "growth": "bottom",
    "thinking": "shown",
    "tool_runs": "fold",
    "stream_reveal": "smooth",
    "activity_bar": "bars"
  }
}
Key Default Values
alignment full full uses the whole width. left or center cap the width at prose_max_width for text and wide_block_max_width for code and tables.
prose_max_width 120 72 to 120 columns, for left and center
wide_block_max_width 140 72 to 140 columns, for left and center
growth bottom bottom grows up from the composer, like a chat. top grows down from the top.
thinking shown How the model's reasoning appears: shown, collapsed to one line, or hidden
tool_runs fold fold draws a run of lookups as one line. cards gives each call a card.
tool_details errors Which tool cards start open: errors, all or collapsed
stream_reveal smooth smooth paces streaming text evenly. off draws text as soon as it comes in.
activity_bar bars The running-turn indicator: bars, dots or off
scroll_lines 3 Lines per mouse wheel notch, 1 to 20
image_max_rows 24 The tallest an image is drawn, 3 to 200 rows

Diffs

Tool cards, the preview and Guided Review draw diffs the same way:

{ "diff": { "layout": "auto", "word_wrap": false } }
layout Side by side when each column fits
auto 44 columns of code
split 28 columns
unified Never

ctrl+b switches the preview or Guided Review for the session. A change that only adds or only removes lines is always one column. Within a changed line, the words that changed are bold.

word_wrap wraps long lines in Guided Review instead of scrolling sideways, and w switches it there. Tool cards always wrap, and the preview starts wrapped; alt+w switches it.

Images

Screenshots and images the agent reads are drawn in the conversation where the terminal can:

images Draws Needs
auto pixels in kitty and Ghostty, off elsewhere and inside tmux or screen
pixels The picture A terminal with the kitty graphics protocol
blocks A rough preview in colored blocks Any terminal with color
off A line naming the image, with open ↗ to view it
{ "images": "auto" }

Double-click an image, or select its message (alt+k) and press alt+i, to view it full-window. /images says which setting is in effect and why. A change to images applies the next time Luxe starts.

The start screen

The start screen's logotype is drawn in your theme's accent, with a slow shine across it. "banner_animation": false holds it still. See The start screen for its styles, and for skipping it.