Configuration

Luxe works with no configuration. Everything here is optional, and most of it can be set from inside Luxe: Configuration (on the start screen, or /config) signs you in and opens these files in your editor, /settings changes the settings you use most, /theme sets the theme, and /model the model.

Files

Your own files live in ~/.config/luxe/ (%APPDATA%\luxe on Windows). A project can have its own in .luxe/ at its root.

LUXE_CONFIG_DIR moves the whole directory, and every file in it.

What a project cannot change

A project’s .luxe/config.json overrides yours key by key, with a few exceptions. These run programs, reach the network, or decide what a repository is trusted with, so Luxe reads them from your own config only:

• launchers and mentions, which run programs
• update, and github.refresh_secs
• lsp.project_servers
• agent.on_ask, which a project can set to deny but not to allow
• agent.cache_warming, which a project can turn down but not up, since it spends your money

Project gate.commands also run programs. Luxe ignores them and warns unless you start with --trust-project. With trust, a nonempty project list replaces your global list. Otherwise, the loop uses your global commands. Move the list to your own config if you don’t want to trust the project.

Editing

luxe init asks the first run’s questions again (a theme, a provider, the tools, and the start screen) and writes the answers to config.json, changing only those keys. It also writes a config.schema.json beside it so your editor can complete and check every key. --defaults writes a file that chooses nothing, without asking, and so does a run with no terminal; with a config.json already there, either one needs --force, which removes the old file first. Luxe ignores a key it does not know, so an old config always loads on a newer Luxe; check the spelling if a setting seems to do nothing.

/reload (ctrl+shift+r) applies changes to config.json and keybindings.json without restarting.

Settings

/settings, or Settings in Configuration, shows the settings you are most likely to change as controls, on five pages: Appearance, Conversation, Dock & statusline, Tools, and Agent. Each change writes one key to your config.json and leaves the rest of the file as it was.

Each value says where it comes from: default, global (your config.json), or project (this project’s .luxe/config.json, which wins over yours, so it is changed there). Most settings take effect at once; the rest say they take effect the next time Luxe starts. That includes the Tools page, because the tools the agent is offered are fixed for a run. In a window too small for the panel, it says so instead, and only esc works until the window fits.

Behavior

Notifications

{ "notifications": true, "bell": false }

notifications sends a desktop notification while the terminal is in the background, when a turn finishes or fails, a tool call waits for your approval, the agent asks you a question, or a Guided Review finishes writing its guide. To pick some of those, list them:

{ "notifications": ["permission", "question"] }

bell rings the terminal bell at each of those moments. Both are off by default. Many terminals turn a bell into a request for the window manager’s attention, which can pull focus from what you are doing.

The notification goes through your terminal, as an escape sequence it turns into a desktop notification, so it works over ssh and needs nothing installed. Ghostty, iTerm2, kitty, WezTerm, Warp and foot show them; Luxe recognizes those and sends nothing to a terminal it does not know. If yours shows them and Luxe does not recognize it, name the sequence: "notification_method": "osc9" (the common one) or "osc777". Inside tmux, add set -g allow-passthrough on to your tmux configuration. Your terminal may also have to be allowed to send notifications in your system’s settings.

herdr

Inside a herdr pane, Luxe tells herdr whether it is working, idle, or waiting on you, and why: Approve bash, or the question it asked. herdr shows that in its sidebar, raises its own notification when Luxe finishes or needs you (set in herdr’s [ui.toast]), and reports it to herdr agent wait. After a herdr restart, the pane reopens the same session with luxe --resume. Luxe sends no escape-sequence notifications inside herdr, because herdr keeps them for itself.

Recipes has a Luxe palette for herdr’s theme.

This is local to your machine and on by default. Outside herdr nothing is sent. LUXE_HERDR=0 in the environment stops the reports, and so does the config:

{ "herdr": false }

Update notice

Once a day, Luxe checks whether a newer release exists and says so on the start screen, with the command to update. Luxe never updates itself. The check sends nothing about you or your machine; the comparison happens locally.

{ "update": { "check": false } }

LUXE_UPDATE_CHECK=0 turns it off as well.

Launchers

A launcher gives a key to a program that takes over the terminal and gives it back, such as gh-dash or lazygit:

{
  "launchers": [
    { "key": "alt+g", "command": "gh-dash" },
    { "key": "ctrl+alt+l", "command": "lazygit" }
  ]
}

Luxe keeps running underneath and redraws when the program exits. Text the program writes to the file named by $LUXE_HANDOFF is put in the composer, so a gh-dash command can send #123 look at this to Luxe. A launcher’s key wins over any other binding.

Reference

Every key in config.json, with its default.