luxe 0.1.4: remembered models, wheel-driven lists, and a steadier phone app

- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in
  opens the model picker instead of choosing for you.
- Every list in a modal takes the mouse wheel and a draggable scrollbar.
- The phone app shows reasoning in full, stays put while you read back through a long session, and
  shows a question's answer on its card.
- On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup
  again.
- The file tree no longer shows "engine busy" in a large project, loop output is easier to follow,
  and the name is written lowercase.

The CHANGELOG has the full list.
This commit is contained in:
Evan Whittaker
2026-10-20 13:51:34 -05:00
parent 6184aa21fb
commit a0666d6c81
591 changed files with 4926 additions and 2942 deletions

View File

@@ -1,11 +1,11 @@
---
title: "The RPC protocol"
summary: "Drive Luxe from your own program: an editor plugin, a dashboard, or a front end of your own."
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
`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.
@@ -15,7 +15,7 @@ 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. Nothing listens on the network. Your client either started Luxe, or
loosen any permission rule. Nothing listens on the network. Your client either started luxe, or
[joined a session](#join-a-running-session) open in the interface on the same machine.
## A session
@@ -68,7 +68,7 @@ for line in luxe.stdout:
elif kind == "turn_ended":
print()
send("close")
# Ignore everything else, so the client keeps working with newer versions of Luxe.
# 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
@@ -83,7 +83,7 @@ client above works with `["luxe", "join"]` in place of `["luxe", "--rpc"]`.
```bash
luxe join --list # sessions running on this machine
luxe join # the one running in this folder
luxe join 5898d57b # one by the start of its id, or by its Luxe's process id
luxe join 5898d57b # one by the start of its id, or by its luxe's process id
```
After `ready` comes the session so far: `session_loaded` with the transcript, the latest
@@ -96,7 +96,7 @@ A joined client is a guest in someone else's session:
- **Either side can answer a prompt.** The first answer counts, and `prompt_closed` tells everyone
to put the prompt away. The interface says which client answered.
- **It can't switch or end the session.** `new_session` and `load_session` are refused with
`action_rejected`. `close`, or the end of your stdin, disconnects you and leaves Luxe running.
`action_rejected`. `close`, or the end of your stdin, disconnects you and leaves luxe running.
- **GitHub writes are off**, and `ready` says `"github_writes": false`.
- **Keep reading.** A client that falls far behind gets a `notice` and is disconnected. Join
again for a fresh copy of the session.
@@ -106,7 +106,7 @@ leaves, by the name it gives in `introduce` if it sends one within a second of c
its process id. A device the bridge introduces as `yours`, paired by you, is listed but not
announced: you know your own phone joined, and a phone reconnects often.
A running Luxe lists its session in a file in its [runtime folder](environment.md#integrations),
A running luxe lists its session in a file in its [runtime folder](environment.md#integrations),
`<pid>.json`, with the `address` to connect to: a Unix socket, or a named pipe on Windows. Connect
there yourself to skip `luxe join`.
To stop sessions being joined, set [`joinable`](configuration.md#joining-a-session) to `false`.
@@ -140,12 +140,12 @@ To stop sessions being joined, set [`joinable`](configuration.md#joining-a-sessi
| `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` |
| `introduce` | `{"name": "iPhone"}` | A joined client's name, which the interface uses when it says who joined or answered. Add `"watch_only": true` as your first line to read without being announced; Luxe then drops everything else you send. `"yours": true` says the person at the terminal paired it, so it's listed without a line in the conversation. Refused from the client that started the session. |
| `introduce` | `{"name": "iPhone"}` | A joined client's name, which the interface uses when it says who joined or answered. Add `"watch_only": true` as your first line to read without being announced; luxe then drops everything else you send. `"yours": true` says the person at the terminal paired it, so it's listed without a line in the conversation. Refused from the client that started the session. |
| `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
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.
@@ -182,7 +182,7 @@ goes in `edit`, beside `request_id` and `review_id`:
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
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`.
@@ -203,7 +203,7 @@ the comment stays `open`.
| `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
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;
@@ -222,16 +222,16 @@ These go through your own `gh`, as the interface's `/github` and `/pr` do. `repo
| `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. |
| `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. |
| `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
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
@@ -256,7 +256,7 @@ 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 |
| `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. |
@@ -266,7 +266,7 @@ There are around sixty. These are the ones a front end is built on:
| `question_asked` | **Answer it** with `answer_question` |
| `turn_started` | A turn began, from any client. It comes before the turn's message is saved, and `turn_ended` always follows. A client joining mid-turn gets it as part of catching up. |
| `turn_ended` | The turn finished; `reason` says why |
| `provider_retrying` | The provider failed before answering, and Luxe is trying again |
| `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. |
@@ -288,7 +288,7 @@ Guided Review, as the interface sees it:
| `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. |
| `open_review_shown` | The answer to `show_open_review`, under its `request_id`: the open `review` and its `session`, or neither when no review is open. `reading` says what each chapter asks of the reader: `needs_review` items, and the `reason` when one thing accounts for all of them. |
| `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_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 |
@@ -330,7 +330,7 @@ list is closed.
- Nothing listens on the network. A [joined](#join-a-running-session) session takes connections
on a local socket or pipe that only your user account can open, and turns away any program the
agent itself started, so the agent can't answer its own prompts.
- Permission rules are enforced inside Luxe. A client cannot weaken a `deny`: reading `.env` is
- Permission rules are enforced inside luxe. A client cannot weaken a `deny`: reading `.env` is
refused here as everywhere.
- Prompts go to your client to answer. To approve everything, send `set_permission_auto_approve` or
start with `--auto-approve`. `--on-ask` is refused, since your client can answer.
@@ -339,15 +339,15 @@ list is closed.
### 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`.
answer threads, open, change, merge or restack a pull request), start luxe with `--github-writes`.
Without it, those actions are refused with `action_rejected`, and `ready` says
`"github_writes": false` so you can hide them.
- **Read-only wins.** With `--read-only`, or a read-only mode in your permissions file, the writes
are refused even with the flag, and so is `commit_review_chapters`.
- **It is a flag, not a setting.** Whoever starts Luxe decides, for that session. No config file
- **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](security.md#when-you-step-away).
Luxe is not a sandbox. To isolate it, run it in a [container](security.md#isolation).
luxe is not a sandbox. To isolate it, run it in a [container](security.md#isolation).