Troubleshooting

Start with luxe doctor

luxe doctor

It lists the tools, language servers and debug adapters Luxe found, starts each language server to check that it works, and shows how to install or fix what does not.

Common problems

Problem	Fix
No model selected, or --headless refuses to start	Choose one with /model, or pass --model provider/id. Luxe never picks one for you.
The model picker is empty	No provider is set up. Open Configuration (c), or set a provider’s key in the environment.
A provider keeps failing with retrying (3/3)	It is overloaded or unreachable. See When a provider stalls for the time limits.
A setting does nothing	Luxe ignores keys it does not know, so check the spelling. luxe init and /settings write a config.schema.json your editor can check against. A project’s file cannot change some settings; see Configuration.
Icons show as boxes, or sit flush against their words	See Fonts, and the glyphs setting in Appearance.
Your terminal’s copy key does nothing	The terminal keeps it. Hold shift while dragging, or let the key pass through; see Mouse and clipboard.
Images do not appear	Your terminal may not draw them. /images says why; see Images.
A language server is not used	luxe doctor says whether it starts. A server a project installed is used only when you are watching; see Tools.
A project’s hooks or MCP servers do not run	They need --trust-project, or an interactive session for MCP servers. See Security.
Luxe opened the wrong folder as the project	Inside a repository, a .luxe/ between you and its top scopes the project there. Remove it, or start Luxe somewhere else. See Where the project begins.
/pr or /github says GitHub is unavailable	Install the GitHub CLI and sign in: gh auth login. A private repository also needs gh auth setup-git.
A key binding does not work	Your terminal may not send that key. Rebind it; see Commands and keys.
On a Mac, some alt keys type a character such as ø or π	Your terminal treats Option as a key that types characters. Set it to act as Alt; see Alt keys on a Mac.

Logs

A session logs to .luxe/logs/luxe.log in the project. Commands that only report, such as luxe auth, luxe doctor and luxe models, log to logs/luxe.log in the state directory: ~/.local/state/luxe/ (%LOCALAPPDATA%\luxe\ on Windows), or wherever LUXE_STATE_DIR or XDG_STATE_HOME puts it. On macOS and Linux, a log is readable only by you. One past 5 MB is moved to luxe.log.1 the next time Luxe starts, replacing the one before.

The log shows Luxe’s own activity at info and everything else at warn. For more:

LUXE_LOG=debug luxe                        # everything
LUXE_LOG=luxe_core::hooks=debug luxe       # one part, in detail

See what is sent to the model

LUXE_WIRE_LOG records every request Luxe sends and every reply, with credentials removed. luxe wire summarizes it: what fills each request, whether the cached part stays the same between turns, and whether anything is sent twice.

LUXE_WIRE_LOG=/tmp/wire.jsonl luxe --headless -p "what does src/main.rs do?"
luxe wire /tmp/wire.jsonl
luxe wire /tmp/wire.jsonl --tools    # with each tool's share

The log stays on your machine and is off unless the variable is set.

Report a bug

Open an issue at github.com/evanwhittaker/luxe with:

• luxe --version, your operating system and terminal
• What you did, what you expected, and what happened
• The relevant part of .luxe/logs/luxe.log

If the interface itself draws wrongly, such as stray characters or a half-drawn screen, record the raw output, which shows what Luxe actually wrote:

script -f /tmp/luxe.tty -c luxe       # replay with `cat` or `scriptreplay`
asciinema rec /tmp/luxe.cast -c luxe

Attach the recording and the log from the same time.