Files
luxe/docs/guide/install.md
Evan Whittaker a0666d6c81 luxe 0.1.4: remembered models, wheel-driven lists, and a steadier phone app
- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in
  opens the model picker instead of choosing for you.
- Every list in a modal takes the mouse wheel and a draggable scrollbar.
- The phone app shows reasoning in full, stays put while you read back through a long session, and
  shows a question's answer on its card.
- On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup
  again.
- The file tree no longer shows "engine busy" in a large project, loop output is easier to follow,
  and the name is written lowercase.

The CHANGELOG has the full list.
2026-10-20 13:51:34 -05:00

188 lines
6.8 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: "Install"
summary: "Install luxe, check your setup, and pick a font."
order: 1
group: "Get started"
---
## Install
On macOS and Linux, the install script puts `luxe` in `~/.local/bin`, or in `$LUXE_INSTALL_DIR`
when it is set, and adds that to your `PATH`:
```bash
curl -fsSL https://luxe.dev/install.sh | sh
```
That address redirects to the script on the [latest
release](https://github.com/evanwhittaker/luxe/releases/latest), the one it built and attested. To
read it before running it, drop the `| sh`.
With Homebrew, on macOS or Linux:
```bash
brew install evanwhittaker/tap/luxe
```
Homebrew finishes with a line that names the installed version; run `luxe --version`
to check. Since Homebrew 6, a tap has to be trusted before its code runs. The full name above
trusts luxe's formula for you, but Homebrew can still stop on *another* tap you already have. If it
names one, trust it with `brew trust <user>/<repository>`, or remove it with `brew untap`.
With Cargo, which builds it, so you need Rust 1.89 or newer ([rustup](https://rustup.rs) installs
one):
```bash
cargo install --locked luxe-cli
```
On Windows, in PowerShell:
```powershell
powershell -c "irm https://luxe.dev/install.ps1 | iex"
```
[That script](https://luxe.dev/install.ps1) is two lines: it lets this PowerShell window run the
release's installer, which Windows' default execution policy would stop, then runs it. Nothing
about your policy is saved.
Any of them installs the `luxe` command; `luxe --version` checks it worked.
To update, run `luxe update`, or `/update` inside luxe. luxe checks once a day for a newer release
and says so on the start screen; see [Updates](configuration.md#updates) for how it updates and how
to turn the check off.
### Check a download
Every file on a release carries a build attestation, so you can confirm it came from this
repository's release workflow and nowhere else:
```bash
gh attestation verify luxe-cli-x86_64-unknown-linux-gnu.tar.xz --repo evanwhittaker/luxe
```
## Build from source
```bash
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.
| | |
| --- | --- |
| **Terminal** | Any current terminal with UTF-8. On Windows, use Windows Terminal. |
| **Model** | An API key, a ChatGPT, Copilot or OpenRouter subscription, or a local server such as LM Studio or Ollama. See [Providers](providers.md). |
| **Git** | For reviewing changes and working in worktrees. Without a repository, luxe runs with nothing to review. |
| **GitHub CLI** | Optional. `gh`, signed in, for issues and pull requests. |
| **A Nerd Font** | Optional, for icons. See [Fonts](#fonts). |
luxe also uses these when they are installed:
- `ast-grep`, for structural search.
- A language server per language, for code intelligence. See [Code
intelligence](tools.md#code-intelligence).
- A debug adapter per language, for the debugger. See [Debugger](tools.md#debugger).
## Check your setup
```bash
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](https://www.nerdfonts.com/) 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**:
```bash
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:
```toml title="alacritty.toml"
[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:
```bash
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**:
```bash
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`](configuration.md), and luxe gives each icon two cells.
## On Windows
Install [Git for Windows](https://gitforwindows.org/). 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.
Python on Windows is `py` or `python`. `python3` is usually the Microsoft Store's placeholder, so
luxe tries `py -3` first. For the Python debugger, run `py -m pip install debugpy`. The agent's
commands run Python in UTF-8 mode (`PYTHONUTF8=1`) unless you have set it yourself, so output with
characters outside your code page doesn't crash them.
Windows Terminal keeps a column at the right edge for its scrollbar. To give it to luxe, set
**Scrollbar visibility** to **Hidden** in your profile's **Appearance** settings.
## Where luxe keeps files
| | Linux and macOS | Windows |
| --- | --- | --- |
| Configuration and credentials | `~/.config/luxe` | `%APPDATA%\luxe` |
| State | `~/.local/state/luxe` | `%LOCALAPPDATA%\luxe` |
| Cache | `~/.cache/luxe` | `%LOCALAPPDATA%\luxe` |
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/`.