Files
luxe/docs/guide/appearance.md
Evan Whittaker 09a7de2520 Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
2026-10-17 12:08:30 -05:00

246 lines
10 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "Appearance"
summary: "Themes, the statusline, icons and fonts, the conversation's layout, diffs and images."
order: 2
group: "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` |
```json title="~/.config/luxe/config.json"
{ "theme": "nord" }
```
An unknown name falls back to `luxe`, and Luxe says so when the session opens. See them all at
[luxe.dev/themes](https://luxe.dev/themes).
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.
```json title="~/.config/luxe/config.json"
{
"colors": {
"accent": "#7aa2f7",
"diffAddBg": "#12331f",
"diffDelBg": "#3a1620"
}
}
```
The names are the ones a theme file uses; [`luxe.json`](https://github.com/evanwhittaker/luxe/blob/HEAD/crates/luxe-core/src/themes/luxe.json)
lists every one.
One more name is optional: `modePlan`, the color [plan mode](agent.md#plan-then-build) 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.
```json title="~/.config/luxe/themes/harbor.json"
{
"vars": { "harbor": "#2f7d8c" },
"colors": { "accent": "harbor", "borderAccent": "harbor" }
}
```
This is also how to have a light theme. Start from a copy of
[`luxe.json`](https://github.com/evanwhittaker/luxe/blob/HEAD/crates/luxe-core/src/themes/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.
```json title="~/.config/luxe/config.json"
{
"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](interface.md#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 |
```json title="~/.config/luxe/config.json"
{ "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](install.md#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
```json title="~/.config/luxe/config.json"
{
"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:
```json title="~/.config/luxe/config.json"
{ "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 | |
```json title="~/.config/luxe/config.json"
{ "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](interface.md#the-start-screen)
for its styles, and for skipping it.