Install

Install with Cargo

cargo install luxe-cli
luxe --version

This installs the luxe command. You need a recent stable Rust; rustup installs one.

To update, run the same command with --force. Luxe checks once a day for a newer release and says so on the start screen; see Update notice to turn that off.

Build from source

git clone https://github.com/evanwhittaker/luxe.git
cd luxe
cargo build --release
./target/release/luxe --version

Requirements

Luxe runs natively on Linux, macOS and Windows. Only a terminal and a model are required.

Luxe also uses these when they are installed:

• ast-grep, for structural search.
• A language server per language, for code intelligence. See Code intelligence.
• A debug adapter per language, for the debugger. See Debugger.

Check your setup

luxe doctor

luxe doctor lists the tools, language servers and debug adapters Luxe found, which ones work, and how to install what is missing:

External programs
  ok    git        git
  ok    gh         git (pull requests)

Language servers
  ok    rust         rust-analyzer
  none  go           tried: gopls
        go install golang.org/x/tools/gopls@latest

Fonts

Luxe draws its icons from a Nerd Font when your terminal has one. Without one, it falls back to plain characters on its own, and every icon has a word beside it, so nothing becomes unreadable.

The screenshots use JetBrains Mono Nerd Font Mono:

brew install --cask font-jetbrains-mono-nerd-font   # macOS
sudo pacman -S ttf-jetbrains-mono-nerd               # Arch
scoop install nerd-fonts/JetBrainsMono-NF-Mono       # Windows, after `scoop bucket add nerd-fonts`

Use the Mono build of a Nerd Font. The other build draws icons wider than one cell, so they overlap the character after them. Set it in your terminal by its short family name:

[font]
normal = { family = "JetBrainsMono NFM" }

The short name matters on Linux desktops that pick their monospace font with a fontconfig rule, such as Omarchy. Asking for the full name, JetBrainsMono Nerd Font Mono, can hand you the desktop’s font instead. To check what a name resolves to:

fc-match -f '%{file}\n' "JetBrainsMono NFM"

JetBrains Mono lacks six symbols Luxe draws (ℹ︎ ↳︎ ↺︎ ⏸︎ ✔︎ ✖︎), and your system fills them in from another font. For every character from one face, use IosevkaTerm or Adwaita Mono:

brew install --cask font-iosevka-term-nerd-font    # "IosevkaTerm NFM"
brew install --cask font-adwaita-mono-nerd-font    # "AdwaitaMono Nerd Font Mono"
sudo pacman -S ttf-iosevka-nerd ttf-adwaitamono-nerd
scoop install nerd-fonts/IosevkaTerm-NF-Mono nerd-fonts/AdwaitaMono-NF-Mono

To use the wider icons anyway, set "glyphs": "nerd_wide" in config.json, and Luxe gives each icon two cells.

On Windows

Install Git for Windows. Luxe finds its bash even though it is not on PATH, and the agent needs a POSIX shell for most commands. Without one, commands run through cmd.exe, which handles cargo test or npm run build but not much else.

If WSL is installed, Luxe skips the bash.exe in System32, which would run commands inside Linux against a different filesystem.

Where Luxe keeps files

An XDG_CONFIG_HOME, XDG_STATE_HOME or XDG_CACHE_HOME you have set wins on every platform. LUXE_CONFIG_DIR moves every configuration file, API key and provider sign-in. LUXE_STATE_DIR moves the state Luxe keeps for you: the model you last chose, MCP sign-ins, and the logs of commands that only report, such as luxe auth.

Inside a project, Luxe keeps its sessions, logs and caches in .luxe/, with a .gitignore that keeps all of it out of Git except the files a team may want to share: permissions.json, mcp.json, hooks.json and skills/.