The RPC protocol

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

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:

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.

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.

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:

Guided Review, as the interface sees it:

GitHub:

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

Treat an event you do not recognize as nothing.

Versioning

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

Security

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

GitHub writes

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

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

Luxe is not a sandbox. To isolate it, run it in a container.