- 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.
234 KiB
@@@ 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.
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.mdalone - 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:
--modeland--thinkingon the command lineLUXE_MODELandLUXE_PROVIDERin the environment- The model you last chose
default_modelinmodels.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:
- A
luxe.jsonin the current Omarchy theme. To give every theme one, write a template at~/.config/omarchy/themed/luxe.json.tpland Omarchy renders it from each theme's colors. - Luxe's built-in theme of the same name, when both are dark.
- 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.
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, orf1tof12. - 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.jsonapplies 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:
launchersandmentions, which run programsupdate, andgithub.refresh_secslsp.project_serversagent.on_ask, which a project can set todenybut not toallowagent.cache_warming, which a project can turn down but not up, since it spends your money
Project gate.commands also run programs. Luxe ignores them and warns unless you start with
--trust-project. With trust, a nonempty project list replaces your global list. Otherwise, the
loop uses your global commands. Move the list to your own config if you don't want to trust the
project.
Editing
luxe init asks the first run's questions again (a theme, a provider, the tools, and the start
screen) and writes the answers to config.json, changing only those keys. It also writes a
config.schema.json beside it so your editor can complete and check every key. --defaults writes
a file that chooses nothing, without asking, and so does a run with no terminal; with a
config.json already there, either one needs --force, which removes the old file first. Luxe ignores a key it does
not know, so an old config always loads on a newer Luxe; check the spelling if a setting seems to
do nothing.
/reload (ctrl+shift+r) applies changes to config.json and keybindings.json without
restarting.
Settings
/settings, or Settings in Configuration, shows the settings you are most likely to change
as controls, on five pages: Appearance, Conversation, Dock & statusline, Tools, and Agent. Each
change writes one key to your config.json and leaves the rest of the file as it was.
| 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:
- The models.dev catalog built into Luxe, which works offline
- A fresher copy, refreshed in the background into
~/.cache/luxe/models-dev.json - 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": nullin the provider'scompatstops 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>saysnever off. - Luxe identifies itself to OpenRouter with its
HTTP-RefererandX-Titleheaders, which carry nothing about you."openrouter_headers": falseincompatdrops 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.
/worktreesays where the session is working./worktree removeends 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 }inconfig.jsongives 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 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.
| 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 |
Search
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.
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
- In
/pr, presst. The unresolved threads open in Guided Review as comments on their lines, against your working tree. alt+usends them to the agent. It reads them as the reviewers' words, not as instructions.- Verify each fix (
rin Feedback), then commit and push. alt+enterand choose Answer on GitHub. Threads you verified are resolved;cadds a reply in your own words.
Conversation
Conversation is the second tab in /pr and /github: the description, comments, reviews and
threads, oldest first.
| 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.
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…, apassword = "…") - A weakened check: a deleted test, an added
#[ignore], an edit to CI ordeny.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:
| 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.
- 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.
aasks the agent about a line, at the pull request's commit.ctrl+rreads 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.
allowmeans no opinion; a hook can only make a call harder. To auto-approve, write a rule inpermissions.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
askrule, 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" }inconfig.json, refuses everyaskin an unattended run, and tells the model why.{ "permission": { "hook_ask": "deny" } }inpermissions.jsonturns every hook'saskinto 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 doctorchecks 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"
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.
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.
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 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.
# 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:
- Your commands. Each must pass.
- A reviewer, if
gate.reviewis 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.
| 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:
~/.agents/AGENTS.md, the file many people keep for every agent they use~/.config/luxe/agents.md, for every project in LuxeAGENTS.mdat the top of the repository- One
AGENTS.mdper 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.mdbeside 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
‮
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:
- Inside a repository (
.git,.jjor.hg), the nearest folder with a.luxe/in it, up to the top of the repository - Otherwise, the top of the repository
- 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.
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.
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 |
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.
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.
| 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.
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.
-
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. -
Keep the secret in your environment. In
~/.zshrcor~/.bashrc, then open a new terminal:export ASANA_MCP_CLIENT_SECRET='…' -
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" ] } } } -
Sign in and check what you can use:
luxe mcp login --id asana luxe mcp tools -
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 writesdeny: nobody is there to answer anask. -
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" }inpermissions.jsonputs each one in front of you. - Give the server a
timeout_secslonger 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
matcherkeeps it offreadandgrep; 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
askis allowed there. Use--on-ask deny, or"hook_ask": "deny"inpermissions.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
- Load a model in LM Studio and start its server.
- In Luxe, open Configuration and choose Connect a local or custom model, then LM Studio. Leave the endpoint blank for the default.
- 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.envis refused here as everywhere. - Prompts go to your client to answer. To approve everything, send
set_permission_auto_approveor start with--auto-approve.--on-askis refused, since your client can answer. --permission-mode,--read-only,--yoloand--trust-projectapply 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 iscommit_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 coverswrite,glob,grep,git,webfetch,websearch,screenshot,mcp), plusexternal_directoryfor paths outside the project,doom_loopfor repeated calls, andhook_askfor hooks that ask. - Values are
allow,askordeny, or a map from pattern to one of them. - Patterns:
*matches anything,?one character, and~your home folder.git *also matchesgitalone. Abashpattern matches the command; areadoreditpattern, the path; anmcppattern,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:
| 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 ifauth.jsonormodels.jsoncan be read by others. - A key is found in this order:
--api-keyorLUXE_API_KEY, then what you signed in with, then the provider's own variable, then a provider block inauth.jsonormodels.json. For a provider Luxe does not know, the block comes beforeOPENAI_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
$VARor!commandrather 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
$VARand!commandkeys 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
authtoken or OAuth sign-in only travels overhttps, or plainhttpto this machine; a server or sign-in endpoint elsewhere on plainhttpis refused. A key you put in a server'sheadersis not checked, so usehttpsfor 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.jsonis ignored. - Its
gate.commandsin.luxe/config.jsonare ignored with a warning. The loop uses your global commands instead; a project list needs--trust-project. - Its
.luxe/permissions.jsoncan 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:
- 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=0stops it). For an Azure resource it includes listing what the resource has deployed when you open/model("discover_deployments": falseon the provider stops it) - Search providers and web pages, when the agent uses
web_searchorweb_fetch, and GitHub whenweb_fetchclones a repository ("tools": { "clone_repositories": false }stops it) - The models.dev catalog, to refresh model details (
LUXE_MODELS_DEV_REFRESH=0stops it) - The update check, once a day (
"update": { "check": false }stops it), and when you runluxe updateor/update, which then runs your package manager's own update - 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… 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.