Files
luxe/docs/guide/interface.md
Evan Whittaker d2129a886f Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
2026-10-20 02:40:13 -05:00

15 KiB

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

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

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

The start screen

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

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

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

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

The start screen with a search typed

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

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

Styles

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

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

The minimal start screen

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

The conversation

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

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

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

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

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

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

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

The composer

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

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

While the agent works, you can keep typing:

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

A waiting message sits above the composer, marked steering or queued, until it is delivered. A message with an image is always queued, because steering carries text only.

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. While a phone or another client has joined, a joined row names it.

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