Files
luxe/crates/luxe-cli/src/guide.md
Evan Whittaker f014ead3b9 Luxe installs with curl -fsSL https://luxe.dev/install.sh | sh, edits keep a file's permissions, and the tools page charts every agent by name
- luxe.dev/install.sh redirects to the latest release's installer, and luxe.dev/install.ps1 runs
  the release's PowerShell installer under Windows' default policy, so the commands are
  `curl -fsSL https://luxe.dev/install.sh | sh` and `powershell -c "irm https://luxe.dev/install.ps1 | iex"`.
  The install tabs run shell, brew, cargo, then windows.
- The edit and write tools and format-on-save keep a file's mode, so editing a script no longer
  leaves it unrunnable.
- The tools page gives Claude Code and Codex their own columns and bars, draws Luxe's own bar in
  each group, and its terminal's window controls take macOS's colors.
- scripts/aur-pkgbuild.sh writes a luxe-bin PKGBUILD from a release, for the AUR once it reopens.
2026-10-17 20:05:01 -05:00

234 KiB
Raw Blame History

@@@ page: agent

title: "How the agent works" summary: "How the agent writes to you, asks you questions, plans, and gets a second opinion." order: 11 group: "Using Luxe"

How it writes

The agent is told to keep its replies short and direct, in every mode:

  • The answer first, then the reason, then any caveats
  • No filler, and no narrating tool calls you can already see
  • Plain words over jargon, casual and quick to read
  • One question at a time, with a recommended option
  • Finished work in a couple of lines: what changed, what was checked, what is left

It is also told to be honest about what it knows. A guess is labeled as a guess, and "I don't know" is a complete answer. It never says something passed that it did not run, and corrects a wrong answer as soon as it notices.

When it changes code, it reads what the change touches first, then reaches for the simplest thing that works: what is already in the codebase, then the standard library, then a platform feature, then a dependency the project already has. It leaves the work uncommitted unless you ask for a commit. A command that is yours to run, such as sudo, it gives you in a code block to run in your own terminal.

None of this is a setting. To change how it talks to you, say so ("go more technical with me"), or put it in your project's AGENTS.md to make it stick.

Questions

When the agent needs a decision, it asks in a picker. Each option has a one-line reason, the one it recommends is marked and selected, so agreeing is one keypress. The last option is always Type your own answer: start typing anywhere and it's picked, so enter sends what you wrote.

A question from the agent, with its recommended answer selected

Number keys pick an option, and in a question with one answer they send it. Your answer stays in the conversation as a card, like the one above the picker. In runs with nobody to answer, such as --headless, the agent takes the default it named, or else its recommended option.

Plan, then build

A session is in one of two modes, named in the composer's title and in the dock's MODEL section:

Mode Does
build Changes files and runs commands. The default.
plan Reads, searches and asks, and writes only PLAN.md

Switch with shift+tab, by clicking either, or with /mode plan and /mode build. luxe --plan starts in plan mode. In plan mode the composer, and the questions the agent asks there, take a second color.

Plan mode is held in code, not asked for. An edit to any other file, a shell command or a test run is refused before it runs, and the agent is told why. Switching changes neither the system prompt nor the tools, so it does not re-read the conversation at full price.

In plan mode the agent asks its open questions one at a time, then writes the plan as one ## Phase N section per phase, numbered from 0, which is the shape luxe loop works through. When a turn writes the plan, Luxe asks what next:

  • Build it here, with the planning conversation still in context
  • Build it in a fresh session, starting from PLAN.md alone
  • Run it as a loop: switch to build and say how to start luxe loop, which works phase by phase with your checks and a review at each
  • Keep planning

To plan into other files, or on a stronger model:

{
  "plan": {
    "files": ["PLAN.md", "docs/design/*.md"],
    "model": "anthropic/claude-opus-5",
    "thinking": "high"
  }
}

The first plain file in files is where the plan goes. A model of its own costs something: each model keeps its own prompt cache, so entering plan mode on another model reads the whole conversation again at full price. --model or LUXE_MODEL wins over plan.model, and --thinking over plan.thinking.

To start every session in plan mode:

{ "agent": { "default_mode": "plan" } }

A second opinion

/review has a reviewer read the uncommitted changes, new files included, in a fresh context: a separate session that never sees this conversation and changes nothing. Add what to look at hardest: /review error handling. What it would fix goes to the agent as its next turn, and the agent may push back on a finding it thinks is wrong. A clean review is only shown.

The reviewer runs on your session's model unless you name another. A fresh context is most of what makes a review useful; another vendor's model adds a second set of blind spots, for a second bill.

{ "reviewer": { "model": "openai/gpt-5.6", "thinking": "high" } }

The same reviewer is the second check in luxe loop.

Which model a session starts on

In order, the first that is set:

  1. --model and --thinking on the command line
  2. LUXE_MODEL and LUXE_PROVIDER in the environment
  3. The model you last chose
  4. default_model in models.json

Luxe never picks a model for you. With none of these set, sending a message opens the model picker, and --headless and the loop refuse to start. To always start from your configured default rather than your last choice:

{ "agent": { "remember_model": false } }

Turn limits

A turn runs until the agent stops calling tools or you stop it with ctrl+esc. To cap the rounds of tool calls in one turn, where calls the model makes together count as one round:

{ "agent": { "max_tool_iterations": 200 } }

At the cap, the agent gets one last reply with no tools, to summarize what it did and what is left. LUXE_MAX_TOOL_ITERATIONS sets the cap for one run, and 0 lifts it. @@@ page: appearance

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
{ "theme": "nord" }

An unknown name falls back to luxe, and Luxe says so when the session opens. See them all on luxe.dev.

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.

{
  "colors": {
    "accent": "#7aa2f7",
    "diffAddBg": "#12331f",
    "diffDelBg": "#3a1620"
  }
}

The names are the ones a theme file uses; luxe.json lists every one.

One more name is optional: modePlan, the color plan mode 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.

{
  "vars": { "harbor": "#2f7d8c" },
  "colors": { "accent": "harbor", "borderAccent": "harbor" }
}

This is also how to have a light theme. Start from a copy of 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.

{
  "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. 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
{ "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), 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

{
  "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:

{ "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
{ "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 for its styles, and for skipping it. @@@ page: cli

title: "Command line" summary: "Every luxe command and flag." order: 2 group: "Reference"

luxe with no command opens the interface. luxe --help, and --help after any command, prints the same reference. luxe --version prints the version.

Starting a session

Flag Does
-c, --continue Resume the most recent session in this project
--resume <id> Resume a session by ID; see luxe sessions list
--from-pr <number> Resume the session that worked on a pull request
--issue <number> Start on a GitHub issue, in a worktree of its own
--pr <number> Check out a pull request in a worktree and start a session there
--worktree [<branch>] Work in a worktree of its own, on a new or named branch
--plan Start in plan mode: read, ask, and write only the plan

See Git and GitHub and Sessions and context.

Model

Flag Does
--model <id> The model, as an ID or provider/id, which also picks the provider
--provider <id> The provider
--thinking <level> off, minimal, low, medium, high, xhigh or ultra. An unknown level is ignored with a warning.
--api-key <key> The key, or $VAR, or !command. A key typed here is visible to other users of the machine, so prefer the other two.
--base-url <url> The endpoint, including its version, such as /v1

These win over the environment and your config for this run only. See Models and providers.

Permissions and tools

Flag Does
--permission-mode <mode> default, strict, read-only or yolo
--read-only The same as --permission-mode read-only
--yolo Allow everything, with the guardrails off
--auto-approve Start with every prompt approved. Interface and --rpc only.
--on-ask <allow|deny> What a prompt becomes with nobody to answer: allow by default. Headless and loop only.
--trust-project Let a project's hooks, permission rules and servers apply
--no-tool <name> Turn a tool off for this run
--with-tool <name> Turn on a tool your config turned off

An unknown --permission-mode stops the run with an error. It never falls back to a more permissive mode.

See Security and permissions and Tools.

Without the interface

Flag Does
--headless Run one prompt and exit
-p, --prompt <text> The prompt, for --headless
--format <text|json> text streams the reply to stdout and tool activity to stderr. json writes one event per line, with token usage.
--rpc Speak the RPC protocol on stdin and stdout
--github-writes Let an --rpc client publish to GitHub: comments, reviews, thread answers, and opening, merging or restacking pull requests. Refused under --read-only.
luxe --headless -p "list the TODO comments in src/" --format text

A headless run needs -p and a model: --model, LUXE_MODEL, your last choice or default_model in models.json. It refuses to start without either. It exits with status 1 when the turn fails or Luxe stops before the turn ends, so a script can tell a failure from an answer without reading the output.

Commands

Command Does
luxe auth login [provider] Sign in. --method api-key or subscription when a provider has both, --stdin to read a key from a pipe, --api-key <key> to store one given here, --no-verify to skip checking it.
luxe auth list Every provider and how it is configured
luxe auth status [provider] A credential's type, where it came from, and when it expires
luxe auth logout <provider> Remove a stored credential
luxe models list Models you can use. --provider <id> filters, --configured lists only the models models.json or auth.json names.
luxe models show <provider/id> What Luxe knows about a model, and where each value came from. A bare ID uses the active provider.
luxe models refresh Refresh the model catalog. --force even if it is fresh.
luxe sessions list Sessions in this project, newest first
luxe mcp list Configured MCP servers
luxe mcp add --id <id> --name <name> Add a server to the project's .luxe/mcp.json, with --command "<program> <args>" or --url <url>. It counts as a project's server.
luxe mcp remove --id <id> Remove a server from the project's .luxe/mcp.json
luxe mcp tools Every server's tools
luxe mcp login --id <id> Sign in to a server, in a browser
luxe loop start Start or continue an autonomous run. --max-turns, --compact-percent, --pause-percent, --quiet.
luxe loop status The run's iteration, phase and cost
luxe loop pause, luxe loop resume, luxe loop stop Pause, clear a pause, or stop the run
luxe loop phase The current phase. --set <n> changes it.
luxe loop fresh Reset the run's turn count; see Autonomous runs
luxe docs [page] Read this guide, offline and for the installed version. --search <words> finds lines across every page.
luxe doctor Check which tools, language servers and debug adapters work
luxe update Update Luxe with the command for however it was installed; see Updates. --check only reports.
luxe init Set up a theme, a provider, the tools and the start screen, and write them to ~/.config/luxe/config.json. --defaults skips the questions, --force starts from an empty file; see Editing.
luxe wire <log> Summarize a LUXE_WIRE_LOG capture; see Troubleshooting. --tools breaks the tool schemas' size down per tool.

Every command also takes the model and permission flags above. @@@ page: commands

title: "Commands and keys" summary: "The Command Palette, slash commands, Help, every default key, and how to rebind them." order: 4 group: "Using Luxe"

Command Palette and slash commands

Every command is in two places:

  • Command Palette (ctrl+k) opens over whatever you are doing, anywhere, with your draft left where it was.
  • Slash commands: type / at the start of an empty composer and the same commands open above it.

The Command Palette, with the commands used last at the top

Both list only what can run where you are, with the five you used last at the top. Type to filter by name, slash command or a few words each is known by: exit finds Quit. A pane beside the list says what the command does and the arguments it takes.

enter runs a command. In the slash list, tab puts it in the composer so you can add arguments: /diff pr 142, /dock left, /compact the API decisions.

Past the command, the list shows the arguments it takes, such as /diff turn or /diff pr <number or URL>, and narrows as you type. tab fills in the one under the cursor. enter runs it when nothing is missing, and fills it in when it still needs a value. esc puts the list away for that command. In the composer, a command Luxe knows is highlighted, and so are the words of it you have typed, like pr in /diff pr 142. A command that stays plain is misspelled.

Slash commands

Command Does
/help Every key for this screen, as you have bound them
/model Change the model; the session carries on
/thinking How hard the model reasons, from Off to Ultra
/mode Switch between build and plan mode: /mode, /mode plan, /mode build (shift+tab)
/review A second opinion on the uncommitted changes: /review, /review error handling
/new Start a new session. The current one is kept.
/sessions Find another session in this project and pick it up; see Sessions
/context What fills the context window, largest first
/compact Summarize the conversation now. Add what to keep: /compact the API decisions.
/cost What this session has cost, by model and kind of token
/search Find text in the conversation
/diff Open a Guided Review: /diff, /diff turn, /diff base main, /diff commit <sha>, /diff pr 142
/preview Preview a file, whole or as its diff: /preview, /preview src/app.rs
/editor Open the project in your editor, or a file: /editor, /editor src/app.rs, /editor src/app.rs:42
/pr This branch's pull request: status, reviewers and conversation
/github Pull requests and issues on GitHub
/stack Restack a stack of pull requests
/worktree Where this session works. /worktree remove ends it and removes its worktree.
/dock Show or hide the dock: show, hide, auto, left, right
/statusline Show or hide the statusline: show, hide, auto
/theme Preview and choose a theme
/mouse Mouse capture on or off
/images What this terminal can draw, and why
/permissions Approve every tool call that would ask you: on, off. Deny rules still apply.
/tools Every tool the agent can use this run, and the ones it cannot
/lsp Language servers: which started, and what they are doing
/debug Debug adapters, and whether each can be reached
/mcp MCP servers, and the tools each offers
/config Providers, credentials, settings and config files
/settings Settings as controls: appearance, the conversation, the dock, tools and the agent
/login, /logout Add or remove a provider's credential
/auth Which providers you are signed in to, and how
/reload Re-read your config and keys without restarting
/quit Leave Luxe. The session is already saved.
/update Leave Luxe and update it, as luxe update does

The Command Palette also lists commands with no slash form, such as Copy message, Swap the sidebar's side and, in a review, Send comments.

Help

Help (/help) shows every key for the screen you are on, grouped and drawn from your own bindings. In Guided Review it shows the review's keys. Help has no default key, because the obvious ones do not reach a terminal program reliably. To give it one:

{ "tui.app.toggle_help": ["f1"] }

Default keys

The name in the last column is what keybindings.json uses.

Compose

Key Does Name
enter Send, or steer a running turn
shift+enter New line tui.editor.new_line
alt+q Queue the message for the next turn tui.editor.queue_message
alt+↑ Bring waiting messages back tui.editor.dequeue_message
ctrl+esc Stop the turn tui.editor.cancel
ctrl+v, shift+insert Paste tui.editor.paste
alt+a Select the whole draft tui.editor.select_all

enter and alt+enter are fixed. ctrl+enter also sends, as tui.editor.submit.

Read

Key Does Name
ctrl+↑, ctrl+↓ Scroll tui.convo.scroll_up, tui.convo.scroll_down
pageup, pagedown Scroll a page tui.convo.page_up, tui.convo.page_down
ctrl+f Search the conversation tui.convo.search
alt+k, alt+j Select the previous or next message tui.convo.select_block_up, tui.convo.select_block_down
ctrl+o Full tool output tui.convo.toggle_tool_output
alt+i View image tui.convo.open_image
alt+y Copy message tui.convo.copy_message
ctrl+insert, ctrl+shift+c Copy selection tui.convo.copy_selection

Conversation

Key Does Name
alt+e Edit and resend your last message tui.convo.edit_resend
alt+t Ask again tui.convo.retry
alt+g Replace the last answer tui.convo.regenerate

An edit replaces your last message and the answer to it, and Replace the last answer drops the old answer, so the model sees only the new version. Ask again sends your last message once more, after the answer if there was one. The replaced messages stay in the session file but leave the conversation. All three wait for a running turn to finish.

Workspace

Key Does Name
ctrl+k Command Palette tui.app.open_palette
shift+tab Switch between build and plan mode, from the composer or the start screen tui.app.cycle_mode
alt+d Show or hide the dock tui.workspace.toggle_dock
alt+s Show or hide the statusline tui.statusline.toggle
ctrl+p Preview tui.preview.toggle
alt+n, alt+p Next or previous changed file, in the preview tui.preview.file_next, tui.preview.file_prev
alt+w Wrap long lines, in the preview tui.preview.toggle_word_wrap
alt+o Open the file in your editor, in the preview tui.preview.open_in_editor
alt+m Show a changed file whole, or its diff, in the preview tui.preview.toggle_view
alt+l Ask about the lines you picked, in the preview tui.preview.ask_about_selection
ctrl+t Move the keyboard into the dock's file tree, then into the file showing tui.workspace.focus_files
ctrl+g Guided Review tui.review.open
ctrl+shift+r Reload config and keys tui.app.reload
ctrl+c Quit tui.app.quit

Guided Review

Key Does Name
c Comment on this line tui.review.add_finding
a Ask the agent tui.review.ask
alt+enter Finish review tui.review.finish
alt+u Send comments tui.review.send
alt+c All comments tui.review.findings
e Edit the selected comment tui.review.edit_finding
x Delete the selected unsent comment tui.review.delete_finding
r Resolve or reopen the selected comment tui.review.resolve_finding
alt+r Reanchor the selected stale comment tui.review.reanchor_finding
], [ Next or previous chapter tui.review.chapter_next, tui.review.chapter_prev
n, shift+n Next or previous hunk tui.review.hunk_next, tui.review.hunk_prev
enter Open what the cursor is on tui.review.open_selection
home Back to column zero tui.review.line_start
g, alt+v Show or hide the guide tui.review.toggle_guide
f Open or fold collapsed churn tui.review.toggle_noise
ctrl+b Side by side, or one column tui.review.toggle_split
w Wrap long lines tui.review.toggle_word_wrap
s Change what is reviewed tui.review.source
ctrl+r Refresh the review tui.review.refresh
o Open on GitHub tui.review.open_in_browser
shift+e Open the file in your editor, at the cursor's line tui.review.open_in_editor
alt+← Back to the conversation tui.review.return_chat
? Help tui.review.help

Rebind keys

Put your bindings in ~/.config/luxe/keybindings.json, or open it from Configuration with Edit configuration files. Each entry is a name from the tables above and a list of keys:

{
  "tui.app.open_palette": ["ctrl+p"],
  "tui.preview.toggle": ["alt+p"],
  "tui.app.toggle_help": ["f1"]
}
  • A binding replaces that action's default keys rather than adding to them.
  • A key you bind is taken from any action that had it by default.
  • A key is modifiers and one key joined by +: ctrl, shift, alt, then a letter, a digit, enter, esc, tab, space, backspace, delete, insert, an arrow (up, down, left, right), home, end, pageup, pagedown, or f1 to f12.
  • An unknown name or key is skipped with a warning in the log, and the rest still load. An action whose keys are all invalid is left with none, rather than its defaults.
  • A project's .luxe/keybindings.json applies over yours.

/reload or ctrl+shift+r applies a change without restarting.

Alt keys on a Mac

A Mac has no Alt key. Its Option key types characters instead: option+o is ø, option+p is π. Most of Luxe's alt keys need your terminal to send Option as Alt:

Terminal Setting
Ghostty macos-option-as-alt = true (or left)
iTerm2 Profiles › Keys › Left Option key: Esc+
Terminal Settings › Profiles › Keyboard › Use Option as Meta key
kitty macos_option_as_alt yes
WezTerm Left Option already sends Alt; for the right one, send_composed_key_when_right_alt_is_pressed = false
Alacritty option_as_alt = "Both" under [window]

Ghostty already does this on the "U.S." keyboard layouts. On the others it sends the character and marks it as an Alt key. On "ABC", the Mac's default English layout, Luxe reads that back as the key you pressed, so option+o opens a file from the preview without any setting. On other layouts, set the option above. @@@ page: configuration

title: "Configuration" summary: "Where Luxe's files live, what a project can set, and every key in config.json." order: 1 group: "Customize"

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.

File Holds In a project
config.json Appearance, behavior, and the settings on this page .luxe/config.json, over yours
keybindings.json Your keys; see Commands and keys .luxe/keybindings.json, over yours
models.json Model and provider settings; see Custom providers
auth.json Credentials; see Models and providers
permissions.json What the agent may do; see Security .luxe/permissions.json, which can only tighten yours
hooks.json Commands run at points in a turn; see Hooks .luxe/hooks.json, only with --trust-project
mcp.json MCP servers; see MCP .luxe/mcp.json or .mcp.json
lsp-servers.json Language servers; see Tools
debug-adapters.json Debug adapters; see Tools
agents.md Instructions for every project; see Project context AGENTS.md
themes/ Your own themes; see Appearance
skills/ Your own skills; see Skills .luxe/skills/ or .agents/skills/

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

The Tools page of the 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.

To Key
Choose a setting ↑ / ↓
Turn it on or off, or step to the next choice space, enter or →
Step back a choice ←
Remove it from your file, so the default applies r
Open config.json in your editor e
Search every page /
Change page tab, or 1 to 5

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"] }
Name When
turn A turn finished or failed
permission A tool call is waiting for your approval
question The agent asked you something
review A Guided Review finished writing its guide

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 }

Updates

Once a day, Luxe checks whether a newer release exists, and when one does the start screen says Update available · /update. The check sends nothing about you or your machine; the comparison happens locally.

/update, or luxe update in a shell, updates Luxe with the command for however you installed it, showing each one before it runs:

Installed with luxe update runs
The install script luxe-cli-update, the updater it put beside luxe
Homebrew brew update, then brew upgrade luxe
Cargo cargo install --locked --force luxe-cli

Luxe never downloads or replaces its own program; whatever installed it does. A copy your system's package manager owns is left to it, and a downloaded archive points you at the releases page. On Windows, Luxe can't be replaced while it runs, so it prints the command to run once it has exited. Afterwards it checks that the luxe your shell finds is the new version, and says so if another copy earlier on your PATH is in the way. luxe update --check only reports.

To stop the daily check:

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

LUXE_UPDATE_CHECK=0 turns it off as well. luxe update still checks when you run it.

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.

Key Default Does
theme your Omarchy theme, else luxe The theme; see Appearance
colors Single color overrides; see Appearance
glyphs auto Which icons to draw; see Appearance
images auto How images are drawn; see Appearance
mouse true Capture the mouse; see The interface
dashboard true Open on the start screen. false skips it; { "style": "minimal" } shows the prompt alone.
banner_animation true The shine across the start screen's logotype
show_key_hints true The key hint beside messages waiting for a turn
notifications false Desktop notifications: true, or a list of moments; see Notifications
notification_method auto auto, osc9 or osc777
bell false Terminal bell when a turn ends or something waits on you
herdr true Report the agent's state to herdr; see herdr
statusline.visibility auto auto, shown or hidden; see Appearance
statusline.style slab slab or flat
statusline.left ["project", "branch", "pr", "todo", "changes"] Modules on the left
statusline.right ["context", "cost", "tokens", "thinking", "model"] Modules on the right
statusline.thinking_colors false Color the thinking level
dock.mode auto auto, shown or hidden; see The interface
dock.position left left or right
conversation.alignment full full, left or center; see Appearance
conversation.prose_max_width 120 Text width under left or center
conversation.wide_block_max_width 140 Code and table width under left or center
conversation.growth bottom bottom or top
conversation.thinking shown shown, collapsed or hidden
conversation.tool_runs fold fold or cards
conversation.tool_details errors errors, all or collapsed
conversation.stream_reveal smooth smooth or off
conversation.activity_bar bars bars, dots or off
conversation.scroll_lines 3 Lines per wheel notch, 1 to 20
conversation.image_max_rows 24 Tallest image, in rows
diff.layout auto auto, split or unified; see Appearance
diff.word_wrap false Wrap long lines in Guided Review
review.exclude [] Files every review leaves out; see Guided Review
review.context_files [] Extra files a review reads for what the change was for, beside PLAN.md and AGENTS.md
tools.disabled [] Tools to turn off; see Tools
tools.format_on_save true Format each file the agent changes; see Tools
tools.clone_repositories true Clone a GitHub repository web_fetch is given; see Tools
lsp.project_servers auto auto, always or never; see Tools
compaction.auto true Summarize when the window fills; see Sessions and context
compaction.at 0.9 How full before summarizing
compaction.keep_recent 20000 Tokens kept word for word
compaction.reserve 20000 Tokens held back for the reply
compaction.prune true Replace old tool output first
compaction.summarizer the session's model The model that writes the summary
agent.default_mode build The mode a session starts in: build or plan; see Plan, then build
plan.files ["PLAN.md"] Files or globs plan mode may write; the first plain file gets the plan, or a file matching the first glob
plan.model the session's model Plan mode's model, as provider/id; switching to it re-reads the conversation at full price
plan.thinking the session's Plan mode's thinking level
reviewer.model the session's model The model /review and the loop's gate ask; see A second opinion
reviewer.thinking the session's The reviewer's thinking level
reviewer.tools read-only tools Tools a review may call; whatever you list, a review changes nothing
agent.remember_model true Start on the model you last chose
agent.max_tool_iterations none Most rounds of tool calls in one turn
agent.on_ask allow What a permission prompt becomes with nobody to answer; see Autonomous runs
agent.cache_warming streaming off, streaming or idle; see Keeping the cache warm
gate.commands [] Commands a phase must pass; see Autonomous runs
gate.timeout_secs 600 Longest one gate command may run
gate.review on when reviewer.model is set Have a reviewer read each phase after the commands pass
worktree.always false Give every session a worktree; see Git and GitHub
github.refresh_secs 60 Seconds between pull request checks; see Git and GitHub
github.sections What /github lists
update.check true Look for a newer release
launchers [] Keys that open other programs; see Launchers
mentions [] Your own @ sources; see Mention sources
@@@ page: custom-providers

title: "Custom providers" summary: "Connect any endpoint, and set a model's context window, thinking levels, request format and samplers." order: 6 group: "Extend"

Luxe knows how to reach every provider in Models and providers, and the models.dev catalog tells it each model's context window, output limit, thinking levels and price. This page is for what neither covers: your own endpoint, a model the catalog does not know, or a local server that needs its requests shaped a particular way.

Everything here goes in ~/.config/luxe/models.json. luxe models show <provider>/<id> shows what Luxe resolved for a model, and where each value came from.

Add an endpoint

Connect a local or custom model in Configuration asks for an endpoint and writes it here. By hand:

{
  "providers": {
    "gateway": {
      "base_url": "https://llm.internal.example.com/v1",
      "api_key": "$GATEWAY_KEY",
      "api": "openai-completions"
    }
  },
  "models": {
    "gateway/qwen3-coder-480b": { "context_window": 262144, "max_tokens": 65536 }
  }
}

Then luxe --model gateway/qwen3-coder-480b, or choose it in /model.

Provider key Does
base_url The endpoint, including its version, such as /v1
api_key The key: the value, $VAR, ${VAR} or $env:VAR, or !command, which runs each time a request needs the key. An unset ${VAR} is empty, as in mcp.json, and Luxe logs which one.
api The API it speaks: openai-completions (the default), openai-responses, anthropic-messages
auth How the key is sent: bearer, x-api-key, api-key, or foundry for both of the last two
models_dev The models.dev provider to take model details from, when the names differ
compat How requests are shaped; see Request format
sampling_params Samplers for every model it serves; see Samplers

A provider in models.json replaces the same provider's block in auth.json whole, so keep a provider's key and endpoint in one file. A provider Luxe already knows keeps everything you do not write. A key in a provider Luxe knows is used when its own variable, such as OPENAI_API_KEY, is unset; for one it does not know, the key you write comes first and OPENAI_API_KEY is the fallback. A key you signed in with comes before either.

A file Luxe cannot parse is skipped with a warning in the log, and a misspelled key is ignored, so check the result with luxe models show <provider>/<id> after editing.

Model settings

Settings for one model go under models, by provider/id. Each value overrides the catalog's, and everything you leave out still comes from it. thinking_level_map, modalities and cost each replace the catalog's whole: a cost you write drops the catalog's long-prompt prices, and an output price you leave out is free.

Key Does
context_window The model's context window, in tokens
max_tokens The most it may write in one reply. Defaults to the model's own limit from the catalog. Luxe lowers it per request to what the window has left, so setting the real limit is safe; setting a lower one is how replies get cut off.
name The name shown in the picker and statusline
reasoning Whether it can think
thinking The level a session starts at for this model
thinking_level_map What each thinking level sends; see below
modalities What it accepts: ["text"] or ["text", "image"]
cost Prices per million tokens: input, output, cache_read, cache_write, and cache_write_1h for a write kept for an hour (twice input if unset)
compat, sampling_params Override the provider's, key by key

A model the catalog does not know gets a 128k context window and no output limit until you set them. Anthropic endpoints require a limit, so there Luxe asks for 128k. If the model allows less, Anthropic's refusal names its real limit, and Luxe retries with that and uses it for the rest of the session.

Thinking levels

thinking_level_map says what each of Luxe's levels sends to the model. null marks a level the model cannot do, removing it from /thinking; a level Luxe needs falls back to the nearest one that is left. ultra is the name for a provider's max.

{
  "models": {
    "lmstudio/qwen3.8-27b": {
      "reasoning": true,
      "thinking": "medium",
      "thinking_level_map": {
        "off": "none",
        "minimal": null,
        "low": "low",
        "medium": "medium",
        "high": "high",
        "xhigh": "high",
        "ultra": null
      }
    }
  }
}

A level you do not map sends its own name, and off sends none; xhigh and ultra are offered only once mapped. Setting a map also marks the model as one that reasons.

An endpoint Luxe does not know sends no thinking setting at all until its compat says how: for most OpenAI-compatible servers, "thinking_format": "openai", which sends reasoning_effort on every request, off included. See Request format.

For Anthropic models, Luxe uses adaptive thinking with an effort level where the model supports it, and a token budget for older ones. If a model refuses how thinking was requested, Luxe tries the other way once and remembers it for the session. compat.force_adaptive_thinking forces adaptive thinking for an endpoint the catalog does not know.

Request format

compat says how a request has to be shaped for an endpoint to accept it. On a provider it applies to every model the provider serves; on a model, only the keys you write override the provider's.

{
  "providers": {
    "lmstudio": {
      "base_url": "http://127.0.0.1:1234/v1",
      "compat": { "supports_developer_role": true, "supports_reasoning_effort": true, "thinking_format": "openai" }
    }
  },
  "models": {
    "lmstudio/qwen3.6-27b-fable-fusion": {
      "compat": { "thinking_format": "chat_template", "supports_developer_role": false }
    }
  }
}
Flag Does
supports_developer_role Send the system prompt as developer rather than system
supports_reasoning_effort Allow reasoning_effort to be sent
thinking_format How thinking is requested: openai, qwen, deepseek, openrouter, together or chat_template
chat_template_kwargs What to send for chat_template; see below
max_tokens_field max_tokens or max_completion_tokens
supports_usage_in_streaming Ask for token usage while streaming. On by default.
requires_tool_result_name Name the tool on each tool result. gpt-oss needs this.
cache_control_format How prompt caching is requested: anthropic or openrouter
force_adaptive_thinking Use Anthropic's adaptive thinking
supports_long_cache_retention Ask Anthropic to keep cached prompts for an hour rather than five minutes. Each cache write costs 2x input instead of 1.25x. Off by default, since not every Anthropic-compatible endpoint accepts it.
stream_tool_arguments Stream a write call's file from Anthropic as it is written, so its card fills in live. On by default; turn off for an endpoint that rejects a tool's eager_input_streaming field.
defer_tool_loading Load a tool the agent asks for with activate_tools where it asked, so the cached prompt stays cached. On by default. Luxe stops on its own for an endpoint that refuses it; turn it off for one that accepts it and then misbehaves. Anthropic and Responses endpoints only.
copilot_headers, openrouter_headers Send those services' identifying headers. With copilot_headers, each model also goes to the Copilot endpoint it takes.
use_responses_api Use OpenAI's Responses API. Provider only; prefer "api": "openai-responses".

anthropic-messages endpoints read only force_adaptive_thinking, cache_control_format, supports_long_cache_retention, stream_tool_arguments, defer_tool_loading and copilot_headers. The rest are for OpenAI-style endpoints. luxe models show lists any flag that differs from the provider's.

Samplers

A local model's card often gives a sampling recipe with settings the OpenAI format has no field for, such as top_k, min_p and repeat_penalty. sampling_params is added to the request as written, after Luxe's own fields, so its values win:

{
  "models": {
    "lmstudio/qwen3.8-27b": {
      "sampling_params": { "temperature": 1.0, "top_p": 0.95, "top_k": 20, "min_p": 0.0 }
    }
  },
  "providers": {
    "lmstudio": { "sampling_params": { "min_p": 0.0 } }
  }
}

A provider's samplers apply to every model it serves, and a model's override them one key at a time. Nothing is checked, so an unknown key goes to your server as is; model, messages, input, stream and tools are refused. OpenAI-style endpoints only.

Chat templates

A server that renders the model's chat template, such as llama-server, takes thinking settings as chat_template_kwargs. Each template names them differently, so you describe them:

{
  "providers": {
    "llama-server": {
      "base_url": "http://127.0.0.1:8080/v1",
      "compat": {
        "thinking_format": "chat_template",
        "chat_template_kwargs": {
          "enable_thinking": { "$var": "thinking.enabled" },
          "reasoning_effort": { "$var": "thinking.level", "omit_when_off": true },
          "preserve_thinking": true
        }
      }
    }
  }
}

thinking.enabled becomes true or false, and thinking.level the value thinking_level_map gives the current level. omit_when_off leaves the key out when thinking is off. Anything else is sent as written. LM Studio ignores chat_template_kwargs; use "thinking_format": "openai" there.

Model details

Luxe takes a model's details from three places, each overriding the one before, value by value:

  1. The models.dev catalog built into Luxe, which works offline
  2. A fresher copy, refreshed in the background into ~/.cache/luxe/models-dev.json
  3. Your models.json
$ luxe models show anthropic/claude-opus-5
anthropic/claude-opus-5
  name              Claude Opus 5  [models.dev]
  context window    1.0M  [models.dev]
  max output        128k  [models.dev]
  reasoning         true  [models.dev]
  thinking levels   high, low, medium, ultra, xhigh  [models.dev]
  thinking control  effort (adaptive thinking), never off  [models.dev]
  modalities        text, image  [models.dev]
  cost /Mtok        $5.00/$25.00  [models.dev]

Each value names where it came from: snapshot for the catalog built into Luxe, models.dev for the refreshed copy, config for your models.json, and default where none of them said.

Variable Does
LUXE_MODELS_DEV_REFRESH=0 Never refresh; the built-in catalog still answers
LUXE_MODELS_DEV_URL Refresh from a mirror
LUXE_MODELS_DEV_PATH Keep the catalog in this file instead. The refresh writes there too, so pair it with LUXE_MODELS_DEV_REFRESH=0 to pin a file of your own.
LUXE_MODELS_DEV_TTL Seconds between refreshes. 21600 by default.

Microsoft Foundry

Keyless sign-in with Microsoft Entra ID

If your Foundry resource has key sign-in turned off, give Luxe a command that prints a token:

{
  "providers": {
    "foundry-anthropic": {
      "auth": "bearer",
      "api_key": "!az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv"
    },
    "foundry-openai": {
      "api_key": "!az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv"
    }
  }
}

Run az login first. Only the Claude provider needs auth; the others already send a bearer token. The command runs for each request and nothing is kept, so a token from az, which lasts about an hour, is replaced as it expires and a long session carries on.

Choose which deployments Luxe offers

Luxe records what a resource has deployed in each provider's served_models, and the model behind any deployment named something else in deployments, which is where it looks up the context window and price. If your key cannot list deployments, or you want to choose the list yourself, turn discovery off and write both:

{
  "providers": {
    "foundry-anthropic": {
      "discover_deployments": false,
      "served_models": ["sonnet-prod", "claude-opus-5"],
      "deployments": { "sonnet-prod": "claude-sonnet-5" }
    }
  }
}

discover_deployments: false on any of the three providers stops Luxe asking the resource at all.

Thinking on partner models

foundry-completions sends no thinking setting by default, because its models disagree on how to take one. Turn it on per model:

{
  "models": {
    "foundry-completions/deepseek-v4-flash": {
      "compat": { "supports_reasoning_effort": true },
      "thinking_level_map": { "high": "high", "ultra": "max" }
    }
  }
}

Use reasoning_effort only: Foundry refuses DeepSeek's own thinking format. Foundry does not report these models' thinking tokens, so /cost counts them as output.

A Foundry deployment can have a different context window and price from the vendor's own API. Luxe uses Azure's figures for Foundry models.

OpenRouter

  • Luxe asks OpenRouter to cache prompts for Claude models, which it otherwise does not, and which makes later turns of a session far cheaper. "cache_control_format": null in the provider's compat stops it.
  • Some models on OpenRouter cannot turn thinking off. For those, Luxe leaves the setting out and the model thinks at its own default. luxe models show openrouter/<id> says never off.
  • Luxe identifies itself to OpenRouter with its HTTP-Referer and X-Title headers, which carry nothing about you. "openrouter_headers": false in compat drops them. @@@ page: environment

title: "Environment variables" summary: "The environment variables you can set, and the ones Luxe sets." order: 3 group: "Reference"

An environment variable wins over the same setting in a config file, and a command-line flag wins over both. A variable that turns something off, such as LUXE_HERDR=0, cannot turn back on what a config file turned off.

Model and provider

Variable Default Does
LUXE_MODEL The model, as an ID or provider/id
LUXE_PROVIDER The provider
LUXE_API_KEY A key for the provider the session starts on
LUXE_BASE_URL That provider's endpoint, including its version
ANTHROPIC_API_KEY, OPENAI_API_KEY, … Each provider's own key; see Models and providers
LUXE_STREAM_START_TIMEOUT 60 Seconds to wait for a reply to start. 0 waits forever.
LUXE_STREAM_IDLE_TIMEOUT 180 Seconds a reply may go quiet. 0 waits forever.
LUXE_PROVIDER_RETRIES 3 Tries after the first when a provider fails before answering
LUXE_COPILOT_PLAN_USAGE 1 0 stops reading how much of your GitHub Copilot plan is used

Files

Variable Does
LUXE_CONFIG_DIR Where configuration and credentials live, instead of ~/.config/luxe
LUXE_STATE_DIR Where Luxe keeps its state, such as the model you last chose, MCP sign-ins and the logs of commands that only report, instead of ~/.local/state/luxe
XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_CACHE_HOME Honored on every platform; see Install

When Luxe works out where its files go, a path in one of these, or in HOME, that is not valid UTF-8 is ignored, as if the variable were unset.

Model catalog

Variable Default Does
LUXE_MODELS_DEV_REFRESH 0 never refreshes, and the built-in catalog still works. 1 refreshes at every start. Unset refreshes once the copy is older than LUXE_MODELS_DEV_TTL.
LUXE_MODELS_DEV_URL https://models.dev/api.json Refresh from a mirror, as a full URL
LUXE_MODELS_DEV_PATH Keep the catalog in this file. The refresh writes there too, so pair it with LUXE_MODELS_DEV_REFRESH=0 to pin a file of your own.
LUXE_MODELS_DEV_TTL 21600 Seconds between refreshes

Tools and turns

Variable Default Does
LUXE_TOOL_TIMEOUT_SECS Replace the time limit of every tool that has one
LUXE_MAX_TOOL_ITERATIONS Most rounds of tool calls in one turn. 0 lifts a configured cap.
LUXE_COMPRESS 1 0 stops trimming long command output, though output past the size limit is still cut
LUXE_LSP_ON_EDIT 1 0 stops adding language server errors, and notes about missing tests, after edits
LUXE_SIZE_CHECK 1 0 stops telling the agent when an edit takes a file past 500 lines or a function past 20
LUXE_DEBUG_NUDGE 1 0 stops suggesting the debugger after repeated test failures
LUXE_PLAN_NUDGE 1 0 stops reminding the agent to update its checklist
LUXE_LAZY_TOOLS 1 0 sends every tool's description with every request
LUXE_CORE_TOOLS The tools sent with every request, comma-separated; the rest load when needed
LUXE_DAP_STOP_TIMEOUT_SECS 30 How long the debugger waits for a program to stop
LUXE_MAX_DEPTH 2 How deeply Luxe may run inside itself, as with subagents
LUXE_WEB_ALLOW_PRIVATE 1 lets web_fetch and screenshot reach your local network and files
LUXE_WEB_TIMEOUT_SECS 30 How long one fetch may take. Past 60, raise LUXE_TOOL_TIMEOUT_SECS too.
BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY Search providers, and Firecrawl for pages built with JavaScript; see Tools

Integrations

Variable Does
LUXE_EDITOR, then VISUAL, then EDITOR The editor Luxe opens files in
LUXE_FILE_MANAGER, then FILE_MANAGER The file manager O in the dock's file tree opens a folder in. Without either, the first of yazi, lf, ranger and nnn that is installed, then your desktop's own.
LUXE_HERDR 0 stops reporting state to Herdr
LUXE_UPDATE_CHECK 0 turns off the update check

Diagnostics

Variable Does
LUXE_LOG What goes in the log, such as debug or luxe_core=debug. RUST_LOG works too. See Logs.
LUXE_WIRE_LOG A file to record every request sent to the model; see Troubleshooting

Set by Luxe

Variable Is
LUXE_DEPTH How deeply this run is nested inside another Luxe
LUXE_REVIEW_GATE_ACTIVE Set for a loop's gate commands, so a Luxe they start does not run a gate of its own
LUXE_HANDOFF For a launcher: a file whose contents go in the composer when the program exits
@@@ page: extending

title: "Extending Luxe" summary: "Which kind of extension you need, how to install one, and what stays stable across updates." order: 1 group: "Extend"

Luxe extends through files and programs, never through code loaded into Luxe itself. A file carries instructions or settings; a program carries behavior, and runs with the same access you have. Installing an extension is copying a file.

Which one you need

To Use Runs
Change how Luxe looks, or which tools exist Configuration and themes Nothing
Teach the agent a procedure or house style Skills and AGENTS.md Nothing
Point the agent at your tracker or runbooks with @ Mention sources Your program, when its tab opens
Give the agent new tools An MCP server Your program, when the agent calls it
Block, rewrite, audit or react to what the agent does Hooks Your program, at points in a turn
Use an endpoint or model Luxe does not know Custom providers Nothing, or your !command for a key
Drive Luxe from your own program, or build a new front end: conversation, Guided Review and GitHub The RPC protocol Your program, driving Luxe
Open another terminal tool with a key Launchers Your program, on a key

The rows are in order of effort; the first that fits is usually right. Recipes puts several together: Asana in the @ picker, subagents, a classifier guard, running in Herdr, and a local model in LM Studio.

Where extensions live

~/.config/luxe/
├── config.json           settings, launchers, mention sources
├── keybindings.json      keys
├── models.json           endpoints and models
├── permissions.json      what the agent may do
├── agents.md             instructions for every project
├── skills/
│   └── <name>/           a skill
├── hooks.json            hooks
├── mcp.json              MCP servers
├── themes/
│   └── <name>.json       a theme
├── lsp-servers.json      language servers
└── debug-adapters.json   debug adapters

<project>/
├── .agents/skills/       skills committed with the repository
├── .mcp.json             MCP servers
└── .luxe/
    ├── config.json       settings, less what a project cannot change
    ├── keybindings.json
    ├── skills/
    │   └── <name>/
    ├── mcp.json
    ├── hooks.json        only with --trust-project
    └── permissions.json  can only tighten yours, unless --trust-project

What a project's config.json cannot change is listed in Configuration. On Windows, your own folder is %APPDATA%\luxe, and LUXE_CONFIG_DIR moves it anywhere. These paths do not change between releases.

.luxe/ writes its own .gitignore, which keeps everything in it out of Git except permissions.json, mcp.json, hooks.json and skills/. To share more with your team, such as the project's config.json, write that .gitignore yourself: Luxe rewrites its own copy, but leaves alone one it did not write.

Trust

A repository does not choose what runs on your machine. Its hooks and its loop gate.commands run only with --trust-project, and its permission rules can only make yours stricter. MCP servers, language servers and formatters it brings start, by default, only in an interactive session or with --trust-project; lsp.project_servers in your own config changes that, see Tools. This is about which programs Luxe starts. A language server itself may run project code, as rust-analyzer does with build.rs, so open an unfamiliar repository in Luxe the way you would build it.

A repository can still write instructions. Its AGENTS.md and skills reach the model. Luxe removes text a reviewer cannot see, but plain text is still instructions, so read an unfamiliar repository's AGENTS.md as you would its Makefile.

What stays stable across updates

Across updates
config.json, models.json, keybindings.json, lsp-servers.json, debug-adapters.json Only added to. An old file always loads. An unknown key is ignored, and no key changes meaning.
Sessions in .luxe/sessions/ A newer Luxe reads every older session. An older Luxe skips what it does not know in a newer one.
The RPC protocol Adding to it changes nothing. Removing or renaming anything changes protocol_version.
Hook points Added, never renamed. An unknown point skips that hook alone, with a warning in the log.
Tool arguments A renamed argument still accepts its old name.
Skills and AGENTS.md Plain markdown
The paths above Do not move

Before 1.0, a minor release may change the RPC protocol and the hook points, and its release notes will say so. Config files and sessions keep the stronger promise regardless, since they are the two you cannot regenerate.

What Luxe will not add

  • Plugins loaded into Luxe. A plugin would have all of Luxe's access, however it was sandboxed.
  • A network listener for RPC. It would turn a local program into a service that needs authentication. @@@ page: github

title: "Git and GitHub" summary: "Worktrees, issues, opening and merging pull requests, review threads, and stacks." order: 7 group: "Using Luxe"

Everything that talks to GitHub goes through the GitHub CLI, gh, signed in with your own account (gh auth login). Without it, the rest of Luxe works and these features say why they cannot.

Work in a worktree

luxe --worktree                # a new branch, luxe/session-…
luxe --worktree fix-the-loop   # a branch you name

The session gets its own Git worktree under .luxe/worktrees/, on a new branch made from origin's default branch, fetched first, or from your current commit when the remote is not origin or origin/HEAD was never set. A branch you name that already exists is checked out as it is. The agent works there, so you can keep working in your own checkout and your uncommitted changes are never touched. .luxe/ keeps its own contents out of Git, so the worktree stays out of git status.

  • /worktree says where the session is working.
  • /worktree remove ends the session and removes the worktree, once everything in it is committed. The branch stays.
  • Resuming the session goes back into its worktree, and recreates it from the branch if it was removed.
  • "worktree": { "always": true } in config.json gives every new session one.

Start from an issue

luxe --issue 123

Luxe reads issue #123, makes a worktree on a branch named for it (123-short-title), and starts a session there. The issue and its latest comments go to the agent with your first message, so "fix it" is enough. They are treated as the reporter's words to weigh, not as instructions.

enter on an issue in /github does the same. If one of your sessions already took the issue up, it resumes that session instead.

Fix a pull request

luxe --pr 142        # check it out in a worktree and start a session
luxe --from-pr 142   # resume the session already working on it

A plain git push from the worktree updates the pull request, including one from a fork. A fork's branch that has to be renamed here, such as its main checked out as mara/main, gets a remote of its own (mara-push-main) for that push, so pushes from the fork's other branches are not redirected. Luxe refuses a pull request that is merged or closed, that your account cannot push to, or whose author turned off edits by maintainers.

Open a pull request

Review the work with Guided Review, finish (alt+enter), and choose Open pull request. Luxe drafts the title and description from the review, with Closes #123 when the session started from an issue.

The pull request, drafted from the review

The heading says where it merges and what happens first, such as commits and pushes first. Nothing happens until you press enter.

Key Does
t Edit the title
e Edit the description
E Edit the description in your editor ($LUXE_EDITOR, $VISUAL or $EDITOR)
d Open it as a draft
enter Open it

Afterward, o opens it in the browser, and the session remembers it for luxe --from-pr.

Browse GitHub

/github lists this repository's pull requests and issues, with the one under the cursor shown beside the list. Each tab is a GitHub search:

Tab Lists
Review requested Open pull requests waiting on your review
Mine Your open pull requests
Assigned issues Open issues assigned to you
Pull requests Every open pull request, most recently updated first
Issues Every open issue, most recently updated first

It opens on the first tab with something in it.

/github, with a pull request's overview

Key Does
tab, shift+tab Next or previous tab
/ Edit the tab's search
s Show open, closed, merged, or all
x Put the tab's own search back
→ / ← Into the detail and back
pagedown / pageup, home / end Move ten rows, or to either end
enter Review the pull request, or start a session on the issue
c Mention it in the composer
o Open it on GitHub
r Read it all again from GitHub
esc Close /github

The line above the rows shows the tab's search. Press / to edit it, then enter to run the tab again with your search. Use the same syntax as GitHub's search box: is:merged, label:bug, author:mara, sort:created-asc. While you type, plain words narrow the rows already loaded, so you can see a match before you search for it.

Editing a search in /github

A changed tab is marked with * and keeps your search until you close Luxe. x puts back the tab's own search, and so does running an empty search.

The tabs always stay in this repository. A repo:, org: or user: you type is ignored.

A tab loads 30 rows at a time and shows how many there are in all, as in 30 of 214. Moving to the last row loads the next 30.

Your own tabs

To list other searches, replace the tabs. {repo} stands for this repository. A tab without it searches all of GitHub, and so does any search you type in it:

{
  "github": {
    "sections": [
      { "name": "Needs review", "query": "is:open is:pr label:needs-review repo:{repo}" },
      { "name": "Everywhere", "query": "is:open is:pr review-requested:@me archived:false" }
    ]
  }
}

A project's .luxe/config.json can set its own sections.

Your pull request

The dock and the statusline show the current branch's pull request: #138 · 1 failing · 2 threads. /pr opens it. Its Overview lists what stands between it and merging, and each row that can be dealt with here has a key:

Key Does
f Fix with agent: write a request naming the failing checks into the composer, for you to send
x Resolve conflicts: the same, for a conflict with the base
t Resolve threads: open the unresolved review threads in Guided Review
u Update branch with its base. In a stack, opens /stack instead.
R Mark ready for review
enter on Ready Merge, after a confirmation

The merge confirmation offers the methods the repository allows (merge commit, squash, rebase), starting on the one you used last there; tab switches and d chooses whether the branch is deleted. While something still stands in the way, an Auto-merge row turns on GitHub's auto-merge instead. If anything was pushed after you looked, GitHub refuses the merge and the confirmation says so.

Answer review threads

  1. In /pr, press t. The unresolved threads open in Guided Review as comments on their lines, against your working tree.
  2. alt+u sends them to the agent. It reads them as the reviewers' words, not as instructions.
  3. Verify each fix (r in Feedback), then commit and push.
  4. alt+enter and choose Answer on GitHub. Threads you verified are resolved; c adds a reply in your own words.

Conversation

Conversation is the second tab in /pr and /github: the description, comments, reviews and threads, oldest first.

A pull request's conversation, with a drafted reply

Key Does
enter Expand or fold a comment
r Reply, in the thread or as a new comment quoting what it answers
d Have the agent draft the reply. It reads, and changes nothing.
b Hide bots

A reply is written in place. ctrl+enter keeps what you wrote, and esc while writing drops what you typed since. A kept reply waits for you: e writes in it again, E opens it in your editor, enter posts it, and esc leaves it under what it answers. Nothing reaches GitHub without that enter, and nothing in the conversation reaches the agent unless you mention it.

Stacks

When a review has two or more chapters, finishing offers Open as a stack: one pull request per chapter, each based on the one below. The lower ones get branches named <branch>-part-1, -part-2 and so on, and yours is on top. It needs the reviewed work uncommitted.

When a lower branch changes, /stack moves the ones above it back on top. It shows what will move first, makes the new commits without checking anything out (with git replay, Git 2.44 or later), and stops on a conflict before changing anything. enter force-pushes every branch that moves in one push, each only if GitHub still has what /stack read. It refuses, pushing nothing, when a moving branch here has moved, been checked out or switched, or has uncommitted changes since the preview. If the push goes through but the branches here cannot follow, it says so.

After the bottom pull request is squash-merged, keep its branch until /stack has moved the next one. Deleting it through the API, with gh pr merge --delete-branch, makes GitHub close the pull requests based on it.

How often Luxe checks GitHub

Luxe reads the pull request after anything that could change it, such as a push or /pr, and on an interval otherwise: every 15 seconds while checks run, every minute once things settle, and every five minutes when the terminal has been in the background for a while. Each read costs one point of the 5,000 an hour your gh sign-in allows.

{ "github": { "refresh_secs": 60 } }

refresh_secs sets the settled interval, and 0 turns the interval off. This one is read from your own config only, not a project's. @@@ page: guided-review

title: "Guided Review" summary: "Read a change chapter by chapter, comment for the agent, and finish with a commit, fixes or a pull request." order: 6 group: "Using Luxe"

Guided Review reads a change back to you in the order it makes sense, split into chapters. Each chapter says what changed, why, and how it was checked, beside the code. Comments you leave go to the agent as work to do.

A review: the guide on the left, the hunk being read on the right

Open a review

Press ctrl+g, or run /diff. Luxe writes the guide first; when review ready shows above the composer, press ctrl+g again to open it. Asked for while a turn is running, the review waits for the turn to end. A review you already have opens at once, and one you had open when Luxe stopped comes back with your comments.

Review Command
Uncommitted changes /diff
What the last turn changed /diff turn
Everything since a branch or commit /diff base main
One commit /diff commit 4c1e2a0
A pull request /diff pr 142, /diff pr #142, or its address

Inside a review, s changes what it covers: uncommitted changes, the last turn, a base or a commit. A pull request takes /diff pr. If the agent committed its work, so nothing is uncommitted, ctrl+g and /diff review the last turn instead. Luxe remembers what you have already reviewed in each project, so the next review leads with what is new since then.

Read it

The guide on the left opens with why the change exists and what it does, then a block per chapter with its files. The right pane shows the hunk you are on, with the guide's sentence about it. Drag the line between them to give the guide more or less room; double-click it to go back.

To Key
Next step. Past the last one, finish. space or n
Previous step shift+n
Next or previous chapter ] / [
Next or previous file ctrl+↓ / ctrl+↑
Scroll ↑ / ↓, pageup / pagedown, or half a page with ctrl+d / ctrl+u
Hide the guide, or the hunk's sentence g / z
Side by side, or one column ctrl+b
Wrap long lines w
Search /
Every key in the review ?
Back to the conversation esc. The review stays pinned until you return.

What needs you

A review lists the hunks that need your attention and accounts for the rest. A hunk covered by a test that passed says so on its own header and stays in the diff. Lockfiles, generated files, moves and formatting-only changes fold away, each run of them in a file into one row; f opens them all.

Three things are flagged and stay on the list, whatever else passed. Each flagged file says so on its row and in the walkthrough, and the guide gives the total for any kind with more than two:

  • A line that looks like a credential (sk-…, ghp_…, AKIA…, a password = "…")
  • A weakened check: a deleted test, an added #[ignore], an edit to CI or deny.toml
  • A file the agent edited without reading first

If a test fixture needs a value that looks like a credential, mark that line with // luxe:allow-secret, gitleaks:allow, pragma: allowlist secret or nosec.

To leave project bookkeeping out of every review:

{ "review": { "exclude": ["PROGRESS.md", "docs/design/**"] } }

The patterns take *, **, ? and a trailing /, and a project's list replaces your own. Excluded files are counted in the guide. Luxe's own .luxe/ is never reviewed.

A review leaves out a file it cannot hold, so the rest is still reviewable: in the last turn, any file over 1 MiB, unreadable, or not a regular file; in uncommitted changes or a base, a new file that is not ignored and is over 1 MiB or not a regular file. The top of the guide names each one, so a review that shows less than the change never passes for all of it.

Comment and ask

Key Does
c Comment on the line under the cursor. It waits for you to send it: to the agent, or to GitHub with your review of a pull request.
a Ask the agent about the line. It answers right away and changes nothing.
alt+c Feedback: every comment, with the one under the cursor in full
alt+u Send the unsent comments to the agent, from a preview where space leaves one out

In Feedback, enter goes to a comment, c replies, e edits, x deletes one not yet sent, r marks it verified, resolved or reopened, d shows its details, alt+r moves a stale one to where its line went, v shows what changed at its line, and u sends. On an answered question, c turns it into a comment, so the question, the answer and your direction reach the agent together.

You can keep commenting while the agent works on what you sent. When the agent's fix is in, the review says The fix is in · ctrl+r refresh. ctrl+r, or /diff refresh, reads the code again so you can verify it, at any time.

The agent ends a fix by reporting on each comment: fixed, not fixed, or needs clarification, with a note. The note shows under the comment, and a comment it calls fixed waits for you to verify it, since a claim is not proof. If the agent leaves its report out, Luxe asks for it once. A comment the agent still says nothing about reads no word from the agent, with the reason in Feedback, and stays where you left it.

Finish

alt+enter finishes the review:

Finishing a review

Choice Does
Accept Mark it reviewed. The agent is not told.
Accept and commit Accept, then commit each chapter as its own commit, with the chapter's explanation as the message. Never pushes.
Request fixes Send your comments for the agent to address
Comment only Send your comments without asking for edits
Keep reviewing Close this and carry on. Nothing is sent.
Open pull request Commit, push and open a pull request drafted from the review. Offered when the branch has none. See Git and GitHub.
Open as a stack One pull request per chapter. Offered with two chapters or more.
Answer on GitHub On your own pull request: reply to and resolve the threads you fixed

Accept and commit shows the commits first; s there makes them one. A review of a base or a commit can only be committed that way. It refuses if files are already staged or the code changed after the review was captured.

Review a pull request

/diff pr 142 reads a pull request into the same review: a teammate's, a bot's, or one another agent opened. It needs the GitHub CLI, gh, signed in.

Reviewing a bot's pull request, with its GitHub discussion

  • It is pinned to the commit GitHub reported and compared from where it branched, as GitHub's Files changed does. Nothing in your checkout moves.
  • The head says who opened it and where it stands: by dependabot (bot) · 1 failing · changes requested.
  • The author's description follows the guide, under its own heading.
  • Review threads appear under the lines they are about. Anything without a line is under Discussion on GitHub.
  • a asks the agent about a line, at the pull request's commit.
  • ctrl+r reads it again after a new push.

Post your review

alt+enter on a pull request shows exactly what will be posted before anything is:

Key Does
tab / shift+tab Choose Comment, Approve or Request changes
c Write the summary. Request changes needs one.
d Have the agent draft the summary from this review
e Edit the summary
enter Post it

Line comments are listed under their files with the diff they sit on, the way GitHub shows them. Questions you asked the agent stay in Luxe and are never posted. On your own pull request, GitHub only takes a comment, so that is all Luxe offers.

A drafted summary opens in the preview for you to read and edit. Anything the agent says beside it, such as a part of the change it did not read, appears under it as a note. Once the review is posted, the guide's foot says Posted to GitHub with the verdict, and o opens it.

Fix it yourself

To change someone else's pull request rather than comment on it, press alt+u (or w in the post preview). Luxe asks GitHub whether you can push to it, then checks it out in a worktree of its own and starts a session there, with your comments as the agent's first task. A plain git push then updates the pull request. @@@ page: hooks

title: "Hooks" summary: "Run your own commands at points in a turn: block, rewrite or audit tool calls, and add context." order: 5 group: "Extend"

A hook runs a command of yours at a point in a turn, such as before each tool call. It receives the event as JSON on stdin and can answer with a decision as JSON on stdout. Any executable works: a shell script, Python, a compiled program.

Add a hook

Hooks go in ~/.config/luxe/hooks.json. This one asks before any recursive delete and refuses a wipe of / or your home folder:

{
  "BeforeToolUse": [
    {
      "matcher": { "bash": "rm *" },
      "command": ["/home/you/.config/luxe/hooks/guard.sh"],
      "on_timeout": "deny"
    }
  ]
}
#!/usr/bin/env bash
cmd=$(jq -r '.ToolUse.args.command // empty')
case "$cmd" in
  *"rm -rf /"*|*"rm -rf ~"*) echo '{"decision":"deny","reason":"refusing a root or home wipe"}' ;;
  *)                         echo '{"decision":"ask","reason":"recursive delete"}' ;;
esac

A project's .luxe/hooks.json runs only when you start Luxe with --trust-project, since opening a repository should never run its commands. When both are loaded, a project's hooks run after yours.

Hook settings

Key Default Does
command The program and its arguments, run without a shell. Use ["sh", "-c", "…"] for shell features.
matcher every call Which tool calls it runs for; see Matchers
timeout_ms 5000 One deadline for sending the event, reading output and waiting for exit. On timeout, it and everything it started are stopped.
on_timeout allow What happens if the hook times out, fails to start, exits non-zero or prints something that is not a decision: allow, deny or ask

on_timeout: "deny" makes a guard fail closed. "ask" puts the question to you instead, at BeforeToolUse; at other points it acts as allow. A decision Luxe does not recognize, a typo or different casing included, gets the same treatment, with a warning in the log, and its args and context are dropped.

Matchers

A BeforeToolUse hook without a matcher runs on every tool call, and each run starts a process. A matcher skips the calls you do not care about, without starting anything:

"matcher": "bash"                                   a tool name, or a pattern like "web_*"
"matcher": { "bash": "rm *", "edit": "src/**" }     a tool and what the call is about

The second form matches if any entry does. The patterns are the same as in permissions.json: "rm *" finds the rm in cd /tmp && rm -rf x, and a pattern for read or edit matches the path, for web_fetch the address.

Only BeforeToolUse sees a call's arguments. At AfterToolUse only the tool name is matched, and points without a tool call ignore the matcher.

Hook points

Point Runs stdin Can
SessionStart A session starts or resumes, including a switch to it from another session {"Other": null}
SessionEnd A session ends, including a switch to another session; Luxe waits for the hook {"Other": null}
UserPromptSubmit You send a message, including one sent while the agent works {"Other": {"content": "…"}} block it, add context
BeforeAgentStart A turn is about to start {"Other": null}
AgentStart Luxe is about to call the model {"Other": null}
BeforeToolUse Before each tool call {"ToolUse": {"tool_name": "bash", "args": {…}}} block it, ask you, rewrite it
AfterToolUse After each tool call {"ToolResult": {"tool_name": "bash", "result": "…", "is_error": false}} add context to the result
FileChanged write, edit, an applied rename or code action, or an ast_grep rewrite changed a file {"FileChanged": {"path": "/abs/file", "operation": "edit"}}
BeforeCompact, AfterCompact Around compaction {"Other": {"tokens_before": 12345}}
AgentEnd A turn finished {"Other": {"effective_context_percent": 12.5}}
Error A turn failed {"Other": {"message": "…"}}
PermissionRequested, PermissionResolved An approval prompt opens or is answered {"Other": {"tool": "bash", "phase": "requested", …}}
ReviewGate, LoopControl luxe loop only

A hook at a point with nothing under Can still runs, for logging or notifications, but its answer is ignored. Point names are matched loosely (before_tool_use works). An unknown name skips that hook alone, with a warning naming the nearest real point.

Answer with a decision

{ "decision": "deny", "reason": "rm -rf is blocked by policy" }
Field Where Does
decision Required in any answer deny blocks the call or message. ask raises a permission prompt, at BeforeToolUse. allow, or no output at all, means no opinion. An answer without decision counts as one Luxe cannot read.
reason with deny or ask Shown to the model when a call is blocked, to you when a message is blocked, and on the prompt
args BeforeToolUse New values for the call's arguments. Keys you leave out keep their values.
context AfterToolUse, UserPromptSubmit Text added to the tool result, or saved with your message, for the model to see
{ "decision": "allow", "args": { "command": "bun test" } }

When several hooks answer the same point, their context and rewrites are combined in order. A deny ends it: hooks after it do not run.

What a hook cannot do

  • Approve a call. allow means no opinion; a hook can only make a call harder. To auto-approve, write a rule in permissions.json.
  • Rewrite its way past the rules. A rewritten call is checked by the permission rules as rewritten, and that is what runs. If a rewritten call matches an ask rule, you are asked about the new command.

When nobody is there to answer

In a headless or loop run, a hook's ask is allowed, like every other ask. To change that:

  • --on-ask deny, or "agent": { "on_ask": "deny" } in config.json, refuses every ask in an unattended run, and tells the model why.
  • { "permission": { "hook_ask": "deny" } } in permissions.json turns every hook's ask into a block everywhere, even when you are there. "allow" silences them instead.

A hook's prompt offers Allow once and Reject, since a hook decides each call afresh.

What a hook sees

The event a hook receives is not redacted: it is a program you installed, with the same access you have, and the call's arguments have already gone to your model provider. What a hook returns, its reason and context, is scrubbed of anything that looks like a secret before it is shown or saved. Read a hook script before installing it, as you would anything on your PATH.

Examples

Add lint output to every edit:

{
  "AfterToolUse": [
    {
      "matcher": "edit",
      "command": ["sh", "-c", "jq -n --arg out \"$(npm run -s lint 2>&1 | tail -20)\" '{decision: \"allow\", context: $out}'"]
    }
  ]
}

Luxe already adds language server errors after every edit; a hook like this is for a different check.

Refuse messages that contain an internal token:

#!/usr/bin/env bash
prompt=$(jq -r '.Other.content // empty')
if printf '%s' "$prompt" | grep -qE 'CORP-SECRET-[0-9]+'; then
  echo '{"decision":"deny","reason":"the message contained an internal token"}'
fi

Copy the sessions before compaction:

{ "BeforeCompact": [{ "command": ["sh", "-c", "cp -r .luxe/sessions /tmp/luxe-precompact-$$"] }] }

Recipes has a hook that asks a classifier model whether a command is destructive.

Coming from Claude Code

Claude Code Luxe
PreToolUse, PostToolUse BeforeToolUse, AfterToolUse
UserPromptSubmit with additionalContext UserPromptSubmit with context
SessionStart, SessionEnd the same
PreCompact, PostCompact BeforeCompact, AfterCompact
Stop AgentEnd, which observes only
permissionDecision: "ask" "decision": "ask"
updatedInput args, checked again by the permission rules
matcher and if matcher, in either form
permissionDecision: "allow", which skips the prompt No equivalent: use permissions.json
@@@ page: index

title: "Overview" summary: "What Luxe is, and where to find what you need." order: 0 group: "Get started"

Luxe is a coding agent for your terminal. It works in your project with the model you choose, then walks you through what it changed so you can review it and open a pull request without leaving the terminal.

New to Luxe? Install it, then follow the Quickstart. The rest of the guide is reference, for when you need it.

Find what you need

To Read
Connect a model, or switch between them Models and providers
Find your way around the screen The interface
Find a command or a key, or rebind one Commands and keys
Point the agent at a file, issue or skill Mentions
Review what the agent changed Guided Review
Work from an issue, open or merge a pull request Git and GitHub
Resume a session, or see what fills the context Sessions and context
See what the agent can use Tools
Let the agent work through a plan on its own Autonomous runs
Change the theme, keys or statusline Configuration
Give the agent your project's conventions Project context
Add tools, skills or your own commands Extending Luxe, Recipes
Control what the agent may do Security and permissions
Look up a command, flag or environment variable Command line, Environment variables
Fix something that is not working Troubleshooting

Help

  • Help (/help) lists every key for the screen you are on, with any you have rebound.
  • luxe doctor checks which language servers, debuggers and tools Luxe can use on your machine.
  • Troubleshooting covers common problems and how to report a bug.
  • Problems and questions: GitHub issues.

Ask Luxe

This guide is built into Luxe, for the version you have installed. Ask the agent how to do something in Luxe, such as how do I add an MCP server?, and it reads the answer from the guide rather than guessing. You can read it yourself too:

luxe docs                  # every page
luxe docs hooks            # one page
luxe docs --search "on_ask"

For agents

Every page is also plain markdown, at the same address with .md on the end: https://luxe.dev/docs/install.md. llms.txt lists every page with a one-line summary, and llms-full.txt is the whole guide in one file. Inside Luxe, luxe docs serves the same pages offline. @@@ page: install

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:

curl -fsSL https://luxe.dev/install.sh | sh

That address redirects to the script on the latest release, the one it built and attested. To read it before running it, drop the | sh.

With Homebrew, on macOS or Linux:

brew install evanwhittaker/tap/luxe

With Cargo, which builds it, so you need Rust 1.89 or newer (rustup installs one):

cargo install --locked luxe-cli

On Windows, in PowerShell:

powershell -c "irm https://luxe.dev/install.ps1 | iex"

That script 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 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:

gh attestation verify luxe-cli-x86_64-unknown-linux-gnu.tar.xz --repo evanwhittaker/luxe

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.

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.
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.

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

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/. @@@ page: interface

title: "The interface" summary: "The start screen, the conversation, the composer, the dock, the statusline and the preview." order: 3 group: "Using Luxe"

The dock beside the preview, showing one file's diff

This page names the keys for each part of the screen. All of them, and how to rebind them, are in Commands and keys; /help lists the ones for the screen you are on, and the Command Palette (ctrl+k) finds any command by name. Which editor and file manager open is in Environment variables.

The start screen

Luxe opens on a prompt. Type and press enter to ask in a new session, or choose a row from the list under it with ↑/↓ and enter.

Row Opens
Set up a provider Configuration. Leads the list, and takes enter on an empty prompt, until a provider is set up.
Resume Your last session, named with its title and how long ago. Once a provider is set up, enter alone opens it.
New session A fresh conversation
Sessions… Every session in this project, searchable. /sessions opens it too, here or in a session.
Review changes A Guided Review of your uncommitted changes, when there are any
Configuration Providers, credentials, settings and config files, once a provider is set up
Quit Leaves Luxe. ctrl+c does too, here and in a session, even mid-turn, unless a prompt or menu is open, which it answers instead.
RECENT Your other recent sessions

Typing narrows the list. The first row becomes Ask in a new session, and under it come the sessions whose titles match, the commands that do, and a search through every session's transcript. A session you open this way keeps what you typed in its composer. Once a draft reads as a prompt (more than five words or 48 characters, a second line, a pasted chip or a mention), the list folds away and enter asks.

/ and @ open the same command and mention pickers a session has, under the prompt. A command chosen there either opens over the start screen, as /model and /theme do, or starts a new session to run in.

The start screen with a search typed

Every key is text here, so esc clears the prompt rather than quitting. shift+tab, or a click on the prompt's title, switches between build and plan mode before you start, and the session opens in the mode you chose. The statusline under it is the one the session will have.

Nothing picks a model for you. Until you choose one, sending a message opens the model picker with your message kept.

Styles

{ "dashboard": { "style": "minimal" } }

minimal shows the prompt alone, and the list waits for ↓. "dashboard": false skips the start screen and opens a new session. Start screen in /settings sets the same key.

The minimal start screen

Luxe works on the project it was started in. To switch projects, cd there and run luxe.

The conversation

Each tool call the agent makes is a card, showing what it did and how long it took. ctrl+o shows every card's full output, and clicking a card opens it.

A finished turn: three reads folded into one card, an edit with its diff, a test run and the reply

A shell command card is titled by what the agent says the command is for, such as "Run the forms tests", with the first line of the command under it and the rest a click away. A test run through the shell that fails shows its counts and what failed, the same as the test tool's card.

Three or more lookups from one message (read, grep, glob, ast_grep and the code intelligence tools) fold into one card that lists what they looked at: the first five by name, or four and a count of the rest. So do three or more calls in a row to one MCP server, with nothing shown between them. Click a folded card to open it into one card per call, and click again to fold it. Edits, commands, git, the todo list and anything that failed always keep their own card. "conversation": { "tool_runs": "cards" } turns folding off.

Tables in a reply fit the width they are drawn at. Narrower than the table, cells wrap inside their columns; too narrow for that, each row is listed as Header: value lines.

Code blocks in a reply are highlighted for their language. Click the rule above a block to copy it.

To Key
Scroll wheel, ctrl+↑ / ctrl+↓, pageup / pagedown
Jump to the newest output ctrl+end
Search the conversation ctrl+f
Select the previous or next message alt+k / alt+j
Copy the selected message alt+y
Edit your last message and send it again alt+e
Ask again, after the last answer alt+t
Replace the last answer alt+g
View the newest image full-window alt+i

The composer

enter sends. shift+enter adds a line. Type / for commands and @ to mention a file, skill, issue or other context.

The composer's title names the session's mode, build or plan. shift+tab or a click on the title switches it; see Plan, then build.

While the agent works, you can keep typing:

Key Does
enter Steer: the message reaches the running turn between steps, without stopping it
alt+enter or alt+q Queue: the message becomes the next turn, after this one ends
alt+↑ Bring waiting messages back into the composer to edit
ctrl+esc Stop the turn. Waiting messages come back into the composer.

A waiting message sits above the composer, marked steering or queued, until it is delivered.

ctrl+v or shift+insert pastes. Pasted text of three lines or more, or over 150 bytes, becomes a [Pasted 40 lines] chip, and a pasted image becomes [Pasted Image]. Both are sent in full. A chip, like a mention, is deleted with one backspace.

The composer and every other text field take the usual line-editing keys:

To Key
Move by word ctrl+← / ctrl+→, or alt+← / alt+→
Start or end of line home / end, or ctrl+a / ctrl+e
Delete the word before or after alt+backspace / alt+delete
Delete to the start of the line ctrl+u
Select shift with any move, or alt+a for everything

On macOS, Option and Cmd with the arrows and backspace do the same in Ghostty, and in other terminals with their natural text editing preset.

The dock

The Context Dock is the column beside the conversation. It sits beside it on terminals 136 columns or wider. On narrower ones it is hidden until you press alt+d, and then opens over the conversation, or in its place below 80 columns.

Section Shows
PROJECT The project, its branch, and the branch's pull request: #138 · 1 failing · 2 threads
PLAN The agent's todo list, scrolled to what it is working on
FILES The project as a tree, with what changed marked in it. Click a file to preview it.
ELSEWHERE Files the session changed outside the project, when there are any
MODEL The provider, model, thinking level and mode. Click the model to change it, or the mode to switch it.
SESSION Context used, tokens and cost, with what a review and compaction cost on rows of their own. A review's row shows its full cost once its guide or drafted summary is done.

alt+d shows or hides the dock, and /dock left or /dock right moves it. To set it for good:

{
  "dock": { "mode": "auto", "position": "left" }
}

mode is auto (beside the conversation when there is room), shown or hidden.

Drag the line between the dock and the conversation to make the dock wider or narrower. It stays that width the next time Luxe starts; double-click the line to put it back.

Files

FILES is the project's tree. Dotfiles such as .github are in it; what .gitignore ignores is not, until you ask for it. Folders on the way to a changed file open on their own, so the change is in view; a changed file shows its letter (M, A, D, ?) and its line counts, and a closed folder with a change inside shows a dot. A folder holding only one folder is drawn as one row, crates/luxe-core/src. all ▾ on the heading opens a menu: show only what changed, or show the ignored files too, drawn faint.

Click a folder to open or close it, and a file to preview it; the file showing is drawn in the accent color. Right-click either for everything you can do with it.

The tree only reads. To move, rename or delete files, ask the agent, which goes through your permissions and shows up in the review, or press O to open the folder in your file manager. A terminal one such as yazi takes the screen until you quit it, as your editor does; the tree reads its folders again when you come back.

ctrl+t moves the keyboard into the tree, and pressed again, into the file showing beside it. tab trades the keyboard between the two, and esc hands it back to the composer.

In the tree Key
Move j / k, or the arrows
Find a file by typing part of its path /
Open a folder, or show a file enter
Open a folder, or show a file and move into it l
Close a folder, or go to its parent h
Open in your editor o
Open its folder in a file manager O
Mention it in the composer @
Copy its path y
Only what changed, or everything a
Show the ignored files, or hide them i
Read the folders again R
Back to the composer esc

Any other key goes to the composer, so you can start typing without leaving the tree first.

/ filters the tree as you type. It searches the whole project, not just the open folders, and matches the letters in order anywhere in the path, so tuiview finds crates/luxe-tui/src/view.rs. The tree shows the best matches under the folders that hold them, with the matched letters lit. The arrows move through them, and enter shows one. esc clears the filter and leaves the cursor on the file you found. Files .gitignore ignores are never matched, even while the tree is showing them.

The statusline

The statusline is the bar under the composer. It carries the same model, context and cost the dock does, so by default it shows only when the dock is not beside the conversation. That makes alt+d a swap on a wide terminal: hiding the dock brings the statusline back, and showing it puts the statusline away. alt+s or /statusline show, hide or auto changes that, and "statusline": { "visibility": "shown" } keeps it. Statusline modules sets what it shows.

Preview

The preview (ctrl+p) shows one file in place of the conversation, with the dock and the composer where they were, so you can reply about what you see. A changed file opens on its diff, and alt+m, or FILE in the header, shows it whole; DIFF goes back. Any other file opens whole. Click another file under FILES to switch; click the open one, or press esc, to go back. /preview src/app.rs opens a given file.

To ask about part of a file, drag across its lines (or click one) and choose ask about lines under them, or press alt+l. The composer gets @[file:src/app.rs:40-52]: the agent receives the path and the lines, and reads them itself. Right-click the lines to copy them instead.

On a wide terminal the conversation stays beside the diff. The diff takes the width code needs, about 134 columns in one column or 218 side by side, and the conversation gets the rest. Drag the line between them to change the split, and double-click it to go back.

The preview is not a review: looking at a file does not count it as reviewed.

In the preview Key
Next or previous changed file alt+n / alt+p
The whole file, or its diff alt+m
Ask about the lines you picked alt+l
Side by side, or one column ctrl+b
Wrap long lines, or not alt+w
Open the file in your editor, at the top line shown alt+o
Open a Guided Review of your changes, at this file ctrl+g
Back to the conversation esc

With the keyboard in the file (ctrl+t twice, or tab from the tree), a cursor moves line by line and the file scrolls to keep it in view. In a diff the same keys scroll.

In the file Key
Move the cursor j / k, or the arrows; space / pageup a page, ctrl+d / ctrl+u half of one; g / G the ends
Select lines, like vim's visual-line mode: moves grow the pick, o moves its other end v or V
Grow a pick by one line without the mode J / K, or shift with the arrows
Ask about the pick, or the cursor's line enter
Copy the pick, or the cursor's line y
Open in your editor at the cursor o
Back to the tree tab or h
Drop the pick or leave visual mode, then back to the composer esc

Mouse and clipboard

The wheel scrolls whatever is under the pointer, and a click acts on what you click. Drag any scrollbar to scroll, or press anywhere on it to jump.

The lines between panes move: the dock's, the preview's, and the one beside a review's guide. A line lights under the pointer; drag it to resize the pane beside it, or double-click it to put the pane back to its own width. Luxe remembers the widths for next time.

Drag across the conversation or the composer to select, and the selection is copied when you let go. Click a message to copy all of it. ctrl+insert or ctrl+shift+c copies a selection too.

Your terminal's own copy key reaches Luxe only if the terminal passes it through. Either hold shift (option on macOS) while dragging, to make a selection the terminal copies itself, or let the copy key fall through when the terminal has nothing selected. In Ghostty:

keybind = performable:control+insert=copy_to_clipboard

Luxe copies to the desktop clipboard, and over SSH through the terminal (OSC 52). Inside tmux, that needs set -g set-clipboard on.

/mouse off hands the mouse back to the terminal for the session, and "mouse": false in config.json starts with it off. "conversation": { "scroll_lines": 5 } sets how far a wheel notch scrolls, from 1 to 20 lines (3 by default). @@@ page: loop

title: "Autonomous runs" summary: "Let the agent work through a phased plan on its own, with tests and a reviewer at each phase." order: 12 group: "Using Luxe"

luxe loop runs the agent on its own, phase by phase through your plan. A phase only counts as done once your tests pass and, if you set one up, a reviewer agrees.

Write the plan

Put the plan in PLAN.md at the project root, one heading per phase. Plan mode writes it in this shape for you, and when it is done, Run it as a loop switches the session to build and tells you to run luxe loop start.

Plan mode's plan written, asking what next: build here, in a fresh session, or run it as a loop

# Word counts

## Phase 0 — Count words
Read a file and print its word count. Tests for an empty file and one line.

## Phase 1 — Count by line
...

The agent is given one phase at a time, and the reviewer judges it against the same section. A plan without phase headings is worked on as a whole.

Start a run

luxe loop start
Command Does
luxe loop start Start a run in a new session, at the phase the last one reached
luxe loop status Iteration, phase, whether it is running, and what it has cost
luxe loop pause, luxe loop resume Pause, and clear a pause so start continues
luxe loop stop Stop the run
luxe loop phase Show the phase. --set <n> changes it.
luxe loop fresh Reset the turn count, so the next start gets all of --max-turns again
Flag Default Does
--max-turns 50 Most turns before the run stops. The count carries over when you start again; luxe loop fresh resets it.
--compact-percent the compaction.at you set, else 75 How full the usable context window gets before the session is summarized; see Compaction
--pause-percent 90 How full it gets before the run stops. Keep it above --compact-percent, and run luxe loop start to go on.
--quiet Print only the banner

A run uses your session's model, or --model. Only one run at a time works in a project.

Check each phase

When the agent says a phase is done, Luxe checks it before moving on:

  1. Your commands. Each must pass.
  2. A reviewer, if gate.review is on and the commands passed. It runs in a fresh session, so it judges the phase without the reasoning that produced it. It reads the phase's section of the plan, the diff and the command output, and can look around the code with read-only tools. It cannot edit.
{
  "gate": {
    "commands": [
      ["cargo", "nextest", "run", "--workspace"],
      ["cargo", "clippy", "--workspace", "--all-targets", "--", "-D", "warnings"]
    ],
    "timeout_secs": 600,
    "review": true
  }
}

The reviewer runs on the run's own model unless reviewer.model names another, which turns gate.review on by itself. A local model building and a hosted one reviewing is a common pairing: the review is a few calls per phase, the building is most of them. See A second opinion.

Each command is a program and its arguments, run without a shell. For shell features, use ["sh", "-c", "…"]. A project's commands replace your global ones only when you start with --trust-project. Otherwise they're ignored with a warning, and your global commands apply.

If a check fails, the findings go back to the agent as work and the phase does not advance. With neither check set up, the agent's word is taken. The same checks apply before the run may finish.

A review is limited to 24 tool calls and 10 minutes. A phase only advances when the reviewer approves it. If the reviewer cannot answer, has nothing to read, or refuses the same phase three times, the loop pauses for you: fix what it needs and run luxe loop start again, or accept the phase with luxe loop phase --set <next>.

Watch a run

A run prints one line per step, timed from its start:

      19s    write logstats.py
      49s    test python3 -m unittest -q
    1m09s  phase 0 claimed complete — running the gate
    1m31s  the acceptance commands passed — asking the reviewer
    2m34s  phase 0 accepted — now on phase 1

luxe loop status shows what it has cost, by model:

  Spend this run:
    claude-sonnet-5: 3 calls, 26295 tokens
    qwen3.6-27b: 19 calls, 188660 tokens

The conversation is in .luxe/sessions/, the log in .luxe/logs/luxe.log, and the journal the agent keeps in .luxe/loop/PROGRESS.md. Past 24 KB, the journal's older ## sections move to PROGRESS.archive.md beside it, and a line pointing there takes their place. The newest section stays, unless it is the only one.

When a tool asks permission

Nobody is there to answer, so a tool call that would ask you is allowed by default. To refuse those calls instead, and tell the agent to find another way:

{ "agent": { "on_ask": "deny" } }

--on-ask deny does the same for one run. A project can set deny but not allow. Calls your permission rules deny are refused either way. See Security. @@@ page: mcp

title: "MCP servers" summary: "Give the agent tools from MCP servers: add one, sign in, and control what it may do." order: 3 group: "Extend"

An MCP server gives the agent new tools: a browser, a database, your issue tracker. Luxe reaches every server through one mcp tool, so a server's tools cost nothing in a request until the agent looks for them:

mcp({ search: "screenshot" })                                    find tools by keyword or server
mcp({ tool: "chrome/take_screenshot" })                          one tool's parameters
mcp({ tool: "chrome/take_screenshot", args: "{\"format\":\"png\"}" })   call it

Add a server

Add servers to ~/.config/luxe/mcp.json. The mcpServers format other tools write works as it is:

{
  "mcpServers": {
    "chrome": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
    "linear": { "url": "https://mcp.linear.app/mcp", "auth": { "kind": "oauth" } }
  }
}

A server is a local program (command and args) or a remote address (url). Or from the command line:

luxe mcp add --id chrome --name "Chrome" --command "npx -y chrome-devtools-mcp@latest"
luxe mcp list     # configured servers
luxe mcp tools    # every server's tools
luxe mcp remove --id chrome

luxe mcp add and luxe mcp remove change only the project's .luxe/mcp.json, so a server added this way is a project's server, and one in your own mcp.json is removed by editing that file. luxe mcp list starts nothing: it shows every configured server, disabled ones included, and marks a project's entries not started (project), with or without --trust-project. In a session, /mcp shows each server, how it connects and its tools.

Luxe also reads ~/.config/mcp/mcp.json, and a project's .mcp.json and .luxe/mcp.json. Where two files name the same server, the project's wins.

Server settings

Key Does
command, args, env Start a local server. An env value can use ${VAR} or $env:VAR; an unset one is empty, and Luxe logs which.
url, headers Connect to a remote server. headers take ${VAR} the same way.
auth Sign in: see below
lifecycle lazy (the default) connects on first use and disconnects when idle. eager connects at start; keep_alive stays connected.
timeout_secs How long one call may take. 60 by default. A call that runs over stops the server; the next call starts it again.
exclude_tools Tool names to hide from the agent
enabled false turns a server off without removing it

Sign in

A remote server signs in with a token or with OAuth.

{
  "mcpServers": {
    "internal": {
      "url": "https://mcp.example.com/mcp",
      "auth": { "kind": "bearer", "token_env": "INTERNAL_MCP_TOKEN" }
    },
    "linear": { "url": "https://mcp.linear.app/mcp", "auth": { "kind": "oauth" } }
  }
}

For OAuth, sign in once in a browser, and Luxe refreshes the token from then on:

luxe mcp login --id linear

The agent never starts a sign-in. Tokens are kept in ~/.local/state/luxe/mcp-auth.json, readable only by you. With LUXE_STATE_DIR set they are kept there instead, so a moved state directory does not share the default one's sign-ins. If that file stops being valid JSON, Luxe moves it to mcp-auth.json.bad (or a dated name, if one is already there) rather than write over it, and you sign in again.

A token only travels over https. A server with auth set whose url is plain http is refused unless it is on this machine, and so is an OAuth endpoint, whether you wrote it or the server described it. The server's metadata must also name itself as the issuer it was asked for.

Some providers, such as Asana, register each app and give you a client ID and secret. Add them, with the redirect address you registered:

{
  "mcpServers": {
    "asana": {
      "url": "https://mcp.asana.com/v2/mcp",
      "auth": {
        "kind": "oauth",
        "client_id": "1209…",
        "client_secret": "${ASANA_MCP_CLIENT_SECRET}",
        "redirect_uri": "http://127.0.0.1:8765/callback"
      }
    }
  }
}

The redirect must be on 127.0.0.1, localhost or [::1], with the port you registered. A secret or token can be written three ways:

  • ${VAR}: an environment variable. Programs the agent runs can read it too. If it is unset, sign-in stops and names the variable.
  • !command: a command that prints it, such as "!pass show asana/mcp-secret". It runs at sign-in and on each refresh, without a terminal, for up to 30 seconds. Only your own config can use this.
  • The value itself, in a file only you can read (chmod 600).

Never put a secret in a project's .mcp.json or .luxe/mcp.json, which are shared with the repository. Asana, end to end walks through the whole setup.

Point the agent at a server

In the @ picker, the MCP tab lists each server with its state: 22 tools · signed in, or not signed in — luxe mcp login --id linear. Mentioning one, as in @[mcp:asana] what is due this week?, sends the agent straight to it, with the names of its tools the first time.

Control what a server may do

A tool call is checked by your permission rules, by its server/tool name:

{
  "permission": {
    "mcp": {
      "asana/get_*": "allow",
      "asana/create_*": "ask",
      "asana/delete_*": "deny"
    }
  }
}

The most specific rule wins. deny holds everywhere, even with --yolo. ask holds only when someone is there to answer; in a headless or loop run it is allowed, unless agent.on_ask is deny.

What a tool returns goes to your model provider, as the result of that call. Signing in and luxe mcp tools send nothing to a model. If a server's data should only go to a provider your organization approves, deny its tools until you are on one.

A server's descriptions and results are treated as information, never as instructions.

Servers a project brings

A project's .mcp.json names programs that would run on your machine. Luxe starts a project's servers in an interactive session, or with --trust-project, but not in a headless or loop run. To decide for every run, set lsp.project_servers in your own config; see Tools.

luxe mcp tools and luxe mcp login do not ask whether to trust a project's servers. They skip project servers unless you pass --trust-project or set lsp.project_servers to always in your own config, and print the skipped server ids and how to allow them. Login refuses a skipped server before contacting its OAuth endpoints. Your global never setting still wins over the flag. Servers in your own config do not need project trust. @@@ page: mention-sources

title: "Mention sources" summary: "Add your own tab to the @ picker: Jira issues, Asana tasks, anything a program can list." order: 4 group: "Extend"

A mention source adds a tab to the @ picker, filled by a program of yours. Pick a row, and the agent receives the text your program gave for it.

Add a source

{
  "mentions": [
    { "name": "Jira", "command": "jira-mentions", "icon": "\udb80\udf03" },
    { "name": "Asana", "kind": "task", "command": "asana-mentions", "args": ["--mine"] }
  ]
}
Key Does
name The tab's name
command, args The program to run, found on PATH or given as a full path, and its arguments
kind The mention's prefix, as in @[task:1209…]. By default the name in lowercase, with anything but letters and digits as -: Jira Cloud is jira-cloud.
icon One Nerd Font glyph for the tab, as the character or a JSON escape. Without one, the tab shows a tag; without a Nerd Font, a plain mark.

Sources are read from your own config only, since each one runs a program. Their tabs come after Luxe's own: Files, Skills, GitHub and MCP, whose kinds file, skill, github and mcp are taken. Two sources with the same kind get one tab, the first's.

What the program prints

Luxe runs the program, in the project, the first time its tab opens, and lists what it prints: one JSON object per line. The rows are kept until Luxe exits, so a new ticket, or a change to your script, shows up the next time you start Luxe. The program has no terminal and no stdin, so it cannot prompt for a sign-in.

{"id": "PROJ-12", "label": "PROJ-12 Login fails on Safari", "detail": "In progress", "text": "Jira issue PROJ-12 \"Login fails on Safari\" (In progress) https://acme.atlassian.net/browse/PROJ-12"}
Field Is
id Required, a string or a number, without ]. Goes in the mention: @[jira:PROJ-12].
label Required. The row in the picker, up to 200 characters.
detail Shown beside the label, up to 200 characters
text What the agent receives, up to 600 characters. The label when missing.

A program has 15 seconds and up to 500 rows. A line that is not JSON, is over 8 KB, or lacks an id or label is skipped without a word, so a tab that stays empty usually means the output is wrong. If the program fails, the tab shows the last line it wrote to stderr, or its exit status, and it runs again the next time the tab opens.

Make text enough for the agent to find the rest: a title and a link, or an ID it can look up with a CLI or an MCP server. A mention you type by hand, or one not picked since Luxe started, reaches the agent as Jira PROJ-12 alone. What a tracker says is other people's words, and it reaches your model provider once you mention it.

Example: your open Jira issues

#!/bin/sh
site=https://acme.atlassian.net
curl -sSf -u "$JIRA_USER:$JIRA_TOKEN" -G "$site/rest/api/3/search/jql" \
  --data-urlencode 'jql=assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC' \
  --data-urlencode 'fields=summary,status' |
jq -c --arg site "$site" '.issues[] | {
  id: .key,
  label: "\(.key) \(.fields.summary)",
  detail: .fields.status.name,
  text: "Jira issue \(.key) \"\(.fields.summary)\" (\(.fields.status.name)) \($site)/browse/\(.key)"
}'

Make it executable (chmod +x), put it on your PATH, and add the Jira entry above. For Asana, see Recipes. Or ask Luxe to write one for the tracker you use. @@@ page: mentions

title: "Mentions" summary: "Point the agent at a file, skill, issue, MCP server or your own tracker with @." order: 5 group: "Using Luxe"

Type @ at the start of a word in the composer to mention something. The picker opens on your project's files; tab and shift+tab move between its tabs, typing filters, ↑/↓ move, enter inserts the mention, and esc or a space closes it.

The @ picker on its Files tab, changed files first

Tab Lists
Files Changed files first, then the rest of the project, 50 rows at most; type to narrow them. Respects .gitignore, and never lists .git, target, node_modules or .cache.
Skills The skills you have installed
GitHub The pull requests and issues /github lists, through gh
MCP The MCP servers this session can use, when there are any
Your own Any mention source you add: Jira, Asana, a runbook index

Dotfiles and files under dot-folders, such as .gitignore and .github/, are left off the first list but show up when you type. Start with . to rank them with everything else.

The file list is read from disk each time the picker opens, every few seconds while the Files tab shows, and when the agent changes files, so a file made or moved a moment ago is there. ctrl+r reads it again on the spot.

What the agent receives

A mention is a pointer, not a copy. Nothing is pasted into your message:

Mention The agent gets
@[file:docs/plan.md] The path, to read when it needs to
@[skill:gh-stack] The skill's name, to load with the skill tool
@[file:src/app.rs:40-52] The path and those lines, from ask about lines in the preview
@[github:acme/todo/issues/42] Its number, title, state and address, and the git tool call that reads it in full
@[mcp:asana] The server to use, with the names of its tools the first time it is signed in and listing them
@[jira:PROJ-12] The text your mention source gave for that row

A mention typed by hand works too. The title and state of an issue, and a mention source's text, come from a row you picked this session; for one you typed, the agent gets the address or Jira PROJ-12 and looks it up itself. A file or skill that does not exist is reported as missing.

So a large file never floods the conversation, and a file the agent then edits is never in it twice in two versions. Review @[file:docs/plan.md] and draft a plan is enough: the agent opens the file itself.

In the composer, a mention is one chip. The cursor steps over it, and one backspace deletes it. In /github, c inserts a mention of the pull request or issue under the cursor. @@@ page: project-context

title: "Project context" summary: "Give the agent your project's conventions in AGENTS.md, and how Luxe finds the project." order: 3 group: "Customize"

AGENTS.md

Put your project's conventions in an AGENTS.md at its root, and the agent reads it at the start of every session. In a project folder a CLAUDE.md works too; when both exist, AGENTS.md is used. The global files below are read only by those names, so ~/.claude/CLAUDE.md is not.

Luxe reads, in order:

  1. ~/.agents/AGENTS.md, the file many people keep for every agent they use
  2. ~/.config/luxe/agents.md, for every project in Luxe
  3. AGENTS.md at the top of the repository
  4. One AGENTS.md per folder down to where you started Luxe

So a monorepo can keep shared rules at the root and package rules beside the code, and luxe started in packages/app reads both. Nothing above the repository is read. Outside a repository, only the folder you started in is, so an AGENTS.md in a parent folder never reaches a project it was not written for.

The files are read once, when a session sends its first message, and every later request in the session repeats that same text, which is what lets the provider reuse its cache. An edit reaches the agent in the next session: /new, or resuming one. If you switch Git branches mid-session, the agent is told with your next message.

Project context lists every file a turn reads, and says whose rules each one carries: global, project or folder context. Type context on the start screen and open it. enter opens a file in your editor, or creates one from a template. The template's guidance is in comments, which Luxe removes and reports, so replace them with your own lines.

Duplicates

A file the walk reaches twice is read once. That covers a symbolic link, such as ~/.config/luxe/agents.md pointing at ~/.agents/AGENTS.md, and a file that is a byte-for-byte copy of an earlier one. The context list shows the copy as read once.

Two files that say mostly the same thing are both read, because only you can say which sentence should stay. Keep rules that apply everywhere in one global file, and the project's own rules in its AGENTS.md.

# AGENTS.md

- Run `pnpm test` before calling work done; `pnpm lint --fix` formats.
- Database changes go through a migration in `db/migrations/`, never by hand.
- The API returns errors as `{ "error": { "code", "message" } }`. Keep it that way.
- The current spec is in `docs/SPEC.md`. Read it before planning; skip it for small fixes.

Keep it short

The file is part of every request, and a long one is followed less carefully, not more. For each line, ask: would a capable model get this wrong without being told, and would that cost something? Commands, pitfalls and conventions that differ from the usual pass. Directory layouts, dependency lists and architecture overviews do not; the agent reads those from the code.

  • A rule for one part of the tree goes in an AGENTS.md beside that code.
  • A procedure the agent needs only sometimes goes in a skill.
  • A plan, spec or design document stays a file. Name it in AGENTS.md, as above, and the agent reads it when the work calls for it.

An AGENTS.md over 24,000 characters is cut off, with a note telling the agent to read the rest of the file itself.

What Luxe removes

Two kinds of text are removed from AGENTS.md and skill files before the agent sees them, because neither is visible to someone reviewing the file:

  • Comments outside code blocks: HTML comments, <!-- … -->, and link definitions used as comments, such as [//]: # (…)
  • Invisible Unicode: tag characters, supplementary variation selectors, bidirectional overrides, and soft hyphens and other marks that draw nothing, written as characters or as references such as &#x202E;

A file that repeats one link label so often that Luxe cannot check every definition is left out entirely. For an AGENTS.md, Luxe says what it removed or left out when it starts; a skill file is cleaned without a notice.

Where the project begins

Luxe works on one project, found by walking up from where you started it:

  1. Inside a repository (.git, .jj or .hg), the nearest folder with a .luxe/ in it, up to the top of the repository
  2. Otherwise, the top of the repository
  3. Outside any repository, the folder you are in

So luxe started in crates/parser/src opens the whole repository, with its sessions, plan and reviews. The walk stops at your home folder. A Git worktree is its own project.

To keep a package of a monorepo separate, give it a .luxe/:

mkdir -p packages/app/.luxe

The package keeps its own sessions and still reads the AGENTS.md at the top of the repository.

Outside a repository, a .luxe/ claims only its own folder. Luxe writes one wherever it runs, so starting it once in ~/.config does not make ~/.config/herdr part of that project. @@@ page: providers

title: "Models and providers" summary: "Sign in to a provider, choose a model and thinking level, and run local models." order: 9 group: "Using Luxe"

Sign in

Open Configuration (on the start screen, or /config) and choose how to connect. When a provider connects, the model picker opens.

Option For
Sign in to a subscription ChatGPT Plus or Pro, GitHub Copilot, or OpenRouter (which signs you in and creates a key)
Add an API key Any provider below
Connect a local or custom model LM Studio, Ollama, Azure, or any OpenAI-compatible endpoint
Edit configuration files config.json, models.json, auth.json and keybindings.json, in $EDITOR

From the command line:

luxe auth login                          # choose a provider from a list
luxe auth login anthropic                # or name one
luxe auth login openai --stdin < key.txt # read the key from a file or a pipe
luxe auth list                           # every provider, and how each is configured
luxe auth status                         # credential type, where it came from, when it expires
luxe auth logout openai                  # remove a stored credential

In a session, /login, /logout and /auth do the same.

Signing in checks the key with one request for the provider's model list, and gives up on an endpoint that stops answering after LUXE_STREAM_START_TIMEOUT seconds. Typing an endpoint that is plain http:// and not on this machine works, with a warning that the key will cross the network unencrypted.

Providers

Provider ID Environment variable
OpenAI openai OPENAI_API_KEY
ChatGPT Plus or Pro openai-codex subscription only
Anthropic anthropic ANTHROPIC_API_KEY
GitHub Copilot github-copilot COPILOT_GITHUB_TOKEN
OpenRouter openrouter OPENROUTER_API_KEY
Google Gemini google GEMINI_API_KEY or GOOGLE_API_KEY
xAI xai XAI_API_KEY
DeepSeek deepseek DEEPSEEK_API_KEY
Groq groq GROQ_API_KEY
Cerebras cerebras CEREBRAS_API_KEY
Mistral mistral MISTRAL_API_KEY
Alibaba DashScope dashscope DASHSCOPE_API_KEY
Z.AI zai ZAI_API_KEY
Moonshot AI moonshotai MOONSHOT_API_KEY
Together AI togetherai TOGETHER_API_KEY
Fireworks AI fireworks FIREWORKS_API_KEY
NVIDIA NIM nvidia NVIDIA_API_KEY
Vercel AI Gateway vercel AI_GATEWAY_API_KEY
Microsoft Foundry foundry-openai, foundry-anthropic, foundry-completions FOUNDRY_API_KEY
Azure OpenAI azure AZURE_OPENAI_API_KEY
LM Studio lmstudio none
Ollama ollama none
Any OpenAI-compatible endpoint custom

A provider's own variable works without signing in; when you have signed in too, the sign-in is used. Anthropic and Google take API keys only: their terms do not allow their subscriptions to be used from other programs.

GitHub Copilot serves Claude through Anthropic's Messages API, its newer GPT, Grok and MAI models only through its Responses API, and the rest through chat completions. Copilot says which model takes which, and Luxe sends each one where it belongs. Claude goes to Messages even though chat completions would take it, because only Messages keeps its thinking, its effort level and the prompt cache for the whole conversation. The models offered are your plan's own, kept current each time the sign-in refreshes. Signing in turns on any model your plan offers that you have not been asked about yet; one you turned off stays off.

Where credentials are kept

Credentials are stored in ~/.config/luxe/auth.json (%APPDATA%\luxe\auth.json on Windows), readable only by you. Subscriptions refresh on their own. A key can be the key itself, an environment variable, or a command whose output is the key, so a password manager works:

{
  "openai": { "type": "api_key", "key": "sk-..." },
  "anthropic": { "type": "api_key", "key": "!op read op://vault/anthropic/credential" }
}

A command runs each time a request needs the key.

Choose a model

/model opens the model picker: every model your providers can serve, configured providers first. Type to search. The session carries on with the new model, even across providers, and Luxe remembers your choice for next time.

From the command line, --model takes a model ID, or provider/id to pick the provider too:

luxe --model anthropic/claude-opus-5

To see what Luxe knows about a model, or list what you can use:

luxe models show anthropic/claude-opus-5   # context window, output limit, thinking levels, price
luxe models list --provider anthropic      # every model; * is active, + is configured
luxe models refresh --force                # update the model catalog now

Luxe ships with the models.dev catalog built in and refreshes it in the background, so a model released after your copy of Luxe still has the right context window and price.

Thinking

/thinking sets how hard the model reasons before answering: Off, Minimal, Low, Medium, High, XHigh or Ultra. Levels the model does not support are grayed out. --thinking high sets it at launch.

Luxe remembers the level per model, since high on a frontier model and on a small local one cost very different amounts of time. To give a model its own starting level:

{
  "models": {
    "lmstudio/qwen3.8-27b": { "thinking": "medium" }
  }
}

The picker marks that level default. /thinking can still change it during a session.

Subscriptions

Usage on a ChatGPT or Copilot subscription is counted in full but never added to what you spent. /cost shows what it would have cost at API prices, as plan ≈$0.42 of usage over 12 calls, covered by your subscription. On a ChatGPT plan, the statusline shows how much of the plan is used, such as 12% weekly, and /cost shows when it resets. On a Copilot plan it shows the month's allowance the same way, such as 19% monthly.

Luxe prices Copilot usage at Copilot's per-token rates, so the figure matches what Copilot reports for each request. A Copilot plan billed by the token spends its monthly allowance at those rates.

A ChatGPT subscription serves its own set of models, different from OpenAI's API, and /model lists exactly those.

Local models

Connect a local or custom model asks for the endpoint (blank takes the default) and records it in ~/.config/luxe/models.json. No credential is needed.

Server Default endpoint
LM Studio http://127.0.0.1:1234/v1
Ollama http://127.0.0.1:11434/v1

The picker lists the models your server has loaded, asked fresh each time it opens. Embedding and reranking models are left out.

For reasoning controls, chat templates and sampling settings on a local server, see Custom providers.

Microsoft Foundry

One Foundry resource and key serve three APIs, which Luxe treats as three providers. Signing in to one configures all three:

luxe auth login foundry

It asks for the resource name, its endpoint, or a deployment's Target URI, and the key. Then choose a model with the provider that serves it:

Provider Serves Example
foundry-openai OpenAI's models luxe --model foundry-openai/gpt-5.6-terra
foundry-anthropic Claude luxe --model foundry-anthropic/claude-sonnet-5
foundry-completions DeepSeek, Grok, Llama, Mistral, Phi and Cohere luxe --model foundry-completions/deepseek-v4-pro

/model lists what your resource has deployed, not every model Azure offers. Luxe asks the resource for its deployments when you sign in and again each time you open /model, and sorts them onto the right provider by the model each one runs. luxe models refresh asks too. If a resource cannot list its deployments, /model shows Azure's catalog marked unverified, and you can list them yourself.

Use a deployment's name as the model ID, whatever it is called. For keyless sign-in with Microsoft Entra ID, see Custom providers.

When a provider stalls

Luxe waits 60 seconds for a provider to start answering, and 180 seconds between parts of a reply. If a provider is overloaded, rate limited or unreachable before it has sent anything, Luxe tries again after 2, 4 and 8 seconds, showing retrying (2/3) above the composer. Once a reply has started, a failure ends the turn rather than paying for the reply twice. A bad key or a refused request is not retried.

Variable Default Sets
LUXE_STREAM_START_TIMEOUT 60 Seconds to wait for a reply to start. 0 waits forever.
LUXE_STREAM_IDLE_TIMEOUT 180 Seconds a reply may go quiet. 0 waits forever.
LUXE_PROVIDER_RETRIES 3 Tries after the first. 0 never retries.
@@@ page: quickstart

title: "Quickstart" summary: "From first launch to a reviewed pull request." order: 2 group: "Get started"

This walks through one change from start to finish: connect a model, ask for something, review what the agent did, and open a pull request.

1. Start Luxe in your project

cd your-project
git switch -c category-enum    # a branch for the work, so it can become a pull request
luxe

Reviewing changes and opening a pull request need a Git repository. A pull request also needs a branch other than the one it merges into; luxe --worktree makes one for you, in a worktree of its own.

The first time, Luxe asks four questions: a theme, a provider, which tools the agent can use, and what Luxe opens on. Each one previews or explains itself, and enter moves on. s skips setup and keeps none of the answers, though a provider you signed in to stays signed in. Your answers go to ~/.config/luxe/config.json, and /settings or luxe init changes them later.

Setup, on its theme step

After that, Luxe opens on the start screen: a prompt, with your last session, your other sessions and Configuration listed under it, or Set up a provider first if you have none yet. Type to ask something or to find a session or a command, or use ↑/↓ and enter to open a row.

The start screen

2. Connect a model

If you skipped the provider question, the start screen leads with Set up a provider. Open it and pick one:

Option For
Sign in to a subscription ChatGPT Plus or Pro, GitHub Copilot, OpenRouter
Add an API key OpenAI, Anthropic, Google, Groq and others
Connect a local or custom model LM Studio, Ollama, Azure, any OpenAI-compatible endpoint

Configuration, before a provider is set up

When it connects, the model picker opens. Choose a model, and change it any time with /model.

An API key in your environment works too. Luxe finds ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY and the rest, and offers that provider's models. To sign in from a script or a machine without the interface, use the CLI:

luxe auth login                       # choose a provider from a list
luxe auth login anthropic --stdin < key.txt
luxe auth list                        # every provider and how it is configured

Credentials are stored in ~/.config/luxe/auth.json, readable only by you. See Providers for every option.

3. Ask for something

Type what you want on the start screen and press enter: it starts a new session and sends it. shift+enter adds a line.

a notification's category is a free-form string, so a typo compiles; make it an enum

The agent reads, edits and runs commands, and each step appears as a card. Click a card to see its full output, or press ctrl+o for every card's; ctrl+esc stops the turn. You can keep typing while it works: a message sent mid-turn reaches the agent between steps, without stopping it.

A turn in progress

Changes (ctrl+p) shows the diff so far, beside the conversation on a wide terminal and in its place on a narrow one.

4. Review the change

Press ctrl+g to start a Guided Review. Luxe writes a guide to the change, split into chapters, each with what changed, why, and how it was checked, next to the code. When review ready shows above the prompt, press ctrl+g again to open it.

Guided Review

Key Does
space Next
c Comment on the line under the cursor
a Ask the agent about it
alt+enter Finish the review
? Every key in the review

Comments go to the agent as work to do when you finish with Request fixes.

5. Open a pull request

This needs the GitHub CLI, gh, signed in (gh auth login): Open pull request is offered once gh says the branch has none. Finish the review (alt+enter) and choose it. Luxe drafts the title and description from the review. The heading says what happens before it opens, such as "commits and pushes first". The pull request pictured came from a session that took up an issue (luxe --issue 123), so its branch is named for the issue and its description closes it.

Opening a pull request

Press t or e to edit the title or description, d to open it as a draft, and enter to open it.

6. Come back later

Resume, the first row on the start screen, picks up your last session. From the command line:

luxe -c                    # the most recent session in this project
luxe sessions list         # this project's sessions, newest first
luxe --resume <id>         # a specific one

Next

  • The interface: the dock, the statusline, the Command Palette and every command.
  • Guided Review: reviewing someone else's pull request, and answering review threads on yours.
  • Configuration: themes, keys and the statusline.
  • Project context: give the agent your project's conventions in AGENTS.md. @@@ page: recipes

title: "Recipes" summary: "Extensions put together: Asana, subagents, a classifier guard, Herdr, and a local model." order: 8 group: "Extend"

Asana

Two ways to bring Asana in, and they work together: its MCP server, so the agent can read and update tasks, and a mention source, so you can point at one task with @.

The MCP server

Asana registers each app, so each person makes one of their own.

  1. Register an MCP app in Asana's developer console (My apps). Set its redirect URL to http://127.0.0.1:8765/callback, and leave This is a native or command-line app unchecked. Share it with your workspace. Your organization may need an admin to approve it.

  2. Keep the secret in your environment. In ~/.zshrc or ~/.bashrc, then open a new terminal:

    export ASANA_MCP_CLIENT_SECRET='…'
    
  3. Add the server, with your app's client ID, and hide the tools Asana marks as internal:

    {
      "mcpServers": {
        "asana": {
          "url": "https://mcp.asana.com/v2/mcp",
          "auth": {
            "kind": "oauth",
            "client_id": "1209…",
            "client_secret": "${ASANA_MCP_CLIENT_SECRET}",
            "redirect_uri": "http://127.0.0.1:8765/callback"
          },
          "exclude_tools": [
            "get_project_internal", "search_objects_internal", "log_widget_event",
            "create_task_confirm", "save_task_changes_confirm", "create_project_confirm",
            "create_project_confirm_populate", "save_project_changes_confirm"
          ]
        }
      }
    }
    
  4. Sign in and check what you can use:

    luxe mcp login --id asana
    luxe mcp tools
    
  5. Decide what the agent may do. Task names and comments go to your model provider when a tool returns them. To let reads through and ask before anything changes:

    {
      "permission": {
        "mcp": {
          "asana/create_*": "ask",
          "asana/update_*": "ask",
          "asana/delete_*": "ask",
          "asana/add_*": "ask"
        }
      }
    }
    

    If Asana's data may only go to a provider your organization approves, use "asana/*": "deny" until you are on one. In a headless or loop run, make the writes deny: nobody is there to answer an ask.

  6. Use it: @[mcp:asana] what is due this week?

Your tasks in the @ picker

This needs a personal access token (My apps → Personal access tokens), since the MCP sign-in's token works only for the MCP server. Your workspace's ID is in https://app.asana.com/api/1.0/workspaces, read with the same token.

#!/bin/sh
curl -sSf -H "Authorization: Bearer $ASANA_PAT" -G https://app.asana.com/api/1.0/tasks \
  --data-urlencode assignee=me --data-urlencode "workspace=$ASANA_WORKSPACE" \
  --data-urlencode completed_since=now --data-urlencode limit=100 \
  --data-urlencode opt_fields=name,due_on,permalink_url |
jq -c '.data[] | (if .due_on then "due \(.due_on)" else "no due date" end) as $due | {
  id: .gid,
  label: .name,
  detail: $due,
  text: "Asana task \"\(.name)\" (\($due)) \(.permalink_url)"
}'
{ "mentions": [{ "name": "Asana", "command": "asana-mentions" }] }

A task you pick goes in as @[asana:1209…] and reaches the agent as its name, due date and link, and the agent can look it up through the MCP server. See Mention sources.

Subagents

A subagent is a separate context that does one job and returns a summary, which is what a headless Luxe run is:

luxe --headless --read-only --model openai/gpt-5.6 --format json \
  -p "review src/parser.rs for edge cases" |
  jq -rs 'map(select(.type == "message" and .text != "")) | last.text'

--read-only keeps the subagent from changing anything, and --model lets it be a different model from the one doing the work. The jq filter keeps the last message with text in it, which is the summary. For a review of your own uncommitted work, /review does this without the wrapper.

To let the agent start one itself, wrap that command in an MCP server with a delegate(task, model) tool. Then:

  • Rule it like any tool: "mcp": { "delegate/*": "ask" } in permissions.json puts each one in front of you.
  • Give the server a timeout_secs longer than a review takes. A call gets 60 seconds by default, and one that runs out stops the subagent.
  • Return the subagent's stderr when it fails, so the agent sees why.
  • Give a subagent that writes its own worktree, with git worktree add, so it stays out of yours.

Luxe refuses to nest more than two levels deep, since an agent that starts two subagents per turn would multiply fast. LUXE_MAX_DEPTH raises the limit.

A guard that asks a model

A BeforeToolUse hook can ask a small classifier model whether a command is destructive, and ask you when it might be. This one calls a typed decision model running on your own machine, and the request follows that model's API; any model that returns a probability works.

#!/usr/bin/env bash
set -euo pipefail
command=$(jq -r '.ToolUse.args.command')

risk=$(jq -n --arg c "$command" '{
    state: { command: $c },
    questions: { destructive: { type: "noul",
      instructions: "Would running this command cause irreversible data loss?" } }
  }' |
  curl -sS --max-time 2 "${DECISION_URL:-http://localhost:8000}/v1/systemone" \
    -H 'Content-Type: application/json' --data @- |
  jq -r '.answers.destructive.noul')

if awk "BEGIN{exit !($risk > 0.8)}"; then
  jq -n --arg r "scored $risk for irreversible data loss" '{decision:"ask", reason:$r}'
else
  echo '{"decision":"allow"}'
fi
{
  "BeforeToolUse": [
    {
      "matcher": "bash",
      "command": ["/home/you/.config/luxe/hooks/risk-gate.sh"],
      "timeout_ms": 2500,
      "on_timeout": "ask"
    }
  ]
}
  • It asks rather than blocks. A hook can only make a call harder, so the worst a wrong answer costs is a prompt.
  • It adds to your rules, not replaces them. Keep what must always hold in permissions.json.
  • It runs before every matching call. The matcher keeps it off read and grep; narrow it further, such as { "bash": "rm *" }, to cost less.
  • on_timeout: "ask" puts the question to you if the classifier is down.
  • Nobody answers in a headless run, so its ask is allowed there. Use --on-ask deny, or "hook_ask": "deny" in permissions.json, to make it hold.

Run Luxe in Herdr

Herdr keeps coding agents in panes and shows which ones are working, waiting on you, or done. Luxe reports its state to Herdr on its own when it runs in a Herdr pane: working during a turn, blocked when it needs you, and done when the turn ends.

curl -fsSL https://herdr.dev/install.sh | sh
herdr
luxe        # in a pane

To let the agent drive Herdr, such as splitting panes or starting other agents, add Herdr's skill:

mkdir -p ~/.config/luxe/skills/herdr
curl -fsSL https://raw.githubusercontent.com/ogulcancelik/herdr/master/SKILL.md \
  -o ~/.config/luxe/skills/herdr/SKILL.md

LUXE_HERDR=0 or { "herdr": false } in Luxe's config turns the reporting off.

Luxe colors in Herdr

Herdr has no theme files — it takes a built-in theme plus per-token overrides. This is Luxe's own palette in those tokens, so the pane and the multiplexer around it read as one program:

[theme]
name = "vesper"          # the closest built-in; every token below is overridden anyway

[theme.custom]
accent        = "#ddc084"  # champagne, the one color Luxe leads with
text          = "#e4dfd6"
subtext0      = "#97938c"
overlay0      = "#4d4a45"
overlay1      = "#97938c"
sidebar_bg    = "#12100e"  # the base surface, same as Luxe's background
panel_bg      = "#12100e"  # the tab bar sits on it too, so the chrome is one field
surface0      = "#201e1a"
surface1      = "#2e2b27"
surface_dim   = "#201e1a"
active_row_bg = "#201e1a"  # the current space, at rest
selection_bg  = "#2e2b27"  # the Navigate cursor, which should be the brighter of the two
mauve         = "#d2a5cd"  # branch names
yellow        = "#ddc084"  # working — an agent at work glows in the accent
green         = "#81caa0"  # idle / done
red           = "#e68485"  # blocked, needs you
peach         = "#faaa51"  # interrupted
blue          = "#85c7d7"  # Luxe has one cool hue, so blue and teal share it
teal          = "#85c7d7"

[ui]
accent = "#ddc084"         # borders and navigation chrome, which read off their own key

Reload it in place with prefix+shift+r, or herdr server reload-config. For any of the other themes Luxe ships, the hexes are in its theme file and the token names above do not change.

The one token worth a second thought is panel_bg: Herdr draws the active tab as panel_bg text on an accent fill, so it has to stay dark enough to read there. Lifting it to #201e1a gives the tab bar a surface of its own if you prefer the chrome delineated.

A local model in LM Studio

  1. Load a model in LM Studio and start its server.
  2. In Luxe, open Configuration and choose Connect a local or custom model, then LM Studio. Leave the endpoint blank for the default.
  3. Choose the model in the picker that opens.

LM Studio ignores the chat-template settings Luxe sends a local server by default, so for thinking levels to reach the model, send them as reasoning_effort, and start each session at a sensible level. Connecting already wrote an lmstudio provider to models.json, so add these keys to it rather than replacing the file:

{
  "providers": {
    "lmstudio": { "compat": { "thinking_format": "openai" } }
  },
  "models": {
    "lmstudio/qwen3.8-27b": { "reasoning": true, "thinking": "medium" }
  }
}

Custom providers covers samplers and request formats. @@@ page: rpc

title: "The RPC protocol" summary: "Drive Luxe from your own program: an editor plugin, a dashboard, or a front end of your own." order: 7 group: "Extend"

luxe --rpc runs Luxe without its interface and speaks JSON over stdin and stdout, one object per line. Use it to build an editor plugin, a dashboard, a CI adapter, or a whole new front end, in any language.

luxe --rpc        # takes the usual flags: --model, --permission-mode, -c, --resume
luxe --rpc --github-writes   # also lets your client publish to GitHub

A client is trusted like the interface it replaces: it answers permission prompts, and it cannot loosen any permission rule. There is no network listener; your client is the process that started Luxe.

A session

→  {"kind":"ready","content":{"protocol_version":2,"luxe_version":"0.1.0","session_id":"…","cwd":"/work/app","github_writes":false}}
→  {"kind":"state_changed","content":{"model":{…},"streaming":false,"mode":"build","thinking":"off"}}
←  {"kind":"submit_user_message","content":{"text":"what does this repo do?"}}
→  {"kind":"tool_started","content":{"call_id":"call_1","name":"read"}}
→  {"kind":"token_delta","content":{"block":0,"delta":"It is "}}
→  {"kind":"turn_usage","content":{"prompt_tokens":5018,"completion_tokens":26,"cost_usd":0.0258,…}}
→  {"kind":"turn_ended","content":{"reason":"end_turn"}}
←  {"kind":"close"}

Every frame is {"kind": …, "content": …}, and a frame with no payload leaves out content. ready always comes first: check its protocol_version and refuse a number you do not know.

A client

import json, subprocess

luxe = subprocess.Popen(["luxe", "--rpc"], stdin=subprocess.PIPE,
                        stdout=subprocess.PIPE, text=True, bufsize=1)

def send(kind, content=None):
    frame = {"kind": kind} | ({"content": content} if content is not None else {})
    luxe.stdin.write(json.dumps(frame) + "\n")
    luxe.stdin.flush()

for line in luxe.stdout:
    event = json.loads(line)
    kind, body = event["kind"], event.get("content")

    if kind == "ready":
        assert body["protocol_version"] == 2, "unsupported protocol"
        send("submit_user_message", {"text": "What does this project do?"})
    elif kind == "token_delta":
        print(body["delta"], end="", flush=True)
    elif kind == "tool_started":
        print(f"\n[{body['name']}]")
    elif kind == "permission_requested":
        send("respond_permission", {"id": body["id"], "reply": "once"})
    elif kind == "question_asked":
        send("answer_question", {"id": body["id"], "reply": {"answered": ["yes"]}})
    elif kind == "action_rejected":
        print(f"\n! refused {body.get('kind')}: {body['reason']}")
    elif kind == "turn_ended":
        print()
        send("close")
    # Ignore everything else, so the client keeps working with newer versions of Luxe.

Three rules make a working client: read ready first, answer both kinds of prompt, and ignore what you do not recognize.

Actions

kind content Does
submit_user_message {"text": "…", "images": [{"data": "<base64>", "mime": "image/png", "name": null}]} Start a turn. images is optional.
steer_turn {"text": "…"} Reach the running turn between tool calls, without ending it. With no turn running, starts one.
withdraw_steering Drop steering messages not yet delivered
cancel Stop the turn
edit_resend {"text": "…"} Replace the last message and send it again
retry Send the last message again
regenerate Replace the last answer
respond_permission {"id": "perm:…", "reply": "once"} Answer a permission prompt: once, always, always_persist or reject
answer_question {"id": "ask:…", "reply": {"answered": ["postgres"]}} Answer a question, or {"reply": "cancelled"}
set_permission_auto_approve true Approve every prompt for the rest of the session. Deny rules still apply.
select_model {"provider": "anthropic", "model": "claude-sonnet-5"} Switch models
set_thinking_level "high" off, minimal, low, medium, high, xhigh or ultra
set_mode "plan" build or plan; see Plan, then build. A name that is not a mode is answered by a notice.
request_review {"focus": "error handling"}, or nothing A second opinion on the uncommitted changes; answered by review_started, then review_finished
new_session Start a new session
load_session "<session id>" Resume a session; answered by session_loaded
refresh_sessions Answered by sessions_refreshed
refresh_workspace Answered by workspace_updated
request_context_composition What fills the context window; answered by context_composition
compact_now {"focus": "the API decisions"}, or nothing Summarize now; answered by compaction_done
load_guided_review {"request_id": "…", "target": {"kind": "working_tree"}} Capture a Guided Review; see below
load_file_diff {"request_id": "…", "path": "src/main.rs"} One file's change, outside any review; answered by file_diff_loaded
list_directory {"request_id": "…", "path": "src"} One project folder's entries, without what .gitignore ignores unless "include_ignored": true, which marks each such entry "ignored": true; answered by directory_listed
read_project_file {"request_id": "…", "path": "src/main.rs"} One project file's text, up to 2 MB; answered by project_file_read
close Shut down, stopping a turn in flight the way cancel does. The stream ends after it.

Guided Review

A review is loaded with load_guided_review. Luxe answers with guided_review_loaded, which carries the whole review (its id, revision_id, files, hunks and chapters), and then always review_session_restored, which carries its comments. Everything below names the review by its id. An action for a review that is no longer the open one is refused.

←  {"kind":"load_guided_review","content":{"request_id":"r1","target":{"kind":"working_tree"}}}
→  {"kind":"guided_review_loaded","content":{"request_id":"r1","review":{"id":"review:…","revision_id":"…",…}}}
→  {"kind":"review_session_restored","content":{"session":{"id":"review:…","findings":[],…}}}
←  {"kind":"edit_review","content":{"request_id":"e1","review_id":"review:…","edit":"comment","anchor":{"kind":"line","file_id":"file:…","hunk_id":"hunk:…","side":"new","line":12},"body":"Why retry twice?","severity":"question","send":true}}
→  {"kind":"review_session_saved","content":{"request_id":"e1","session":{…}}}

edit_review changes the comments. Every one is answered once, under its request_id: with review_session_saved and the stored comments, or review_session_save_failed and why. The change goes in edit, beside request_id and review_id:

edit Fields Does
comment anchor, body; optionally severity (issue or question), title, proposed_fix, send A new comment. anchor is {"kind":"line","file_id","hunk_id","side","line"}, a hunk, a chapter, or {"kind":"review"}. The title defaults to the first line.
reply finding_id, body, optionally send A reply on its thread. A resolved comment opens again.
ask_for_fix finding_id, body, optionally send Turn an answered question into a request for the fix
edit_comment finding_id, severity, title, body, optionally proposed_fix Rewrite a comment not sent yet
delete_comment finding_id Delete a comment not sent yet
resolve, reopen finding_id Mark a comment resolved, or open it again
reanchor finding_id, anchor Move a comment whose code a refresh moved away
set_outcome outcome: accepted, changes_requested or commented Record how the review ended. The agent is not told.
send finding_ids; optionally mode (request_fixes, comment_only, question), outcome Send comments to the agent at the next turn. The mode defaults to what the strongest comment asks for.
cancel_send, retry_send submission_id Withdraw a send the agent has not started, or send a failed one again

send on a comment, reply or fix request sends it in the same save. A sent comment's turn shows up as review_session_saved while it runs: the agent's answer to a question, and its report on a fix, are recorded on the comments. You can keep editing while it works.

Each comment's thread says who said what, by author: reviewer, agent, or system for Luxe's own word. A fix turn that ends with no report on a comment leaves a system entry saying why, and the comment stays open.

kind content Does
edit_review {"request_id", "review_id", "edit", …} Change the comments, as above
record_review_progress {"review_id", "walked_chapter_ids": [...]} Which chapters were read. Saved when it changed, never answered.
record_review_seen {"review_id"} Remember what the walked chapters covered, so the next review of the same target leads with what is new
refresh_guided_review {"request_id", "review_id", "revision_id"} Read the change again, keeping the comments, if the review is still at revision_id. Answered like a load.
commit_review_chapters {"request_id", "review_id", "revision_id", "chapter_ids", "squash"} A commit per chapter, or one with squash. All chapters when chapter_ids is left out. Never pushes. Answered by review_committed.
prepare_pull_request {"request_id", "review_id"} Draft the pull request this branch's review would open; answered by pull_request_prepared
open_pull_request {"request_id", "title", "body", "draft"} Open the draft request_id named, with your title and description. Commits the reviewed work first when the draft said so. A GitHub write.
prepare_stack {"request_id", "review_id"} Draft a pull request per chapter; answered by stack_prepared
open_stack {"request_id", "draft"} Open the drafted stack, bottom first. A GitHub write.
prepare_pull_request_post {"request_id", "review_id"} Read what posting your review of a pull request needs; answered by pull_request_post_prepared
post_pull_request_review {"request_id", "verdict", "session_revision"} Post it with comment, approve or request_changes. A GitHub write.
prepare_thread_answers {"request_id", "review_id"} Whether your fixes are pushed yet, on your own pull request; answered by thread_answers_prepared
answer_threads {"request_id", "review_id", "answers": [{"finding_id", "reply", "resolve"}]} Reply to and resolve its threads, each named by the comment it became. A GitHub write.

The open_* and post_* actions confirm a preview by its request_id. Luxe keeps what it prepared, so you send back only what a person can change: a title, a description, a verdict. post_pull_request_review is refused if the comments changed after the session_revision you drew the preview from, so what posts is what you showed. A failed open or post can be confirmed again; a stack opens once.

GitHub

These go through your own gh, as the interface's /github and /pr do. repository is owner/name, and you leave it out for the checkout's own repository.

kind content Does
list_github {"sections": [{"name": "Mine", "query": "is:open is:pr author:@me repo:{repo}"}]}, or nothing Run /github's searches. With no sections, runs the ones in your config. Answered by github_listed.
search_github {"request": 7, "section": {…}, "after": "<cursor>"} One search on its own, or its next page; answered by github_searched with your request
read_github_overview {"repository": "acme/app", "number": 142, "pull_request": true} A pull request's or issue's status; answered by github_overview_read
read_github_conversation {"number": 142, "pull_request": true} Everything said on it; answered by github_conversation_read
draft_github_reply {"request_id": "…", "number": 142, "pull_request": true, "target": {…}, "conversation": […]} The agent drafts a reply in a turn that changes nothing; answered by github_reply_drafted. target and conversation are what github_conversation_read gave you.
check_pull_request_fix {"number": 142} Whether it can be checked out here to fix; answered by pull_request_fix_checked
plan_restack {"request_id": "restack:…"} What restacking this branch's stack would do; answered by restack_planned. Luxe keeps the plan.
check_worktree_removal What the session's worktree has not committed; answered by worktree_removal_checked
set_focus {"focused": false} Whether your window has focus. Luxe checks GitHub less often while it does not.
link_pull_request {"number": 142, "url": "…"} Record that this session worked on that pull request
post_github_comment {"number": 142, "thread": "PRRT_…", "body": "Fixed."} Post a reply in a thread, or a comment without thread; answered by github_comment_posted. A GitHub write.
change_pull_request {"number": 142, "write": {"change": "mark_ready"}} update_branch, mark_ready, merge, enable_auto_merge or disable_auto_merge; answered by pull_request_changed. A GitHub write.
restack {"request_id": "restack:…"} Push the plan plan_restack made under that id, exactly as planned; answered by restacked or restack_failed. A GitHub write.

You confirm a restack by its id, not by sending the plan back: Luxe pushes the plan it showed you. A newer plan_restack replaces the older plan, and a plan is pushed once. Before pushing, Luxe checks that every moving branch here is where the plan saw it, checked out where it was, and clean, and refuses with restack_failed otherwise. A push that did not finish is also restack_failed, and its message says to check the branches on GitHub, since some may have moved. If the push succeeds but the branches here, or a pull request's base on GitHub, cannot follow, the answer is restacked, with what went wrong in retarget_failed. A restack_planned with nothing to restack, such as no open pull request or no gh, carries a refusal and no plan.

--issue, --from-pr and --worktree work with --rpc as they do anywhere, since they decide the session before the first frame. See Git and GitHub.

An unknown kind is answered with action_rejected, which is also how to find out what a build supports. So is a malformed line, and nothing else happens: one bad line never ends the session.

←  {"kind":"steer_turn","content":{}}
→  {"kind":"action_rejected","content":{"kind":"steer_turn","reason":"steer_turn: missing field `text`"}}

Events

There are around sixty. These are the ones a front end is built on:

kind Is
ready The handshake: protocol version, Luxe version, session ID, directory
token_delta, thinking_delta The reply and reasoning as they stream. block orders them.
tool_call_composing The model has started writing a tool call. Optional; useful for showing a write filling in.
tool_started, tool_progress, tool_completed, tool_ended A tool call's progress, by call_id. tool_completed carries its output.
tool_activity_updated The card the interface draws for a call: title, body, state and timing
message_committed A complete message was added to the transcript
permission_requested Answer it with respond_permission, or the turn waits. If always_patterns is empty, offer only once and reject.
question_asked Answer it with answer_question
turn_ended The turn finished; reason says why
provider_retrying The provider failed before answering, and Luxe is trying again
state_changed Model, thinking level, mode, and whether a turn is running
plan_written Plan mode wrote path. The interface offers the plan's next step when the turn ends.
review_started, review_finished A requested review began on model, and came back with a verdict (continue, fix or unavailable) and findings. On fix the findings also become the agent's next turn.
turn_usage, session_usage, plan_usage Cost per call, for the session, and what a subscription has left
context_usage, context_composition How full the context window is, and with what
workspace_updated The project, Git changes, todos and tools: what the dock shows
session_loaded, sessions_refreshed A transcript was restored; the session list changed
notice, error Something to show. error ends the turn.
action_rejected Your frame was refused and nothing happened

Guided Review, as the interface sees it:

kind Is
guided_review_loading, guided_review_loaded, guided_review_failed A review you asked for, by request_id. loaded carries the whole review: files, hunks and chapters.
guided_review_guide_updated Better chapters and a summary replaced the first ones, for the same pinned revision
review_session_restored The comments and progress that go with the review just loaded. It always follows guided_review_loaded, after a restart too.
review_session_saved, review_session_save_failed A change to them was stored, or refused. Luxe reports its own changes this way too: a turn starting, the agent's report, a review posted.
review_feedback_turn_dispatched, review_feedback_turn_completed, review_feedback_turn_failed Feedback you sent reaching the agent, and how its turn went
review_questions_answered, remediation_reported The agent's answer to a question, and its report on a fix
review_committed, review_commit_failed Committing a review's chapters
last_turn_available The agent's last turn can be reviewed on its own
file_diff_loaded, file_diff_failed One file's change, for load_file_diff
directory_listed, directory_list_failed One folder's entries, for list_directory
project_file_read, project_file_read_failed One file's text, for read_project_file

GitHub:

kind Is
github_listed, github_searched Search results, with each section's rows or why it has none
github_overview_read, github_conversation_read One pull request or issue: its status, or everything said on it
github_reply_drafted, github_comment_posted A draft to edit and send, and where a sent one was posted
pull_request_changed, pull_request_fix_checked What a change did, and whether a fix can be checked out here
restack_planned, restacked, restack_failed A restack's plan, and what pushing it did
pull_request_prepared, pull_request_opened, pull_request_open_failed Opening a pull request from a review
stack_prepared, stack_opened Opening a review as a stack
pull_request_post_prepared, pull_request_review_posted, pull_request_post_failed Posting your review of a pull request
thread_answers_prepared, threads_answered, thread_answers_failed Replying to and resolving review threads on your own pull request
worktree_removal_checked What removing the session's worktree would lose

The branch's pull request, its checks and its review status come in workspace_updated, as they do for the interface's dock.

Treat an event you do not recognize as nothing.

Versioning

protocol_version is 2. New events, actions and fields do not change it, since a client that ignores what it does not know already handles them. It changes only when something a client could have relied on is removed or renamed. So dispatch on kind, ignore the rest, and do not assume the list is closed.

Security

  • Luxe listens on nothing; your client is the process that started it.
  • Permission rules are enforced inside Luxe. A client cannot weaken a deny: reading .env is refused here as everywhere.
  • Prompts go to your client to answer. To approve everything, send set_permission_auto_approve or start with --auto-approve. --on-ask is refused, since your client can answer.
  • --permission-mode, --read-only, --yolo and --trust-project apply as usual.

GitHub writes

Your client can read GitHub without asking. To let it publish there (post a comment or a review, answer threads, open, change, merge or restack a pull request), start Luxe with --github-writes. Without it, those actions are refused with action_rejected, and ready says "github_writes": false so you can hide them.

  • Read-only wins. With --read-only, or a read-only mode in your permissions file, the writes are refused even with the flag, and so is commit_review_chapters.
  • It is a flag, not a setting. Whoever starts Luxe decides, for that session. No config file turns it on, and a project cannot.
  • It covers your client, not the agent. The agent's own GitHub writes are permission rules: they ask first, and the prompt comes to your client. See Security.

Luxe is not a sandbox. To isolate it, run it in a container. @@@ page: security

title: "Security and permissions" summary: "What the agent may do, the rules and prompts that decide it, secrets, and what Luxe sends over the network." order: 1 group: "Reference"

The agent reads and writes files and runs commands on your machine. Luxe lets ordinary work through without asking, keeps a few guardrails on at all times, and gives you rules to tighten the rest. For real isolation, run it in a container.

What is allowed by default

Every tool call is allowed, asked about, or denied. With no configuration:

Denied Reading .env and .env.* files (.env.example is fine). Catastrophic commands: wiping /, your home folder or a system folder, mkfs, dd to a device, fork bombs. Running a command as root; see below. The same call with the same arguments a third time in a row: the agent is told it already has the result.
Asked Anything outside the project folder. git push --force. Committing. Writes to GitHub: opening, merging or commenting on pull requests and issues, and re-running CI. Capturing your screen.
Allowed Everything else

Commands are matched piece by piece, so cd /tmp && rm -rf / is caught. These are guardrails, not a security boundary: a model set on getting around a pattern can. Committing asks because a commit moves what Guided Review compares against; answer Allow always once and it stops asking.

Recursive rm has its own check, covering -r, -R, combined flags, --recursive and an end-of-options --. It catches /, /*, whole-home targets such as ~, $HOME and ${HOME}, and protected system folders and their contents. Ordinary build-folder cleanup stays allowed. /etc-backup/ isn't /etc, so its name alone doesn't trigger this guard. A Bash allowance or session approval cannot waive this check; --yolo disables the default guard.

Permission modes

luxe --permission-mode strict
Mode
default The defaults above
strict Ask before every change: write, edit, bash, git, debug, a test with its own command, and an applied ast_grep or lsp_navigation change
read-only Deny every change, and a test with its own command. Reading, search, code intelligence and detected tests still work. Also --read-only.
yolo Allow everything, guardrails off. Also --yolo. Your own deny rules still apply.

Plan mode is a different thing: the session's mode, not a permission mode. It refuses every change but a write to the plan file, before the permission rules are asked, so a rule that allows a command does not let plan mode run it. A review runs in a mode that refuses every change.

Rules

{
  "mode": "default",
  "permission": {
    "bash": { "*": "allow", "rm *": "ask", "git push * --force *": "deny" },
    "git": { "commit*": "allow" },
    "read": { "*": "allow", "*.env": "deny", "*.env.example": "allow" },
    "external_directory": { "~/scratch/**": "allow" },
    "mcp": { "github/*": "ask" }
  }
}
  • Keys are tool names (bash, read, edit, which also covers write, glob, grep, git, webfetch, websearch, screenshot, mcp), plus external_directory for paths outside the project, doom_loop for repeated calls, and hook_ask for hooks that ask.
  • Values are allow, ask or deny, or a map from pattern to one of them.
  • Patterns: * matches anything, ? one character, and ~ your home folder. git * also matches git alone. A bash pattern matches the command; a read or edit pattern, the path; an mcp pattern, server/tool.
  • The most specific pattern wins.

Bash chains are also checked segment by segment. An allowance for git * does not allow git status && curl example.com: the curl segment needs its own allowance. A denied segment blocks the call. Otherwise, if any segment asks, the call asks too. Every segment must be allowed for the whole chain to run without asking. The matcher is best-effort, not a shell parser.

Tools that run a program, change files or search a folder are judged by the same rules:

Tool Also checked as
test with a command bash, segment by segment, with its filter; a filter that hides a second command is checked too
debug launch bash, as the program and its arguments; a shell's -c script is checked as a command of its own
ast_grep replace with apply: true edit, for each path
lsp_navigation rename or code action with apply: true edit, for the file
grep, glob, ast_grep read, for the folder or file searched
module_report, read_symbol, lsp_navigation, lsp_diagnostics read, for each file opened

Each tool's own rules still apply alongside. A folder outside the project asks, and a named .env is denied even with all: true. Always on these prompts remembers only what was asked: the exact command for test and debug, the folder for one search outside the project, and nothing for an applied change, since its files aren't known until it runs.

grep and ast_grep also check every file they find before reading it, so a search of the whole project skips a nested .env; glob checks every name before listing it. A file your rules deny is skipped. One that would ask is read when the run approves asks on its own (headless by default, or with auto-approve on) and skipped otherwise, since a search can't stop to ask. The result says how many were skipped; read the file to be asked. A walk over a huge tree stops at 100,000 files and says so.

An applied rename or code action is refused whole if the language server's edit names a file outside the project or inside a fetched repository. These checks cover what a tool is asked to open. They don't sandbox a language server, which can index other files and runs the project's own code.

A project's .luxe/permissions.json can only make your rules stricter, never looser, unless you start Luxe with --trust-project.

The permission prompt

When a call needs approval, a prompt opens above the composer:

A commit waiting for approval, offering to remember git commit*

Choice Does
Allow once Run this call
Allow for this session Allow calls like it until you quit
Allow always Write the rule to your ~/.config/luxe/permissions.json
Reject Refuse; the agent is told and carries on

The prompt shows the rule an Allow always would write: a command family, such as cargo *, or the whole folder for a path outside the project. A hook's prompt or a chained Bash command offers only Allow once and Reject: one command family cannot cover a chain. Choose with the arrows and enter, or a number; esc rejects. For a moment after it opens, the prompt ignores every key but esc, so typing meant for the composer cannot answer it.

When you step away

Auto-approve (/permissions on, or --auto-approve) allows every call that would ask, while your deny rules still hold. The statusline says auto-approve for as long as it is on.

A run with nobody to answer, such as --headless, luxe loop or a phase reviewer, allows every ask by default. To refuse them instead, and tell the agent why:

luxe --headless --on-ask deny -p "…"

or "agent": { "on_ask": "deny" } in config.json. A project can set deny but not allow.

Four GitHub actions need a person: merging a pull request, closing one, submitting a review, and closing an issue. Auto-approve and unattended runs refuse them. To let an unattended run do one, allow it in your own rules, such as "bash": { "gh pr merge *": "allow" }.

Secrets

  • Credentials are stored in ~/.config/luxe/auth.json, readable only by you. Luxe warns if auth.json or models.json can be read by others.
  • A key is found in this order: --api-key or LUXE_API_KEY, then what you signed in with, then the provider's own variable, then a provider block in auth.json or models.json. For a provider Luxe does not know, the block comes before OPENAI_API_KEY. The order is the same for the provider a session starts on and for one you switch to in /model.
  • A key can be $VAR or !command rather than the value, so it never sits in a file. A command runs when a key is needed, so treat these files like your shell's startup file. It runs from your home folder and is stopped after 30 seconds, so a password manager that asks for a passphrase needs a graphical prompt.
  • Anything that looks like a secret (API keys, tokens, private keys, passwords in URLs) is removed from tool output before the model, the transcript, hooks or the log see it. So is every key and token Luxe itself has used or loaded, whatever it looks like, including $VAR and !command keys and MCP tokens, as long as it is at least 8 characters.
  • MCP sign-in tokens are kept in ~/.local/state/luxe/mcp-auth.json, outside your config folder, so a dotfiles repository never carries them.
  • An MCP server's auth token or OAuth sign-in only travels over https, or plain http to this machine; a server or sign-in endpoint elsewhere on plain http is refused. A key you put in a server's headers is not checked, so use https for one. See MCP.
  • Anthropic and Google take API keys only, since their terms do not allow their subscriptions in other programs.

Commands that need root

The agent does not run commands as root: sudo, doas, su, pkexec, run0, and gsudo or runas on Windows. A command that needs root needs your attention and consent, and typing it into your own terminal is how you give both. So when a step needs one, the agent puts the exact command in a code block, you copy it into another terminal and run it, then tell the agent it is done.

The same goes for a command that waits on you at a terminal, such as a password, a confirmation or an interactive installer. Commands the agent runs have no terminal at all, so one of those fails at once and says what it wanted, rather than waiting where nobody can answer.

To allow it anyway, decide ahead of time in your global file. It only helps where no password is needed, such as a passwordless sudo rule for one program:

{ "permission": { "bash": { "sudo pacman *": "allow" } } }

--yolo allows it too. A project's .luxe/permissions.json cannot.

Screen capture

The screenshot tool's url mode renders a web page and captures only that. Its fullscreen, region and window modes capture whatever is on your screen, and the image goes to your model provider, so each asks first, and runs with nobody watching refuse them. To turn screen capture off entirely:

{ "permission": { "screenshot": { "fullscreen": "deny", "region": "deny", "window": "deny" } } }

Untrusted repositories

Opening a repository should not run its code. So, without --trust-project:

  • Its .luxe/hooks.json is ignored.
  • Its gate.commands in .luxe/config.json are ignored with a warning. The loop uses your global commands instead; a project list needs --trust-project.
  • Its .luxe/permissions.json can only tighten your rules.
  • Its MCP servers, language servers and formatters start only in an interactive session; see Tools.

Its AGENTS.md and skills, including the ones it commits in .agents/skills/, still reach the model, because your own project's are the point of the feature. Luxe removes text a reviewer cannot see, comments and invisible Unicode, and leaves out a file it cannot finish checking; see What Luxe removes. Plain text is still instructions, so read an unfamiliar repository's AGENTS.md as you would its Makefile. Text from GitHub, such as issues and comments, is filtered the same way and given to the agent as someone else's words, not as instructions. So are MCP servers' descriptions and results.

A language server can run project code itself: rust-analyzer runs build.rs. Treat opening a repository in Luxe like building it.

A repository the agent fetches with web_fetch is different: you never chose to open it. Luxe clones it into .luxe/gh-cache/ with symbolic links flattened to plain files, and starts no language server or formatter there; see Tools.

Isolation

Rules are a policy, not a sandbox. For hard isolation, run Luxe in a container that mounts only the project:

docker run --rm -it -v "$PWD":/work -w /work -e ANTHROPIC_API_KEY <image-with-luxe> \
  luxe --headless -p "…"

Do not mount your home folder or SSH keys. --network none works for everything but the model provider, the web tools, the catalog refresh and the update check.

What Luxe sends over the network

There is no telemetry. Luxe connects only to:

  1. The model provider you configured, including the cache refreshes described in Keeping the cache warm ("agent": { "cache_warming": "off" } stops them). For GitHub Copilot that includes reading your plan's usage from GitHub every few minutes while you work (LUXE_COPILOT_PLAN_USAGE=0 stops it). For an Azure resource it includes listing what the resource has deployed when you open /model ("discover_deployments": false on the provider stops it)
  2. Search providers and web pages, when the agent uses web_search or web_fetch, and GitHub when web_fetch clones a repository ("tools": { "clone_repositories": false } stops it)
  3. The models.dev catalog, to refresh model details (LUXE_MODELS_DEV_REFRESH=0 stops it)
  4. The update check, once a day ("update": { "check": false } stops it), and when you run luxe update or /update, which then runs your package manager's own update
  5. GitHub, through your own gh, when you, the agent or an RPC client work with pull requests and issues. A client can write there only if you start it with --github-writes.

None of them carries anything about you or your machine. The update check sends no version, platform or identifier; it downloads a public file and compares versions locally.

One local report stays on your machine: inside a herdr pane, Luxe runs herdr's own command to tell it whether the agent is working, idle or waiting on you, and the id of the session for herdr to resume. Nothing is sent outside herdr, and "herdr": false stops it.

What you post to GitHub is yours alone: reviews, replies and pull requests are posted from a preview, with nothing added, and no agent tool can post them.

Supply chain

Luxe is written in Rust with unsafe code denied throughout, apart from two reviewed blocks in what ships: one starts each command in a session of its own, so nothing the agent runs can reach your terminal, and one on Windows keeps the programs Luxe starts off the stdin --rpc reads. CI checks every dependency's security advisories and license with cargo-deny, builds with --locked, and pins its GitHub Actions to exact commits. @@@ page: sessions

title: "Sessions and context" summary: "Resume past sessions, see what fills the context window, and how Luxe keeps long sessions going." order: 8 group: "Using Luxe"

Sessions

Every conversation is saved as it goes, in .luxe/sessions/ inside the project. Quitting loses nothing.

To In Luxe From the command line
Pick up the last session Resume on the start screen luxe -c
Find an older one Type part of its title on the start screen, or open Sessions… (/sessions) luxe sessions list, then luxe --resume <id>
Return to the session that worked on a pull request type #146 in Sessions… luxe --from-pr 146
Start fresh /new, or type on the start screen and press enter luxe

Sessions…, with the selected session's conversation previewed

Sessions… searches session titles and what was said in them, with a preview of the one under the cursor. /sessions opens it from the start screen or from inside a session. However you resume a session, it runs in its own worktree when it has one, and keeps what you had typed and the mode, model and thinking level you chose. /new keeps the session you leave, so you can come back to it.

Cost

The dock's SESSION section shows context used, tokens and cost as you go. /cost shows the session's cost with the tokens behind it, how much of the input was read from the provider's cache, and, once more than one of them has spent something, the split between agent, review, compaction and cache warming. On a ChatGPT or Copilot plan, it shows what the usage would have cost at API prices, and what is left of the plan's allowance when the provider reports it. A model that charges more for a long prompt, as models.dev lists for some Claude and Gemini models, is priced at the higher rate for each request past the threshold. A price you set in models.json replaces the catalog's, tiers and all.

Keeping the cache warm

Anthropic keeps a cached prompt for five minutes after it was last read. A turn that waits longer than that, on a slow command, a permission prompt or a question, loses the cache, and the next request pays to write the whole conversation again: about $2 on a 400k-token Opus session. So while a turn runs, Luxe re-sends its last request with a one-token reply just before the five minutes are up. That costs a cache read, a tenth of the write it saves.

agent.cache_warming decides when:

Value Keeps the cache warm
streaming (default) While a turn is running
idle While a turn is running, and for up to 30 minutes after it
off Never

A refresh goes out only when it is expected to save at least $0.05, so a short conversation is never refreshed. Between turns Luxe cannot know you will reply, so idle refreshes only a large conversation. On real sessions it lost money overall, which is why it is not the default. Refreshes are never sent on a subscription plan, or for an Anthropic model using a fixed thinking budget, whose cache would change on replay. Their cost shows under cache warming in /cost.

The other answer to a long pause is supports_long_cache_retention, which asks Anthropic to keep the cache for an hour; see Custom providers. It costs more on every turn instead of on each pause.

The context window

/context shows what fills the context window, largest first:

 GPT-5.6 Sol   18.5k of 1.1M · 2% used

  conversation     9.6k   52%
      `read` crat…-tui/src/statusline.rs   9.2k
  tool schemas     4.5k   25%
  instructions     2.8k   15%
  harness          1.5k    8%
  free             1.0M
Row Is Shrink it with
conversation Messages, tool calls and results, reasoning, images /compact, /new
tool schemas The tools the agent can call tools.disabled; see Tools
instructions Your AGENTS.md files A shorter file; see Project context
skills The list of skills the agent can load Fewer, or shorter descriptions
harness Luxe's own instructions Nothing; this is fixed
appended One-time context added to a resumed session, such as what changed while you were away /new

The largest single items are named under a row, which is usually how you find a read or bash call that should have been narrower. The total is what the provider reported for the last request.

Compaction

When a conversation fills 90% of the usable window, Luxe summarizes it and carries on, keeping the most recent part word for word. The summary records the goal, constraints, progress, decisions, next steps and the files the session touched. You see a line like Compacted the conversation — 82k → 21k of context.

/compact summarizes now. Add what matters to steer the summary: /compact the API decisions. A conversation that already fits in what keep_recent keeps has nothing to summarize, and /compact says so.

Before summarizing, from 80% full, Luxe first replaces old tool output in the request with a short placeholder. The session file keeps everything; only what is sent changes.

To change when and how it happens:

{
  "compaction": {
    "auto": true,
    "at": 0.9,
    "keep_recent": 20000,
    "reserve": 20000,
    "prune": true,
    "summarizer": "anthropic/claude-haiku-4-5"
  }
}
Key Default Does
auto true Summarize automatically. Off leaves it to /compact and turns pruning off too; a request the provider refuses as too long is still summarized and sent again, once.
at 0.9 How full the usable window gets before summarizing. Pruning starts 0.1 earlier.
keep_recent 20000 Tokens of the newest conversation kept word for word
reserve 20000 Most tokens held back for the reply when judging how full the window is, or the model's output limit if that is smaller
prune true Replace old tool output before summarizing
summarizer the session's model The model that writes the summary, as provider/id, on a provider you have set up. A smaller, cheaper model is usually enough, and /cost prices its spend as it does any other model's.

This works in a project's .luxe/config.json too, and so does agent.cache_warming, which a project can turn down but not up. The compaction settings in /settings apply the next time Luxe starts.

Long command output

Build, test and lint output is trimmed before the agent sees it. Errors, warnings, failing tests, file:line locations and exit codes are always kept; progress bars, color codes and repeated lines are not. When output is trimmed, the untouched text is saved under .luxe/artifacts/ (each stream whole up to 8 MB, or its first and last 4 MB past that) and its path is included, so the agent can read it if it needs to. Set LUXE_COMPRESS=0 to turn this off; output past the size limit is still cut and saved.

Searches and listings (grep, glob, git log) are capped the same way, with a note saying how many more results there are. @@@ page: skills

title: "Skills" summary: "Teach the agent a procedure it loads only when it needs it." order: 2 group: "Extend"

A skill is a playbook in a SKILL.md file: how your team reviews a migration, cuts a release or writes a changelog entry. The agent sees each skill's name and description, and loads the full text only when a task calls for it, so a long skill costs nothing until it is used.

Write a skill

One folder per skill, with a SKILL.md in it:

Folder For
~/.agents/skills/<name>/ Every project, and every agent that reads it
~/.config/luxe/skills/<name>/ Every project (%APPDATA%\luxe\skills on Windows)
.agents/skills/<name>/ This repository, committed with it
.luxe/skills/<name>/ This project. Git sees it too, since .luxe/ keeps skills/ out of what it ignores.

.agents/skills/ is where Codex, OpenCode, Pi, GitHub Copilot and the npx skills installer put skills, so one installed for any of them works here too. Luxe reads a repository's .agents/skills/ from the top of the repository down to the project. When two skills share a name, whatever its case, the one lower in the table wins, so a project's skill replaces your own, and between nested .agents/skills/ folders the deeper one wins. A skill reached twice through a symbolic link counts once.

---
name: release-notes
description: >
  Writes the CHANGELOG entry for a user-visible change. Use when a change
  adds, removes or alters something a user would notice.
---

1. Read the diff and the issue it closes.
2. Add one line under `## Unreleased` in CHANGELOG.md, in the past tense,
   naming what changed for the user, not how.
3. Link the pull request at the end of the line.

Write the description for the moment the agent decides whether to load it: say when to use it, not what it contains. Without one, the agent sees only the name. name is optional and defaults to the folder's, and the --- block has to start on the first line.

A skill folder can also hold reference files. A loaded skill tells the agent its folder, so a skill that says see references/schema.md gets read. A skill over 40,000 characters is cut off, with a note telling the agent to read the rest of the file.

Use a skill

The agent loads a skill when its description fits the task. To ask for one yourself, mention it: @, tab to Skills, and enter, as in split this into a stack with @[skill:gh-stack].

Project context lists the skills Luxe found: type skills on the start screen and open it. A SKILL.md placed directly in skills/, without its own folder, is skipped, and Luxe names it at startup. The list in the agent's instructions is read with a session's first message, and again when you resume one. The @ picker and the skill tool look again every time, so a skill added mid-session can be mentioned or loaded at once.

Install a skill

Skills written for other agents use the same format and work as they are. Installing one is copying its folder:

git clone --depth 1 https://github.com/github/gh-stack /tmp/gh-stack
mkdir -p ~/.config/luxe/skills
cp -r /tmp/gh-stack/skills/gh-stack ~/.config/luxe/skills/

Create skills/ first, as above. Without it, cp -r copies the skill's contents to skills/ itself, one level too high.

A skill's text reaches the model as instructions, so read a skill before installing it, as you would a script. The same goes for a repository you clone: its .agents/skills/ and .luxe/skills/ reach the model without --trust-project. Luxe removes comments and invisible characters from skill files, as it does from AGENTS.md, but without a notice. @@@ page: tools

title: "Tools" summary: "What the agent can use: files, the shell, tests, Git, code intelligence, a debugger and the web." order: 10 group: "Using Luxe"

What the agent can use

Tool Does
read Read files, several at once, with numbered lines. A long file comes back a page at a time. An image is read as a picture for models that can see.
write, edit Write or change a file. A file must be read before it is edited, and the card shows the diff, after formatting.
bash Run a shell command. Long output is trimmed, and the untouched output saved under .luxe/artifacts/: each stream whole up to 8 MB, or its first and last 4 MB past that.
test Run the project's tests and report each failure with its file:line, and which tests your change broke. Output is saved as bash's is.
grep, glob Search file contents and names, with capped output
ast_grep Search and replace by code structure. Needs ast-grep.
git Status, diffs, history, commits, branches, and GitHub pull requests, issues and CI checks through gh
todo The agent's checklist, shown in the dock's PLAN
question Ask you a question with choices, in a picker
skill Load a skill
symbol_search, read_symbol, module_report Find symbols across the project and read one without the whole file
impact What else a change to a symbol or file affects: callers, dependents and covering tests
lsp_diagnostics, lsp_navigation Errors and warnings, definitions, references and types, from a language server
debug Drive a debugger: breakpoints, stepping, inspecting variables. Offered when a debug adapter is installed.
web_search, web_fetch Search the web and read pages; see Web
screenshot Capture a web page or your own dev server, with a Chromium-based browser, or with your approval, your screen; see Screen capture
mcp Call tools on the MCP servers you configured, when there are any

Each tool has to beat the shell command it replaces. luxe.dev/tools shows how, measured.

A call with an argument the tool does not know still runs, and its result names the argument it ignored, with the one the agent probably meant.

/tools lists what the agent can use in the current session, and why any tool is missing. Some tools are sent with every request; the rest are listed by name and loaded when the agent first needs one, which keeps every request smaller.

The test tool runs tests the way the project does: through its own .venv or the package manager its lockfile names (uv, poetry, pnpm, yarn and so on), not whatever happens to be on PATH.

Turn tools off

The Tools page of /settings turns each one on or off, or set it in the file:

{ "tools": { "disabled": ["web_search", "screenshot"] } }

A change applies the next time Luxe starts, since the tools the agent is offered are fixed for a run.

For one session, luxe --no-tool web_search turns a tool off and luxe --with-tool web_search turns one back on. read, write, edit and bash cannot be turned off.

Format on save

Each file the agent writes or edits goes through its formatter, and the result shows the file as the formatter left it. That includes a file changed by an applied rename, code action or ast_grep rewrite. rustfmt and gofmt always run. The others run only where the project has their config, in the file's directory or one above it:

Language Formatter Runs when the project has
Rust rustfmt, at the project's edition always
Go gofmt always
Python ruff ruff.toml, .ruff.toml, or [tool.ruff] in pyproject.toml
TypeScript, JavaScript biome biome.json or biome.jsonc
TOML taplo taplo.toml or .taplo.toml

A formatter that is not installed is skipped. When Luxe pipes a file through one (taplo), an empty answer, or a file that changed again while it ran, leaves the file as it was. To turn formatting off:

{ "tools": { "format_on_save": false } }

Time limits

Every tool call has a time limit, after which it is stopped: 120 seconds, or 60 for tools that wait on the network. bash defaults to 30 seconds and test to 300, and the agent can ask for longer, up to an hour. question waits for you as long as it takes. LUXE_TOOL_TIMEOUT_SECS replaces the 120- and 60-second limits; bash and test keep their own.

ctrl+esc stops the whole batch of calls, not just the one running. A call that never started is reported as having had no effect; one stopped partway says so, since it may have done half its work.

A command that starts something and leaves it running, such as a dev server, returns when the command itself ends. The server keeps running.

Tools work from the directory Luxe was started in. A cd inside one bash call does not carry over to the next, so start Luxe in the project you want to work on.

Code intelligence

After every edit, Luxe asks the file's language server for errors and warnings and adds the ones the edit introduced to the result the agent sees, so it can fix what it broke before moving on. Problems that were already in the file are counted, not listed. The result also names changed code that no test covers. Set LUXE_LSP_ON_EDIT=0 to turn both off.

The agent is held to small files and functions: 500 lines and 20 lines. When an edit takes a file or a function past one of those for the first time, the result says so, so the agent can split it while the change is fresh. A file that was already long says nothing more. Functions are measured in Rust, Python, Go, TypeScript and JavaScript; files in any language. Set LUXE_SIZE_CHECK=0 to turn this off, for a project whose own conventions differ.

Luxe launches these language servers when they are installed:

Language Server Install
Rust rust-analyzer rustup component add rust-analyzer
TypeScript, JavaScript typescript-language-server, tsgo for TypeScript 7, or tsc --lsp npm i -g typescript-language-server typescript
Python pyright, or basedpyright npm i -g pyright
Go gopls go install golang.org/x/tools/gopls@latest
C, C++ clangd apt install clangd, brew install llvm
Bash bash-language-server npm i -g bash-language-server
Ruby ruby-lsp, or solargraph gem install ruby-lsp
Lua lua-language-server mise use -g lua-language-server
Svelte svelte-language-server npm i -g svelte-language-server
JSON vscode-json-language-server npm i -g vscode-langservers-extracted
YAML yaml-language-server npm i -g yaml-language-server

A rename or code action the agent applies writes only inside the project. An edit naming a file anywhere else, or inside a fetched repository, is refused whole. Otherwise every file is written or none is, and the result says which edits didn't fit their file and which file operations, such as creating or renaming one, it left undone.

/lsp shows which servers are running, and luxe doctor starts each one to check it works. Luxe never installs a server itself. When one is missing, the result tells the agent the command that installs it, which runs through bash under your rules like any other.

A server the project installed

Luxe prefers the copy a project installed for itself, in its node_modules/.bin or virtual environment, since that version matches the project. The same goes for formatters such as ruff and biome, and for MCP servers a project declares. Runs with nobody watching, such as --headless and the loop, use only what you installed yourself unless you pass --trust-project. To decide for every run, in your own config:

{ "lsp": { "project_servers": "always" } }

auto (the default) uses a project's servers when you are watching, always uses them every time, and never uses only yours. A project's own config cannot change this.

A language server runs your project's build tooling. rust-analyzer runs build.rs and procedural macros, and a TypeScript server loads tsconfig.json plugins. For a repository you do not trust, use a container rather than relying on this setting.

Add a language server

{
  "ruby": {
    "command": "ruby-lsp",
    "extensions": ["rb"],
    "root_markers": ["Gemfile"],
    "install_hint": "gem install ruby-lsp"
  }
}

An entry for a language Luxe already knows changes only what it names, so { "rust": { "command": "rust-analyzer-nightly" } } swaps the binary and keeps the rest. alternatives lists other servers to try, in order, when the first will not start.

Debugger

The debug tool drives a real debugger, so the agent can set breakpoints, step through code and inspect variables rather than add print statements. After three failing test runs in a row, Luxe suggests it. LUXE_DEBUG_NUDGE=0 turns that suggestion off.

Language Adapter
Python debugpy (pip install debugpy)
Rust, C, C++ CodeLLDB, lldb-dap or gdb
Go Delve (dlv)

/debug shows which adapters are installed and any running sessions. To add one, reuse the launch style of a built-in adapter (debugpy, lldb, gdb or delve). This one debugs Zig programs with lldb-dap:

[
  {
    "id": "zig",
    "command": ["lldb-dap"],
    "extensions": ["zig"],
    "dialect": "lldb"
  }
]

transport is stdio (the default) or tcp_dial_in, for an adapter that connects back to Luxe: put ${DAP_ADDR} in its command where it takes the address, as Delve's dlv dap --client-addr ${DAP_ADDR} does, and Luxe replaces it with host:port. addr_placeholder names a different placeholder.

A breakpoint the adapter could not set is listed under the launch, with the adapter's reason. An adapter that fails to start says why, with what it printed.

Web

web_search works without a key. To use a particular search provider, set its key; the first one set is used:

Key Provider
none Exa, through its public endpoint
BRAVE_API_KEY Brave
TAVILY_API_KEY Tavily
EXA_API_KEY Exa, on your own account
FIRECRAWL_API_KEY Firecrawl

web_fetch reads a page as markdown. If a page refuses, it tries again as a browser, and then, with FIRECRAWL_API_KEY set, in a real browser for pages built with JavaScript.

web_fetch and screenshot reach the internet and your own machine (localhost), so your dev server works. Other machines on your network, cloud metadata addresses and file:// are refused, including through an IPv6 address that carries one of them. A page elsewhere can't redirect a fetch to your machine, and a fetch reads at most 10 MB. screenshot loads only the host you asked for, so a redirect, frame or image from any other host fails to load, and it runs the browser on a fresh profile, sandboxed unless Luxe runs as root or in a container. LUXE_WEB_ALLOW_PRIVATE=1 lifts the address checks, allows file:// in screenshot, and lets it load other hosts. A fetch gives up after 30 seconds, or LUXE_WEB_TIMEOUT_SECS, within the call's 60-second limit.

A search provider's other features, such as crawling a site, are available through its MCP server; see MCP.

GitHub repositories

Given a repository address, such as https://github.com/owner/repo, web_fetch clones it instead of reading the page, so the agent can search the real files. The clone is shallow, the latest commit only, and goes into .luxe/gh-cache/owner/repo in your project, which git ignores. Reading it never asks permission, because it is inside the project.

A repository you did not write sits inside one you did, so Luxe keeps it inert:

  • Symbolic links are checked out as plain files holding the link's target. A link cannot point the agent at your .env, or anywhere else outside the clone.
  • Git never prompts. A private repository needs your git credentials for github.com, for example from gh auth setup-git.
  • Git LFS files, submodules and tags are not downloaded.
  • Language servers and format-on-save do not start there, because rust-analyzer would run the repository's build.rs.
  • Nothing in it runs unless the agent runs it with bash, under your permission rules as usual.

A clone over 500 MB on disk, or one that takes longer than 45 seconds, is stopped and removed. Fetching a clone more than a day old clones it again, and a clone nobody has fetched in 14 days is deleted. To clear them all, delete .luxe/gh-cache/.

The files are still text the agent reads, and text can carry instructions, so treat a clone like any other page from the web. To read repositories as web pages instead:

{ "tools": { "clone_repositories": false } }

@@@ page: troubleshooting

title: "Troubleshooting" summary: "Common problems, where Luxe logs, and what to include in a bug report." order: 4 group: "Reference"

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.