- 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.
11 KiB
11 KiB
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.
Commands
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.shwith 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 withwhile pgrep cargo. A slow run is compiling, not stuck: nextest kills tests over ~120s. luxeonPATHistarget/release/luxe, and onlyinstall-dev.shrebuilds 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, thensite-fonts.sh, or it shows as a box.
Architecture
- Dependencies point in, to
luxe-core.providers,tools,lsp,dap,mcp,remoteandtuimay usecore;climay use all of them.coreuses no workspace crate, andtuinever usesprovidersortools(go through core traits). coreis logic and traits: no UI, no HTTP, noreqwestorratatui. Spawning processes is fine. Network code lives inluxe-providers,luxe-tools' web tools,luxe-remoteandluxe-cli; its policy (likeluxe-core::update) stays in core.- A UI talks to core over channels only:
Actionin,Eventout. 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.rsnext tofoo/, neverfoo/mod.rs(exceptluxe-core/tests/common/).- Errors:
thiserrorenums in libraries,anyhowonly inluxe-cli. Nounwrap()orexpect()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_dropor its own process-group guard. Blocking work goes inspawn_blocking. - Logging is
tracing, with fields instead of formatted strings and secrets through the redaction layer.infois routine,debugis detail,warnis something odd the run handled,erroris 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.
pubmeans another crate uses it; everything else ispub(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.rsplus modules. coretests run headless: mock providers, temp dirs, no UI, no network.- An example's tests only run if its
[[example]]setstest = 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/*.jsonlline, a realghreply). 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 anArgs: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 IDonsession_id), no banners, no commented-out code. - Prose people read follows
docs/brand/voice.md. How the agent talks lives inluxe-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.envreads 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 justbash. - A project can't trust itself. Its
.luxe/permissions.jsononly tightens; its hooks,gate.commands, MCP and language servers need--trust-project(or globallsp.project_servers), so "always" approvals save globally.project_tooling_allowedis the one switch for project binaries; reuse it. Language servers still runbuild.rsand proc macros, so never say Luxe runs no repo code. - Secrets:
0600files,$ENVor!command, held insecrecy::SecretString, scrubbed from tool results, logs and wire captures byredact::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 remoteis the only server. It binds to loopback (Bridge::bindrefuses 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
mcptool, through the permission engine. Their descriptions and results are data, not instructions. luxe-core::instructionsstrips 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_onereturns a result for every call, a batch always commits (cut off, cancelled or failed too), andtool_pairing::repairfixes 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::scrubdrops empties from the outgoing copy, and an empty tool result is filled, never dropped. - Cancel with
Engine::set_cancelled.watch::Sender::senddoes nothing without subscribers, which is normal between turns. - Nothing the model runs is unbounded.
Tool::timeoutsets each deadline; dispatch drops the future at it or on cancel.Noneis 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 progressis a claim;ReviewIntegratorHookmoves 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::Usageafter the newest compaction.estimate_tokensis 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_tokenssteps. Watch the written share on/costand inluxe 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_LOGplusluxe wire). ActionandEventare a public protocol.luxe --rpcstreams them to clients built elsewhere, and an unknown tag becomesOther, so a rename breaks them silently. Adding is free; removing or renaming bumpsPROTOCOL_VERSION.tests/event_serialization.rspins the literals.
Product rules
AGENTS.mdis 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 fromscripts/site-record.sh. Change how Luxe looks and you owe asite-assets.shrun and a re-record.- The wordmark constants in
luxe-tui/src/widgets/wordmark/art.rsare the logo: one drawing, no alternatives.
Where things live
CONTRIBUTING.md: process, tooling, publishing.docs/guide/: the user guide, also inluxe docs..luxe/todos/<session-id>.json: thetodochecklist.- A dev checkout also has
PROJECT.md(what must stay true; read it when a design call is unclear),ROADMAP.md,PROGRESS.md,PLAN.mdand design notes. None of them ship.