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.
This commit is contained in:
@@ -1,154 +1,77 @@
|
||||
# Luxe — voice
|
||||
# Luxe's voice
|
||||
|
||||
How Luxe writes, everywhere a person reads it: the site, the README, `--help`, tool descriptions,
|
||||
error messages, release notes.
|
||||
How Luxe sounds anywhere a person reads it: the TUI, the phone app, the site, the guide, `--help`,
|
||||
errors and release notes. How the agent talks is set in `luxe-core::context`, not here.
|
||||
|
||||
This is not the agent's runtime communication contract — that is product behavior and lives in
|
||||
`luxe-core::context` (`SystemPromptBuilder::build_base_harness`). The two agree, but they are
|
||||
enforced in different places: that one by the prompt, this one by whoever is writing.
|
||||
**In one line:** plain, direct and warm. Luxe sounds confident because it's good, not because it
|
||||
says so.
|
||||
|
||||
---
|
||||
## Principles
|
||||
|
||||
## The register
|
||||
- **Say it plainly.** Short words, short sentences. "Start", not "initiate". If a word can go, it
|
||||
goes. Read it out loud: if you wouldn't say it to a friend at their desk, rewrite it.
|
||||
- **Lead with what matters.** The point first, then the detail.
|
||||
- **Talk to one person.** "You". Never "we" or "users".
|
||||
- **Show, don't boast.** A fact beats an adjective: "Works with over 8,000 models", not "Works
|
||||
with all the best models". CI fails on the marketing words listed in `scripts/voice-check.py`.
|
||||
- **Use the real name.** Feature names, git terms and key names are what people search for. Explain
|
||||
one if you have to; don't swap it for a cuter word.
|
||||
- **Don't oversell the model.** Luxe drives models; it isn't one. Talk about what Luxe does: what
|
||||
the model sees, what it can touch, how you review what it did.
|
||||
- **Have some fun, in the right places.** Wordplay belongs in headlines and empty states: "As good
|
||||
as it gits.", "Get excited." Never in errors, buttons, permission prompts or anything read when
|
||||
something's gone wrong. One per screen at most.
|
||||
|
||||
Luxe already has a voice. It is in `AGENTS.md` and `PROGRESS.md`, and it sounds like this:
|
||||
## UI text
|
||||
|
||||
> Windows is a gate, not a hope.
|
||||
>
|
||||
> A test that names a program has named a platform.
|
||||
>
|
||||
> The blocker was never the version.
|
||||
>
|
||||
> A check that only ever sees correct input proves nothing.
|
||||
>
|
||||
> A promotion is a claim, and a wrong one renders as tofu.
|
||||
The TUI and the phone app use labels, not sentences. People glance at UI; they don't read it.
|
||||
|
||||
Declarative. Specific. Willing to say what it cost. No adjective stacks, no throat-clearing. The job
|
||||
is to carry that outward, not to invent something friendlier for the front page — a product that
|
||||
writes one way in its journal and another way in its marketing is telling you which one is true.
|
||||
| What | Do | Don't |
|
||||
| --- | --- | --- |
|
||||
| Button | `Review changes` | `Click here to review your changes` |
|
||||
| Key hint | `ctrl+g to review` | `Press ctrl+g to open a review of what changed.` |
|
||||
| Status | `Compacting` | `Luxe is now compacting your conversation…` |
|
||||
| Empty state | `No sessions yet. Run luxe in a project to start one.` | `Nothing to see here!` |
|
||||
| Error | `No shell found. Install Git for Windows and try again.` | `Oops! Something went wrong.` |
|
||||
|
||||
---
|
||||
- **Buttons start with a verb:** Send, Allow once, Review.
|
||||
- **Sentence case** for titles and buttons: `Command palette`.
|
||||
- **Keys in lowercase,** the way the TUI draws them: `ctrl+p`, `alt+enter`, `esc`. A capital means
|
||||
Shift, so `G` is Shift+G.
|
||||
- **No period** on labels, hints or status. A full sentence in a message gets one.
|
||||
- **Errors say what happened, then what to do.** No "oops", no "sorry", no blame.
|
||||
- **Empty screens say what to do next.**
|
||||
- **One word per thing.** Once something has a name, use it everywhere.
|
||||
|
||||
## Rules
|
||||
## The site
|
||||
|
||||
### 1. A claim carries its evidence
|
||||
|
||||
Numbers, or nothing. The evidence is what separates a fact from a boast, and Luxe has the facts.
|
||||
|
||||
> **Yes** — 2481 tests. The whole suite cross-compiled and run against Windows in twenty-two seconds.
|
||||
> **No** — Thoroughly tested. Blazingly fast CI.
|
||||
|
||||
If a claim has no number behind it, either find one or cut the sentence.
|
||||
|
||||
### 2. Name the trade-off
|
||||
|
||||
This is the rule that makes the others believable, and it is the least-copied thing about how this
|
||||
project writes. Every real engineering decision cost something. Say so.
|
||||
|
||||
> **Yes** — The chamfer ships in three grades because a terminal either draws the triangle at exact
|
||||
> cell metrics or invents its own shape. A kitty user sees a one-step bevel until someone runs the
|
||||
> probe, and never sees a broken glyph.
|
||||
> **No** — Beautiful, pixel-perfect rendering on every terminal.
|
||||
|
||||
A page with no cost on it reads as a page that hasn't been used.
|
||||
|
||||
### 3. No marketing adjectives
|
||||
|
||||
Banned outright, on top of the runtime list (*leverage, delve, robust, seamless, intricate, pivotal,
|
||||
realm*): **effortless, magical, blazingly, revolutionary, game-changing, powerful, simply, just,
|
||||
supercharged, next-generation, unleash, elevate**.
|
||||
|
||||
Note *simply* and *just*. They almost always precede something that isn't simple, and they tell the
|
||||
reader that if it's hard for them, that's their fault.
|
||||
|
||||
### 4. Vary sentence length
|
||||
|
||||
A paragraph of same-length sentences reads as generated, because it usually is. Land the point on a
|
||||
short one.
|
||||
|
||||
### 5. Second person
|
||||
|
||||
"You." Never "we", never "users", never "developers everywhere". Luxe is talking to the one person
|
||||
reading it.
|
||||
|
||||
> **Yes** — Your files live where your platform keeps them.
|
||||
> **No** — We store user configuration in platform-appropriate locations.
|
||||
|
||||
### 6. Headlines are statements, with a full stop
|
||||
|
||||
> **Yes** — It runs where you already work.
|
||||
> **No** — Runs everywhere! · Cross-Platform Support
|
||||
|
||||
### 7. Never oversell the model
|
||||
|
||||
Luxe drives models; it is not one. Output quality belongs to the model. What Luxe can claim is what
|
||||
it does with one: what reaches it, what it is allowed to touch, what happens to the result.
|
||||
|
||||
> **Yes** — The system prompt stays byte-identical between turns, so the cache prefix holds. You can
|
||||
> check: `LUXE_WIRE_LOG=… luxe wire`.
|
||||
> **No** — Luxe writes better code.
|
||||
|
||||
### 8. Say the real word, then gloss it
|
||||
|
||||
Never swap a precise term for a fuzzy one — the precise term is what the reader will search for.
|
||||
Keep it and explain it in the same breath.
|
||||
|
||||
> **Yes** — A review gate: a command that has to pass before a turn counts as done.
|
||||
> **No** — A special checkpoint thingy that makes sure everything's okay.
|
||||
|
||||
---
|
||||
|
||||
## Applying it
|
||||
|
||||
**Nouns.** *Harness*, not "platform" or "solution". *Turn*, not "interaction". *Tool*, not
|
||||
"capability". *Model*, not "AI".
|
||||
|
||||
**The name.** "Luxe" in prose, `luxe` in a command. Never "LUXE" outside the logotype.
|
||||
|
||||
**Lists.** Prose by default. A list is for genuinely parallel items, and it earns itself when the
|
||||
items are scannable — a list of three sentences is a paragraph wearing a costume.
|
||||
|
||||
**Errors** get the most care, because they are read at the worst moment. State what happened, what
|
||||
it means, and the one thing to do next. No apology, no blame.
|
||||
|
||||
> **Yes** — No POSIX shell found. `bash` needs one for the pipelines a model writes. Install Git for
|
||||
> Windows and Luxe will find it — it doesn't need to be on `PATH`.
|
||||
> **No** — Error: shell not found. Please ensure your environment is configured correctly.
|
||||
|
||||
**Release notes** lead with what changed for the reader, not with the internal refactor that caused
|
||||
it.
|
||||
|
||||
---
|
||||
- **Headlines are short statements, with a period:** "A better way to build."
|
||||
- **Body copy is two or three sentences,** then show it. A screenshot beats a paragraph.
|
||||
- **Numbers come from the source** (`facts.json`), never typed by hand.
|
||||
|
||||
## The guide
|
||||
|
||||
`docs/guide/` is read by people using Luxe and by the agents they point at it, usually while they
|
||||
are in the middle of something. Most of the rules above still hold. These come first.
|
||||
People read `docs/guide/` mid-task, and so do the agents they point at it.
|
||||
|
||||
- **Answer the reader's question.** How do I, what does, where is. Rationale stays only where it
|
||||
changes what the reader does; history and internals go in commit messages.
|
||||
- **Short.** Lead with the task. One example per idea. If a sentence can go, it goes.
|
||||
- **Labels over prose.** Headings name the task or the thing: *Add an MCP server*, *Statusline
|
||||
modules*. A table for options, a list for steps, prose for what neither can carry.
|
||||
- **Features by name.** Keys can be rebound, so name the feature and give the default key after it:
|
||||
**Fix with agent** (`f`), the **Command Palette** (`ctrl+k`).
|
||||
- **Keys in lower case**, the way a keybindings file spells them and the TUI draws them: `ctrl+p`,
|
||||
`alt+enter`, `esc`. A capital means Shift, so `G` is Shift+G and `ctrl+p` never reads as
|
||||
Ctrl+Shift+P.
|
||||
- **Every config example names its file**, in the fence: ` ```json title="~/.config/luxe/config.json" `.
|
||||
The site shows it above the block, and a test loads it as that file. A fragment that will not
|
||||
load does not get a title, and should rarely exist.
|
||||
- **Written to be followed by an agent.** Each page opens with what it covers. Headings are tasks.
|
||||
Blocks are complete enough to paste. No "see above": link the heading.
|
||||
- **Links name the file**, `configuration.md#github`, so they work on GitHub, on the site and in the
|
||||
terminal.
|
||||
- **Plain words.** No *lands*, *arrives* or *invariant*; few em dashes. `scripts/docs-check.py`
|
||||
holds both, along with the links.
|
||||
- **Answer the question:** how do I, what does, where is. History goes in commit messages.
|
||||
- **Headings name the task:** "Add an MCP server".
|
||||
- **A table for options, a list for steps,** prose only for what neither can carry.
|
||||
- **Name the feature, then its default key:** the **Command Palette** (`ctrl+k`). Keys can be
|
||||
rebound; names can't.
|
||||
- **Every config example names its file** in the fence:
|
||||
` ```json title="~/.config/luxe/config.json" `. A test loads it as that file.
|
||||
- **Links name the file,** `configuration.md#github`, so they work on GitHub, the site and in the
|
||||
terminal. No "see above": link the heading.
|
||||
|
||||
---
|
||||
`scripts/docs-check.py` checks the links, the frontmatter and a short list of words.
|
||||
|
||||
## The check
|
||||
## Words
|
||||
|
||||
Read it aloud. If a sentence sounds like a landing page, cut it. If a paragraph could describe any
|
||||
other coding agent with the nouns swapped, it says nothing — replace it with the specific thing Luxe
|
||||
does that the others don't.
|
||||
- **Luxe** in prose, `luxe` for the command. Never all caps.
|
||||
- **Model,** not "AI". **Coding agent,** not "platform" or "solution".
|
||||
- **American spelling.** `scripts/voice-check.py` checks it, comments included.
|
||||
|
||||
## Before you ship it
|
||||
|
||||
Read it out loud. If another tool could put its name on the sentence, make it specific. If it sounds
|
||||
like an ad, cut it.
|
||||
|
||||
@@ -83,6 +83,16 @@ script can tell a failure from an answer without reading the output.
|
||||
| `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 join [id]` | Join a session another Luxe is running, speaking the [RPC protocol](rpc.md#join-a-running-session) on stdin and stdout. The id can be its start, or the Luxe's process id; without one, it joins the session running in this folder. |
|
||||
| `luxe join --list` | Sessions running on this machine that can be joined |
|
||||
| `luxe remote` | Serve this machine's sessions to your own phone or tablet. Listens on this machine only, for Tailscale Serve to carry to your devices, and lets in this machine's tailnet owner from a paired device. |
|
||||
| `luxe remote --port <n>` | The port it listens on (default 4519) |
|
||||
| `luxe remote --allow <login>` | Also let this tailnet login in, as Tailscale names it (`alex@github`). Repeatable. |
|
||||
| `luxe remote setup` | Check Tailscale, offer to publish the bridge on your tailnet with Tailscale Serve, offer to run it at login as a user service, then show a QR code to pair a device. Each step that changes something outside Luxe asks first. |
|
||||
| `luxe remote pair` | Show a QR code and link that pair one phone or tablet. They work once, within ten minutes. |
|
||||
| `luxe remote devices` | The paired devices |
|
||||
| `luxe remote devices revoke <id>` | Unpair a device. Its open sessions close within a few seconds. |
|
||||
| `luxe remote service remove` | Stop the bridge's user service and stop it starting at login |
|
||||
| `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](mcp.md#servers-a-project-brings). |
|
||||
| `luxe mcp remove --id <id>` | Remove a server from the project's `.luxe/mcp.json` |
|
||||
|
||||
@@ -139,6 +139,19 @@ This is local to your machine and on by default. Outside herdr nothing is sent.
|
||||
{ "herdr": false }
|
||||
```
|
||||
|
||||
### Joining a session
|
||||
|
||||
A running Luxe lets another program on this machine join its session: `luxe join`, a script, or
|
||||
whatever you build on [the RPC protocol](rpc.md#join-a-running-session). Only your user account can
|
||||
connect, and nothing listens on the network. To turn it off:
|
||||
|
||||
```json title="~/.config/luxe/config.json"
|
||||
{ "joinable": false }
|
||||
```
|
||||
|
||||
`LUXE_JOINABLE=0` turns it off for one run. A project's config can turn it off too, but can't turn
|
||||
it back on once yours has.
|
||||
|
||||
### Updates
|
||||
|
||||
Once a day, Luxe checks whether a newer release exists, and when one does the start screen says
|
||||
@@ -204,6 +217,7 @@ Every key in `config.json`, with its default.
|
||||
| `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](#herdr) |
|
||||
| `joinable` | `true` | Let another program on this machine join a running session; see [Joining a session](#joining-a-session) |
|
||||
| `statusline.visibility` | `auto` | `auto`, `shown` or `hidden`; see [Appearance](appearance.md#statusline) |
|
||||
| `statusline.style` | `slab` | `slab` or `flat` |
|
||||
| `statusline.left` | `["project", "branch", "pr", "todo", "changes"]` | Modules on the left |
|
||||
|
||||
@@ -54,6 +54,7 @@ UTF-8 is ignored, as if the variable were unset.
|
||||
| `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_NESTED_INSTRUCTIONS` | `1` | `0` stops reading the [`AGENTS.md` of folders](project-context.md#folders-the-agent-works-in) the agent works in |
|
||||
| `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 |
|
||||
@@ -70,6 +71,8 @@ UTF-8 is ignored, as if the variable were unset.
|
||||
| `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](recipes.md#run-luxe-in-herdr) |
|
||||
| `LUXE_UPDATE_CHECK` | `0` turns off the update check |
|
||||
| `LUXE_JOINABLE` | `0` stops other programs [joining](configuration.md#joining-a-session) this run's session |
|
||||
| `LUXE_RUNTIME_DIR` | Where a running Luxe keeps the socket and record that let a program join it, instead of `luxe` in `$XDG_RUNTIME_DIR` on Linux or `$TMPDIR` on macOS, or `run` in the state folder |
|
||||
|
||||
## Diagnostics
|
||||
|
||||
|
||||
@@ -25,6 +25,7 @@ guide is reference, for when you need it.
|
||||
| Resume a session, or see what fills the context | [Sessions and context](sessions.md) |
|
||||
| See what the agent can use | [Tools](tools.md) |
|
||||
| Let the agent work through a plan on its own | [Autonomous runs](loop.md) |
|
||||
| Reach your sessions from your phone or tablet | [Luxe on your phone](remote.md) |
|
||||
| Change the theme, keys or statusline | [Configuration](configuration.md) |
|
||||
| Give the agent your project's conventions | [Project context](project-context.md) |
|
||||
| Add tools, skills or your own commands | [Extending Luxe](extending.md), [Recipes](recipes.md) |
|
||||
|
||||
@@ -113,7 +113,8 @@ While the agent works, you can keep typing:
|
||||
| `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 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`.
|
||||
@@ -144,7 +145,7 @@ conversation, or in its place below 80 columns.
|
||||
| **FILES** | The project as a tree, with what changed marked in it. Click a file to [preview](#preview) it. |
|
||||
| **ELSEWHERE** | Files the session changed outside the project, when there are any |
|
||||
| **MODEL** | The provider, model, thinking level and [mode](agent.md#plan-then-build). 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. |
|
||||
| **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](remote.md), 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:
|
||||
|
||||
|
||||
@@ -28,6 +28,15 @@ session repeats that same text, which is what lets the provider reuse its cache.
|
||||
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.
|
||||
|
||||
### Folders the agent works in
|
||||
|
||||
An `AGENTS.md` in a folder below the repository's top, but not on the way to where you started,
|
||||
joins when the agent first opens, writes or searches a path in that folder. It's added to that
|
||||
tool result, once, and Luxe shows **Following** and the file's path. The system prompt doesn't
|
||||
change, so the cache holds. Ignored folders, such as `node_modules`, are skipped. If a rewind or a
|
||||
compaction drops the file, it joins again the next time the agent goes there.
|
||||
`LUXE_NESTED_INSTRUCTIONS=0` turns this off.
|
||||
|
||||
**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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Recipes"
|
||||
summary: "Extensions put together: Asana, subagents, a classifier guard, Herdr, and a local model."
|
||||
summary: "Extensions put together: Asana, subagents, a classifier guard, Herdr, your phone, and a local model."
|
||||
order: 8
|
||||
group: "Extend"
|
||||
---
|
||||
@@ -246,6 +246,60 @@ The one token worth a second thought is `panel_bg`: Herdr draws the active tab a
|
||||
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.
|
||||
|
||||
## Luxe from your phone
|
||||
|
||||
Your sessions keep running on your computer, and your phone or tablet reaches them over
|
||||
[Tailscale](https://tailscale.com), a private network between your own devices. Nothing is opened to
|
||||
the internet. This is the terminal over SSH; [Luxe on your phone](remote.md) is Luxe's own way in.
|
||||
|
||||
1. Install Tailscale on the computer and on the phone, and sign in to the same account on both.
|
||||
2. On the computer, turn on SSH. On Linux and macOS, Tailscale can do it for you:
|
||||
|
||||
```bash
|
||||
sudo tailscale up --ssh
|
||||
```
|
||||
|
||||
On Windows, turn on the OpenSSH Server in Settings, under Optional features.
|
||||
3. Run Luxe in [Herdr](#run-luxe-in-herdr), so your sessions outlive the terminal you started
|
||||
them in.
|
||||
4. On the phone, connect with an SSH app such as Blink Shell or Termius, using the computer's
|
||||
Tailscale name, and run `herdr`. It attaches to the panes you left, with Luxe where it was.
|
||||
|
||||
```bash
|
||||
mosh you@desk -- herdr
|
||||
```
|
||||
|
||||
[Mosh](https://mosh.org) keeps the connection through a locked screen or a switch from Wi-Fi to
|
||||
cellular. It needs `mosh` installed on the computer too, which Linux and macOS have and Windows
|
||||
does not; plain `ssh` works everywhere.
|
||||
|
||||
On an iPad with a keyboard, this is Luxe as you know it. On a phone, Luxe fits a narrow screen,
|
||||
and Herdr marks which session is waiting on you.
|
||||
|
||||
### A notification when Luxe needs you
|
||||
|
||||
[Luxe on your phone](remote.md#notifications) has notifications built in. Without it, a
|
||||
[hook](hooks.md) can post to [ntfy](https://ntfy.sh), whose app shows it on your phone:
|
||||
|
||||
```json title="~/.config/luxe/hooks.json"
|
||||
{
|
||||
"PermissionRequested": [
|
||||
{ "command": ["curl", "-s", "-d", "Luxe is waiting for an approval", "https://ntfy.sh/your-topic"] }
|
||||
],
|
||||
"BeforeToolUse": [
|
||||
{ "matcher": "question", "command": ["curl", "-s", "-d", "Luxe has a question", "https://ntfy.sh/your-topic"] }
|
||||
],
|
||||
"AgentEnd": [
|
||||
{ "command": ["curl", "-s", "-d", "Luxe finished", "https://ntfy.sh/your-topic"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **Anyone who knows an ntfy.sh topic can read it**, so pick a long random name, or run ntfy
|
||||
yourself on your Tailscale network. The messages above say only that something is waiting, never
|
||||
the command.
|
||||
- **`AgentEnd` fires after every turn**, at your desk too. Leave it out if that is too many.
|
||||
|
||||
## A local model in LM Studio
|
||||
|
||||
1. Load a model in LM Studio and start its server.
|
||||
|
||||
200
docs/guide/remote.md
Normal file
200
docs/guide/remote.md
Normal file
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: "Luxe on your phone"
|
||||
summary: "Reach the sessions running on your computer from your own phone or tablet, over Tailscale."
|
||||
order: 13
|
||||
group: "Using Luxe"
|
||||
---
|
||||
|
||||
`luxe remote` lets your phone or tablet see the sessions running on your computer, join one, and
|
||||
start new ones. It listens on your computer only. [Tailscale](https://tailscale.com), a private
|
||||
network between your own devices, carries it to them over HTTPS, so nothing is opened to the
|
||||
internet and there is no Luxe server in between.
|
||||
|
||||
On the phone it's an app in the browser, drawn like the interface in your theme. For the whole
|
||||
terminal, editor included, [Luxe from your phone](recipes.md#luxe-from-your-phone) works over SSH.
|
||||
|
||||
## Set it up
|
||||
|
||||
1. Install Tailscale on the computer and on the phone, and sign in to the same account on both.
|
||||
2. On the computer, run:
|
||||
|
||||
```bash
|
||||
luxe remote setup
|
||||
```
|
||||
|
||||
3. Scan the QR code it shows with the phone's camera, and give the device a name.
|
||||
4. On an iPhone or iPad, add it to the Home Screen: in Safari, Share, then Add to Home Screen. It
|
||||
opens full screen with the Luxe mark as its icon, and keeps the sign-in Safari had when you
|
||||
added it. An app added before pairing asks for the invitation link instead: copy it from
|
||||
`luxe remote pair` and paste it in.
|
||||
|
||||
Setup takes four steps, and asks before each one that changes something outside Luxe:
|
||||
|
||||
| Step | Does |
|
||||
| --- | --- |
|
||||
| Tailscale | Checks it is installed and signed in, and stops here if not |
|
||||
| Serve | Publishes the bridge at `https://<computer>.<tailnet>.ts.net/` with Tailscale Serve, for your tailnet only. One that already leads somewhere else is left alone. |
|
||||
| Service | Runs the bridge whenever you're signed in to the computer |
|
||||
| Pairing | Shows a QR code for one device |
|
||||
|
||||
A step that's already done says so and moves on, so running setup again is how to check it. On
|
||||
Linux, Serve may say access was denied; let your account manage Tailscale once, then run setup
|
||||
again:
|
||||
|
||||
```bash
|
||||
sudo tailscale set --operator=$USER
|
||||
```
|
||||
|
||||
The service is your own, and needs no administrator:
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Linux | A systemd user unit, `~/.config/systemd/user/luxe-remote.service` |
|
||||
| macOS | A launch agent, `~/Library/LaunchAgents/dev.luxe.remote.plist` |
|
||||
| Windows | `Luxe remote` under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` |
|
||||
|
||||
Without it, run `luxe remote` in a terminal, and your devices reach Luxe while it runs.
|
||||
|
||||
## Devices
|
||||
|
||||
```bash
|
||||
luxe remote pair # a QR code and link for one more device
|
||||
luxe remote devices # the paired ones
|
||||
luxe remote devices revoke a41c9e02 # unpair one
|
||||
```
|
||||
|
||||
An invitation pairs one device, within ten minutes. Revoking a device disconnects it within a few
|
||||
seconds; the sessions it had open carry on.
|
||||
|
||||
Only your own Tailscale login gets in. To let someone else on your tailnet in too, name them when
|
||||
you set up, and send them an invitation from `luxe remote pair`:
|
||||
|
||||
```bash
|
||||
luxe remote service remove
|
||||
luxe remote setup --allow sam@github
|
||||
```
|
||||
|
||||
## Two or more computers
|
||||
|
||||
Each computer runs its own bridge at its own address, so one phone can reach several: set each up
|
||||
as above, with Tailscale signed in to the same account, and pair the phone with each. Every one is
|
||||
its own app on the Home Screen, named for the computer as Tailscale names it (`desk` for
|
||||
`desk.tail1234.ts.net`), with the name beside the Luxe mark in its session list and after the
|
||||
project in its notifications, "luxe · desk". Luxe finds Tailscale by the `tailscale` command, so
|
||||
on a Mac check that `tailscale version` works in Terminal before running setup.
|
||||
|
||||
## What your device sees
|
||||
|
||||
Every Luxe running on the computer as you: the interface, `luxe --rpc`, and any started from your
|
||||
device. A device that joins a session is a guest, as in [joining a
|
||||
session](rpc.md#join-a-running-session): it sees the conversation so far and every live event, and
|
||||
can answer prompts and send messages. It can't switch or end the session, or publish to GitHub.
|
||||
|
||||
In a session, the app can:
|
||||
|
||||
- Name the session's folder and branch in the header, starred when the tree has changes.
|
||||
- Show the conversation as the interface draws it: markdown, highlighted code, tool cards. A long
|
||||
one opens on its latest 300 items, and **Show earlier** at the top brings 300 more at a time.
|
||||
- Send a message, with photos from the camera or library, and steer or stop a running turn. While
|
||||
one runs, a line over the message box says what sending will do: steer it at the next step, or
|
||||
wait for the turn to end when a photo is attached.
|
||||
- Run `/compact`, `/cost`, `/dock`, `/mode`, `/model` and `/thinking`, offered as you type a `/`. The
|
||||
interface's other commands work its own screen, so a message that starts with one goes to the
|
||||
agent as written.
|
||||
- Mention a project file: type `@` and pick from the project's folders, a level at a time. A picked
|
||||
file goes in as its path, which is what the interface sends the model for one.
|
||||
- Answer permission prompts and questions. As in the interface, every answer but Reject waits a
|
||||
moment after a prompt appears, so a stray tap can't grant anything.
|
||||
- Switch the mode with a tap on the status line, which also shows the context, thinking level and
|
||||
model. Tap those for the session's details: switch the mode, the thinking level or the model
|
||||
(from the same list as `/model`, with the levels each model honors), and see the cost.
|
||||
- Show [the dock](interface.md#the-dock), with the plan and the changed files. On an iPad or an
|
||||
open iPhone Duo it's a rail beside the conversation: the header's dock button or `/dock` shows
|
||||
and hides it, `/dock left` or `/dock right` moves it, and it starts from your `dock.mode` and
|
||||
`dock.position` [settings](configuration.md), as the interface does. On a phone the header has
|
||||
one menu button, and the dock is the first tab of the panel it opens; `/dock` opens it there
|
||||
too. A long plan scrolls in a box of its own that keeps the work in hand in view, until you
|
||||
scroll it yourself. Tap a file for its diff.
|
||||
- Browse the project's files from the header's menu button, in the interface's FILES tree, and
|
||||
read a file highlighted as the interface shows it. **Mention** adds its path to your message.
|
||||
On an iPad or an open iPhone Duo the tree is a rail and a file opens beside it; on a screen wide
|
||||
enough the conversation stays in view too.
|
||||
- Ask about particular lines of a file, a diff or a review chapter, as you would in the interface's
|
||||
File view: tap a line's number to pick it and another to stretch the pick, or select text the
|
||||
phone's usual way, down to part of a line, and tap **Ask** for the lines it covers. Your message
|
||||
gets the path and lines the interface would send. Tap anywhere else to let a pick go, and copy a
|
||||
selection with the phone's own menu. In a diff, a removed line can't be picked, since the file
|
||||
no longer has it.
|
||||
- Read the project's pull requests and issues in the same panel's GitHub tab, by the sections
|
||||
[`/github`](github.md) shows. Tap one for its overview (what stands between it and merged, or
|
||||
who's on an issue) and its conversation. **Mention** adds it to your message. It only reads: a
|
||||
joined session runs with GitHub writes off, so merging, replying and resolving stay in the
|
||||
interface.
|
||||
- Walk the open [Guided Review](guided-review.md) in the Review tab: the guide's summary and
|
||||
chapters, each one opened beside it with the guide's notes over its diffs. **Reviewed** marks a
|
||||
chapter read, the same progress `/review` keeps, and **Next** opens the one after. The phone
|
||||
joins the review the interface has open rather than starting its own, since a session holds one;
|
||||
with none open, **Review changes** reviews the working changes.
|
||||
- Comment on a review chapter: pick a line, or a run of lines, and tap **Comment**, or tap
|
||||
**Comment on the chapter** with nothing picked. Make it a question if you want an answer rather
|
||||
than a fix, then **Save** it to send later or **Send** it now. Each comment shows under what it's
|
||||
about with the agent's replies, and can be replied to, resolved, or, unsent, sent or deleted.
|
||||
The guide counts what's unsent and sends it all. Comments made in the interface show up too.
|
||||
Editing a comment, re-anchoring one the code moved away from, and commenting on a removed line
|
||||
are the interface's.
|
||||
|
||||
The interface says which device joined, "iPhone joined this session", and which one answered a
|
||||
prompt, "Approved from iPhone". A session with [`joinable`](configuration.md#joining-a-session) set
|
||||
to `false` is out of reach, from your device too.
|
||||
|
||||
## Starting a session
|
||||
|
||||
Tap **New** on the session list to start Luxe in a folder: one where Luxe is running now, one with
|
||||
a [herdr](recipes.md#run-luxe-in-herdr) pane, one where the bridge has seen Luxe run, or any path
|
||||
you type. What you type narrows the folders it offers, by name and then by path. They're only the
|
||||
ones above: it never looks through your home folder.
|
||||
|
||||
**herdr is optional, and recommended.** You don't need it to reach your sessions; it decides what
|
||||
happens to the ones you start away from your desk:
|
||||
|
||||
- **With herdr running**, the bridge opens a herdr pane in that folder, in the workspace already
|
||||
there or a new one named after it. The session survives a restart of the bridge, and waits for
|
||||
you at your desk like any other pane.
|
||||
- **Without it**, the bridge runs `luxe --rpc` itself, and the session lasts as long as the bridge
|
||||
does. At your desk, `luxe --resume` on it is refused while the bridge has it, and says so.
|
||||
|
||||
The bridge uses herdr only when herdr's server is already running, and never starts it.
|
||||
|
||||
## Notifications
|
||||
|
||||
A device can hear when a session needs it: a prompt waiting on an answer, or a long turn finished.
|
||||
Turn them on under **Notifications** in the app's session list. On an iPhone or iPad the app has to
|
||||
be on your Home Screen first (in Safari, Share, then Add to Home Screen), and paired from there, since
|
||||
the Home Screen app keeps its own sign-in.
|
||||
|
||||
A notification says what's waiting and where, "Approve bash" over `my-app`, never the command, and
|
||||
tapping it opens the session. Answering takes the app. So that one doesn't buzz you while you're
|
||||
at your desk:
|
||||
|
||||
- A prompt is held for ten seconds, and one answered meanwhile is never sent.
|
||||
- A finished turn is news only after a turn of thirty seconds or more.
|
||||
- A device with that session open on screen isn't told about it.
|
||||
|
||||
While any device has notifications on, the bridge joins each running session to watch. It joins
|
||||
watch-only, so the interface doesn't announce it and it can't act in the session.
|
||||
[Security](security.md#luxe-remote) covers what a notification carries and where it goes.
|
||||
|
||||
## Turn it off
|
||||
|
||||
```bash
|
||||
luxe remote service remove
|
||||
tailscale serve --https=443 off
|
||||
```
|
||||
|
||||
The first stops the bridge and stops it starting at sign-in; the second takes the address off
|
||||
your tailnet. Your paired devices stay paired until you revoke them, in case you set it up again.
|
||||
|
||||
## How it's kept to you
|
||||
|
||||
Every request needs your Tailscale login, which only Tailscale Serve can vouch for, and every
|
||||
session needs a paired device as well. [Security](security.md#luxe-remote) has the details.
|
||||
@@ -15,8 +15,8 @@ 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.
|
||||
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
|
||||
|
||||
@@ -24,6 +24,7 @@ Luxe.
|
||||
→ {"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":"turn_started"}
|
||||
→ {"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,…}}
|
||||
@@ -73,6 +74,43 @@ for line in luxe.stdout:
|
||||
Three rules make a working client: read `ready` first, answer both kinds of prompt, and ignore
|
||||
what you do not recognize.
|
||||
|
||||
## Join a running session
|
||||
|
||||
A session open in the interface can be joined while you keep using it, and so can one a `luxe --rpc`
|
||||
client started. `luxe join` connects to it and speaks this protocol on stdin and stdout, so the
|
||||
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
|
||||
```
|
||||
|
||||
After `ready` comes the session so far: `session_loaded` with the transcript, the latest
|
||||
`state_changed`, `session_usage` and `workspace_updated`, a `tool_activity_updated` for each call
|
||||
of a turn in flight, and any `permission_requested` or `question_asked` still waiting. Then the
|
||||
live events, the same ones the interface gets.
|
||||
|
||||
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.
|
||||
- **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.
|
||||
|
||||
The interface lists who's joined in its dock, and says in the conversation when a client joins or
|
||||
leaves, by the name it gives in `introduce` if it sends one within a second of connecting, or by
|
||||
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),
|
||||
`<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`.
|
||||
|
||||
## Actions
|
||||
|
||||
| `kind` | `content` | Does |
|
||||
@@ -88,6 +126,7 @@ what you do not recognize.
|
||||
| `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 |
|
||||
| `list_models` | `{"request_id": "…"}` | The models you can switch to, configured ones first, each with the thinking levels it honors; answered by `models_listed`, to you alone |
|
||||
| `set_thinking_level` | `"high"` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `ultra` |
|
||||
| `set_mode` | `"plan"` | `build` or `plan`; see [Plan, then build](agent.md#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](agent.md#a-second-opinion) on the uncommitted changes; answered by `review_started`, then `review_finished` |
|
||||
@@ -101,6 +140,7 @@ what you do not recognize.
|
||||
| `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. |
|
||||
| `close` | | Shut down, stopping a turn in flight the way `cancel` does. The stream ends after it. |
|
||||
|
||||
### Guided Review
|
||||
@@ -110,6 +150,9 @@ carries the whole review (its `id`, `revision_id`, files, hunks and chapters), a
|
||||
`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.
|
||||
|
||||
A session has one open review, and every load makes a new one, so a second client that loads its
|
||||
own replaces the review the first is reading. To join it instead, send `show_open_review`.
|
||||
|
||||
```text
|
||||
← {"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":"…",…}}}
|
||||
@@ -148,6 +191,7 @@ the comment stays `open`.
|
||||
| `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 |
|
||||
| `show_open_review` | `{"request_id"}` | Ask for the review open now, whoever opened it, answered by `open_review_shown` |
|
||||
| `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` |
|
||||
@@ -220,6 +264,7 @@ There are around sixty. These are the ones a front end is built on:
|
||||
| `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_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 |
|
||||
| `state_changed` | Model, thinking level, mode, and whether a turn is running |
|
||||
@@ -229,8 +274,10 @@ There are around sixty. These are the ones a front end is built on:
|
||||
| `context_usage`, `context_composition` | How full the context window is, and with what |
|
||||
| `compaction_started`, `compaction_done`, `compaction_stopped` | A summary of the conversation is being written, on request or mid-turn. It can take a minute. It always ends in `compaction_done` (with `tokens_after`) or `compaction_stopped` (failed or cancelled). |
|
||||
| `workspace_updated` | The project, Git changes, todos and tools: what the dock shows |
|
||||
| `prompt_closed` | A prompt stopped waiting, answered here or by another client, or cancelled. Take it down by `id`. |
|
||||
| `session_loaded`, `sessions_refreshed` | A transcript was restored; the session list changed |
|
||||
| `notice`, `error` | Something to show. `error` ends the turn. |
|
||||
| `guests_changed` | The names of the clients joined now, sent to the interface as one joins or leaves, for its dock. |
|
||||
| `action_rejected` | Your frame was refused and nothing happened |
|
||||
|
||||
Guided Review, as the interface sees it:
|
||||
@@ -240,6 +287,7 @@ Guided Review, as the interface sees it:
|
||||
| `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. |
|
||||
| `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_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 |
|
||||
@@ -247,6 +295,7 @@ Guided Review, as the interface sees it:
|
||||
| `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` |
|
||||
| `models_listed` | The models for `list_models`: each has `provider` and `model` for `select_model`, a `name` to show, and its `thinking_levels` |
|
||||
| `project_file_read`, `project_file_read_failed` | One file's text, for `read_project_file` |
|
||||
|
||||
GitHub:
|
||||
@@ -278,7 +327,9 @@ list is closed.
|
||||
|
||||
## Security
|
||||
|
||||
- Luxe listens on nothing; your client is the process that started it.
|
||||
- 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
|
||||
refused here as everywhere.
|
||||
- Prompts go to your client to answer. To approve everything, send `set_permission_auto_approve` or
|
||||
|
||||
@@ -144,6 +144,69 @@ or `"agent": { "on_ask": "deny" }` in `config.json`. A project can set `deny` bu
|
||||
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" }`.
|
||||
|
||||
## Joining a session
|
||||
|
||||
A session open in the interface can be [joined](rpc.md#join-a-running-session) by another program,
|
||||
which then sees the conversation and can answer its prompts. That makes who may join a security
|
||||
question:
|
||||
|
||||
- **Only your user account.** The socket sits in a folder only you can open, only you can use it,
|
||||
and Luxe checks the account of whatever connects. On Windows the named pipe admits your account
|
||||
alone, and refuses remote clients.
|
||||
Nothing listens on the network.
|
||||
- **Not the agent.** A program the agent started, at any depth, is turned away, so it can't
|
||||
approve its own prompts. Luxe checks the joining process's ancestry. It can't see past a program
|
||||
that detaches from its parent, such as one started with `setsid` and left running after its
|
||||
parent exits, so treat this as a tripwire, not a wall. A command that would do that should be
|
||||
something your rules ask about.
|
||||
- **A guest can't do everything.** A joined client can't switch or end the session, and can't
|
||||
publish to GitHub.
|
||||
|
||||
Anything running as you can already read your sessions on disk and your credentials, so joining
|
||||
adds a way to steer, not a way to read. To turn it off, set
|
||||
[`joinable`](configuration.md#joining-a-session) to `false`.
|
||||
|
||||
## Luxe remote
|
||||
|
||||
[`luxe remote`](remote.md) is the one part of Luxe that answers network requests, and it is off
|
||||
until you run it. It puts your sessions in reach of your phone, so it takes two things to get in:
|
||||
|
||||
- **Your Tailscale login.** The bridge listens on this machine only (`127.0.0.1`) and refuses to
|
||||
listen anywhere else. Tailscale Serve carries it to your tailnet over HTTPS and adds the login of
|
||||
whoever is asking, replacing any the request brought. A request without one didn't come through
|
||||
Serve and is refused, and so is a login other than yours or one you `--allow`. Luxe never uses
|
||||
Tailscale Funnel, which would publish it to the internet.
|
||||
- **A paired device.** Any program on this machine can reach a local port and claim a login, so
|
||||
every session also needs the credential a device gets when it pairs. An invitation works once,
|
||||
within ten minutes. Luxe keeps only a hash of each invitation and credential, in
|
||||
`~/.config/luxe/remote.json`. The device keeps its credential in a cookie scripts can't read,
|
||||
sent only over HTTPS and never with a request from another site; a request a page on another
|
||||
site makes is refused too.
|
||||
|
||||
Revoking a device disconnects it within a few seconds. A device joins a session as a guest, with
|
||||
the same limits as any [joined client](#joining-a-session), and the interface names it when it joins
|
||||
and when it answers a prompt. The name is the device's own label: whether a client may answer
|
||||
prompts at all is still decided by the process checks above.
|
||||
|
||||
Notifications are off until you turn them on in the app, one device at a time, and they never
|
||||
answer anything: a notification says what is waiting and where, such as "Approve bash" over the
|
||||
folder's name, never the command, and answering takes the app. While any device has them on, the
|
||||
bridge joins each running session to watch for prompts. It joins watch-only: the terminal doesn't
|
||||
announce it, and Luxe drops anything it sends, so a client nobody sees can't act. Each
|
||||
notification is sealed so only that device can read it (RFC 8291) and posted to the push service
|
||||
the device's browser picked; the push service sees when, not what. The bridge posts only to
|
||||
Apple's, Google's, Mozilla's and Microsoft's push services, so a paired device can't aim it at
|
||||
anything else on your network. It signs with a key of its own, kept in `remote.json`, and revoking
|
||||
a device ends its notifications.
|
||||
|
||||
The bridge starts Luxe only in a folder a device asks for, as you, in a herdr pane when herdr is
|
||||
already running and as its own `luxe --rpc` otherwise. A packager can build Luxe without the
|
||||
`remote` feature, which leaves out the bridge entirely.
|
||||
|
||||
A session is open in one Luxe at a time. A second `luxe --resume` of a session the interface
|
||||
already has, or a resume from the session list, is refused and says which process has it. The lock
|
||||
is the operating system's, so a crash never leaves a session stuck.
|
||||
|
||||
## Secrets
|
||||
|
||||
- Credentials are stored in `~/.config/luxe/auth.json`, readable only by you. Luxe warns if
|
||||
@@ -257,6 +320,9 @@ There is no telemetry. Luxe connects only to:
|
||||
5. GitHub, through your own `gh`, when you, the agent or an [RPC client](rpc.md#github-writes) work
|
||||
with pull requests and issues. A client can write there only if you start it with
|
||||
`--github-writes`.
|
||||
6. Your device's push service (Apple's, for an iPhone), when you turn on notifications in the
|
||||
[`luxe remote`](remote.md#notifications) app, sealed so only that device can read them
|
||||
(turning them off in the app stops it)
|
||||
|
||||
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.
|
||||
@@ -264,14 +330,22 @@ platform or identifier; it downloads a public file and compares versions locally
|
||||
One local report stays on your machine: inside a [herdr](configuration.md#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.
|
||||
And a running session takes connections on a local socket only you can open, so another program can
|
||||
[join it](#joining-a-session); `"joinable": false` stops that.
|
||||
|
||||
Apart from notifications, `luxe remote` sends nothing of its own. It answers your paired devices
|
||||
through Tailscale Serve and runs your own `tailscale` and `herdr` commands; see
|
||||
[Luxe remote](#luxe-remote).
|
||||
|
||||
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
|
||||
Luxe is written in Rust with `unsafe` code denied throughout, apart from a few small, reviewed
|
||||
modules that call the operating system directly. One starts each command in a session of its own,
|
||||
so nothing the agent runs can reach your terminal. On Windows, one keeps the programs Luxe starts
|
||||
off the stdin `--rpc` reads, one ends a command's whole process tree on a timeout, and one locks
|
||||
the [session pipe](#joining-a-session) to your account. CI checks
|
||||
every dependency's security advisories and license with `cargo-deny`, builds with `--locked`, and
|
||||
pins its GitHub Actions to exact commits.
|
||||
|
||||
Reference in New Issue
Block a user