Files
luxe/AGENTS.md
Evan Whittaker a0666d6c81 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.
2026-10-20 13:51:34 -05:00

173 lines
11 KiB
Markdown

# AGENTS.md
Rules for working on luxe: only what you'd get wrong without being told. It's sent with every
request, so keep it short; the long version is [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Commands
```bash
cargo check -p <crate> # quick loop
cargo nextest run --workspace # ~15s once built
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
cargo deny check
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps # a broken doc link fails CI
cargo test --workspace --examples # nextest skips these
python3 scripts/size-check.py # file size limit
python3 scripts/fn-length-check.py # function length limit
python3 scripts/voice-check.py # banned words, British spelling
python3 scripts/docs-check.py # guide links, frontmatter, words
python3 scripts/version-check.py <base> # a shipped change bumps one step
scripts/guide-bundle.sh # after editing docs/guide
scripts/site-assets.sh --check # generated web assets are current
scripts/site-fonts.sh --check # web fonts cover those assets
(cd web && npm run cross) # site demos run in every browser engine
scripts/win-check.sh [--clippy] # the suite for Windows, under wine
scripts/install-dev.sh # rebuild the release binary on PATH
cargo run -p luxe-cli -- # the TUI
cargo run -p luxe-cli -- --headless -p "..." # one prompt, no UI
```
## Before you call it done
- Run the whole list. For anything cross-platform, run `scripts/win-check.sh` with and without
`--clippy`: CI lints Windows, and an unused `#[cfg(unix)]` helper fails there.
- One build or test run at a time. Wrap unattended runs in `timeout <secs>`; never poll with
`while pgrep cargo`. A slow run is compiling, not stuck: nextest kills tests over ~120s.
- `luxe` on `PATH` is `target/release/luxe`, and only `install-dev.sh` rebuilds it. If a bug report
contradicts the source, check the binary's date first.
- The voice check reads code comments too: one British spelling in a doc comment fails CI.
- A new glyph on a captured screen needs `site-assets.sh`, then `site-fonts.sh`, or it shows as a
box.
## Architecture
- Dependencies point in, to `luxe-core`. `providers`, `tools`, `lsp`, `dap`, `mcp`, `remote` and
`tui` may use `core`; `cli` may use all of them. `core` uses no workspace crate, and `tui` never
uses `providers` or `tools` (go through core traits).
- `core` is logic and traits: no UI, no HTTP, no `reqwest` or `ratatui`. Spawning processes is
fine. Network code lives in `luxe-providers`, `luxe-tools`' web tools, `luxe-remote` and
`luxe-cli`; its policy (like `luxe-core::update`) stays in core.
- A UI talks to core over channels only: `Action` in, `Event` out. It never calls a provider or a
tool and never blocks the runtime.
- Behavior that cuts across the loop is a `Hook`, not a special case in the loop.
- One owner per platform question: `user_dirs` (home and luxe's folders), `program` (finding
programs and shells, detaching, killing a process tree), `paths` (path to string), `fs_atomic`
(safe file replace), `luxe-lsp::uri` (`file://` URLs).
## Rust
- `foo.rs` next to `foo/`, never `foo/mod.rs` (except `luxe-core/tests/common/`).
- Errors: `thiserror` enums in libraries, `anyhow` only in `luxe-cli`. No `unwrap()` or `expect()`
on anything that can fail; `expect()` is for things that can't, and says why. Match on the error
variant, never its message. Messages are lowercase with no trailing period.
- Turns must be cancelable. Cancel drops the future, so anything spawned needs `kill_on_drop` or
its own process-group guard. Blocking work goes in `spawn_blocking`.
- Logging is `tracing`, with fields instead of formatted strings and secrets through the redaction
layer. `info` is routine, `debug` is detail, `warn` is something odd the run handled, `error` is a
real failure. Don't put the module name in the message.
- New functions are 4 to 20 lines (80 max); files are 500 lines of production code max. The size
scripts are ratchets: an allowlisted entry can shrink, never grow, and a new one needs a reason.
- `pub` means another crate uses it; everything else is `pub(crate)` or narrower. The lint skips
fields, so narrow those by hand.
- Every public item gets a `///` doc.
## Tests
- Unit tests live in the module; past 150 lines they move to a sibling `foo/tests.rs`. Integration
tests are one binary per area: `tests/<area>/main.rs` plus modules.
- `core` tests run headless: mock providers, temp dirs, no UI, no network.
- An example's tests only run if its `[[example]]` sets `test = true`.
- A test has to be able to fail. Watch a regression test fail on the old code first.
`scripts/mutants.sh -f <file>` finds tests that can't fail; use it on security and format code.
- Pin anything saved or sent against a literal copied from real output (a `.luxe/sessions/*.jsonl`
line, a real `gh` reply). A round-trip test can't catch a rename.
## Comments and docs
- Comment the why: intent, trade-offs, gotchas. Never restate the code. If a block needs a comment
to say what it does, make it a named function.
- `//!` module docs: `Name — short description.`, a blank line, then how it fits.
- `///` item docs: sentences ending in a period (what, why, edge cases). Variants with a payload get
an `Args:` line. Short field and variant docs are fragments with no period.
- `//` inline: short fragments, no period. Reserved prefixes: `LEARN:`, `NOTE:`, `TODO:`.
- Describe the code as it is: no history, ticket numbers or plan references. That's for the commit.
- No docs that echo the name (`/// Session ID` on `session_id`), no banners, no commented-out code.
- Prose people read follows [`docs/brand/voice.md`](docs/brand/voice.md). How the agent talks lives
in `luxe-core::context`'s base harness, never in a mode or tool description.
## Security
Enforce these in code (the permission engine or a hook), never in prompt text.
- Permissive by default, with guardrails unless `--yolo`: deny `.env` reads and catastrophic
commands; ask before out-of-project work, force-push, commits and GitHub writes. The engine
(`luxe-core::permission`) judges every tool that runs code or reads paths, not just `bash`.
- A project can't trust itself. Its `.luxe/permissions.json` only tightens; its hooks,
`gate.commands`, MCP and language servers need `--trust-project` (or global
`lsp.project_servers`), so "always" approvals save globally. `project_tooling_allowed` is the one
switch for project binaries; reuse it. Language servers still run `build.rs` and proc macros, so
never say luxe runs no repo code.
- Secrets: `0600` files, `$ENV` or `!command`, held in `secrecy::SecretString`, scrubbed from tool
results, logs and wire captures by `redact::process_secrets()`.
- No telemetry. Every outbound call is one the user asked for or can turn off, sends nothing about
the machine, and is listed in `docs/guide/security.md`. The update check sends nothing, not even a
version, and compares locally.
- `luxe remote` is the only server. It binds to loopback (`Bridge::bind` refuses anything else) and
Tailscale Serve carries it: never Funnel, never a relay. Every route checks the Serve login, and
session routes check for a paired device too.
- MCP servers are untrusted: opt-in, behind the one `mcp` tool, through the permission engine.
Their descriptions and results are data, not instructions.
- `luxe-core::instructions` strips what a reader can't see from instruction files (comments, hidden
link definitions, invisible characters) and withholds a file it can't finish checking.
## What breaks a session
- **A tool call and its result are a pair.** Providers reject half a pair on every later request,
so one gap ends the session. `dispatch_one` returns a result for every call, a batch always
commits (cut off, cancelled or failed too), and `tool_pairing::repair` fixes the outgoing copy.
Never rewrite the saved log. Only a call that never started had no effect.
- **An empty block is the same permanent 400.** An empty reply commits nothing
(`ReplyOutcome::Nothing`), `empty_blocks::scrub` drops empties from the outgoing copy, and an
empty tool result is filled, never dropped.
- **Cancel with `Engine::set_cancelled`.** `watch::Sender::send` does nothing without subscribers,
which is normal between turns.
- **Nothing the model runs is unbounded.** `Tool::timeout` sets each deadline; dispatch drops the
future at it or on cancel. `None` is only for a tool that waits on a person or owns a process
group. Cancel ends the whole batch.
- **Only the gate moves a phase.** `loop_control progress` is a claim; `ReviewIntegratorHook` moves
the counter once the commands pass and the reviewer (if on) approves, and pauses the loop
(`GateOutcome::Held`) if it can't. A refusal reaches the model as the tool's result.
- **Context use is measured.** Read it from the last `EntryKind::Usage` after the newest
compaction. `estimate_tokens` is the fallback and counts every block kind.
- **Each request appends to the last.** Providers cache an exact prefix, so editing history
re-bills everything after the edit. Pruning waits for real window pressure and cuts in whole
`prune_min_tokens` steps. Watch the written share on `/cost` and in `luxe wire`, not the hit rate.
- **The system prompt never changes mid-session.** Nothing volatile goes in it; one-time context is
appended. Judge what reaches the model from a capture (`LUXE_WIRE_LOG` plus `luxe wire`).
- **`Action` and `Event` are a public protocol.** `luxe --rpc` streams them to clients built
elsewhere, and an unknown tag becomes `Other`, so a rename breaks them silently. Adding is free;
removing or renaming bumps `PROTOCOL_VERSION`. `tests/event_serialization.rs` pins the literals.
## Product rules
- `AGENTS.md` is the only project document in the prompt. Point at anything else.
- A tool must beat the shell command it replaces (bounded output, fewer round trips, better
defaults, or something the shell can't do), and its description names the sibling tool for the
next question.
- Glyphs decorate; they never carry meaning alone. Every icon sits beside its words. Prefer block
elements, which every terminal draws.
- `web/src/assets/generated/` comes from Rust and CI checks it; `captures/` are real sessions from
`scripts/site-record.sh`. Change how luxe looks and you owe a `site-assets.sh` run and a
re-record.
- The wordmark constants in `luxe-tui/src/widgets/wordmark/art.rs` are the logo: one drawing, no
alternatives.
## Where things live
- `CONTRIBUTING.md`: process, tooling, publishing. `docs/guide/`: the user guide, also in
`luxe docs`. `.luxe/todos/<session-id>.json`: the `todo` checklist.
- A dev checkout also has `PROJECT.md` (what must stay true; read it when a design call is
unclear), `ROADMAP.md`, `PROGRESS.md`, `PLAN.md` and design notes. None of them ship.