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:
Evan Whittaker
2026-10-20 02:40:13 -05:00
parent 99e30d6d0f
commit d2129a886f
423 changed files with 31666 additions and 1669 deletions

View File

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