Files
luxe/docs/guide/agent.md
Evan Whittaker f3ed35beb5 luxe 0.1.5: a provider picker, model ids, and a guided review that says less
The dock's provider row opens a list of providers, and the model picker opens on the provider in use, with tab to widen it; signing in opens it on the provider just signed in to. Models go by their id unless config names them, and the model row wears its maker's mark.

The guided review's guide prompt is shorter, the pull request brief shows the start of the description with the rest behind p, its commits drop the Luxe-review and Luxe-revision lines, and the weakened-gates signal is gone.

luxe update reruns the installer it was installed with, in place of luxe-cli-update. The preview's FILE tab reads files the session changed outside the project, and only those. Smaller fixes: bash headers are highlighted, the preview loses a blank row, the launcher divider sits inside its frame, and the phone app's top bar is clear of iOS's blur.

rustls-webpki 0.103.16 and webpki-roots 1.0.10 fix RUSTSEC-2026-0381 and RUSTSEC-2026-0382, and vite 8.3.4 fixes GHSA-587h-7wmj-h5pm, GHSA-698v-4r3x-3vcv and GHSA-r825-w8mm-5pxw.
2026-10-22 13:25:32 -05:00

140 lines
5.9 KiB
Markdown

---
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`](project-context.md) to make it stick.
## Questions
When the agent needs a decision, it asks in a picker. Each option has a one-line reason, the one it
recommends is marked and selected, so agreeing is one keypress. The last option is always
**Type your own answer**: start typing anywhere and it's picked, so `enter` sends what you wrote.
![A question from the agent, with its recommended answer selected](images/agent-question.svg)
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`](loop.md) works
through. When a turn writes the plan, luxe asks what next:
- **Build it here**, with the planning conversation still in context
- **Build it in a fresh session**, starting from `PLAN.md` alone
- **Run it as a loop**: switch to build and say how to start [`luxe loop`](loop.md), 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:
```json title="~/.config/luxe/config.json"
{
"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:
```json title="~/.config/luxe/config.json"
{ "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.
```json title="~/.config/luxe/config.json"
{ "reviewer": { "model": "openai/gpt-5.6", "thinking": "high" } }
```
The same reviewer is the second check in [`luxe loop`](loop.md#check-each-phase).
## Which model a session starts on
In order, the first that is set:
1. `--model` and `--thinking` on the command line
2. `LUXE_MODEL` and `LUXE_PROVIDER` in the environment
3. The model you last chose in this project
4. The model you last chose anywhere
5. `default_model` in `models.json`
luxe never picks a model for you, and signing in doesn't either: the model picker opens on the
provider you signed in to, at the top of its models, for you to choose. 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:
```json title="~/.config/luxe/config.json"
{ "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:
```json title="~/.config/luxe/config.json"
{ "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.