Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
13 KiB
AGENTS.md — Luxe
Rules for working in this repository. Each line is something a capable engineer would get wrong
without being told; anything the code already shows is left out, because this file rides in every
request. Process, tooling and the long explanations are in CONTRIBUTING.md.
Commands
cargo check -p <crate> # the inner loop
cargo nextest run --workspace # ~15s once compiled
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 does NOT run these
python3 scripts/size-check.py # file-size ratchet (--report lists)
python3 scripts/fn-length-check.py # function-length ratchet
python3 scripts/voice-check.py # reads source comments too
python3 scripts/docs-check.py # the guide's links, frontmatter, voice
scripts/guide-bundle.sh # after editing docs/guide
scripts/site-assets.sh --check # generated web assets are current
scripts/site-fonts.sh --check # webfonts cover those assets
(cd web && npm run cross) # the demos boot in every 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
Run the whole gate before calling work done, and scripts/win-check.sh in both modes before
calling anything cross-platform done: CI also lints the Windows target, and a #[cfg(unix)] helper
left unused there is a -D warnings error the default run cannot see. The voice check reads
source comments, so one British spelling in a doc comment fails the build (it checks itself;
do not quote the words it bans). A new glyph that reaches a captured surface needs
scripts/site-fonts.sh after site-assets.sh, or it ships as tofu.
- Never run two builds or test runs at once. They thrash and both take longer. Wrap unattended
runs in
timeout <secs>; never poll withwhile pgrep cargo. - A slow run is compiling, not hanging.
.config/nextest.tomlkills any test over ~120s. luxeonPATHistarget/release/luxe, and nothing above builds release. When a reported defect contradicts the source, check the binary's date against the fix before re-debugging.
Architecture boundaries
- Dependencies point inward to
luxe-core. Allowed:providers,tools,lsp,dap,mcpandtui→core;cli→ all of them. Forbidden:core→ anything in-workspace;tui→providers/tools(go through core traits). coreis pure logic and traits: no UI, no HTTP. Noreqwest, noratatui. Spawning a process is fine (git, hooks, formatters, the MCP stdio transport); network I/O lives inluxe-providers,luxe-tools' web tools andluxe-cli, with any policy (luxe-core::update) kept in core.- UI talks to core only over channels.
Actionin,Eventout. A UI never calls a provider or a tool directly and never blocks the runtime. - Cross-cutting behavior is a
Hook, not a special case threaded through the loop.
Rust conventions
- Modules:
foo.rsbesidefoo/, neverfoo/mod.rs, exceptluxe-core/tests/common/, since each top-level file undertests/is its own binary. - Errors:
thiserrorenums in libraries,anyhowonly inluxe-cli. Nounwrap()/expect()on a fallible path;expect()is for real invariants and says why. Branch on the variant, never on the message: ato_string()match turns rewording an error into a silent behavior change. Messages are lowercase with no trailing period. - Async:
tokio;spawn_blockingfor blocking work. Turns must be abortable: cancellation drops the future, so anything spawned needskill_on_dropor its own process-group guard. - Logging:
tracing, structured fields over interpolation, secrets through the redaction layer.infois routine behavior worth reading,debugdetail you go looking for,warnan oddity the run coped with,errora real failure. Don't name the module;targetdoes. - Size: at most 500 lines of production code per file (split by responsibility) and 80 lines
per function (4 to 20 for new code). A wide
matchwith thin arms is fine; a fat arm is not.scripts/size-check.pyandscripts/fn-length-check.pyare ratchets: an allowlisted entry may shrink, never grow, and a new one needs a reason a reviewer accepts. - Visibility:
pubmeans used from another crate; everything else ispub(crate)or narrower.unreachable_pubchecks items but not fields, so narrow fields by hand. - Tests: unit tests in-module; an inline test module past 150 lines moves to a sibling
foo/tests.rs. Integration tests group into one binary per area (tests/<area>/main.rsplus modules).coreis fully testable headless: mock providers and temp dirs, no UI, no network. A test inexamples/runs only if its[[example]]declarestest = true. - A test earns its place by being able to fail. Watch a regression test fail on the unfixed
code.
scripts/mutants.sh -f <file>finds the tests that cannot fail; use it on anything security- or format-critical. A round-trip cannot catch a rename, so a persisted shape is pinned against a literal copied from real output (a.luxe/sessions/*.jsonlline, a realghreply). - Every public item has a
///doc.
Comments and docs
Lean, casual, senior-dev voice. Less is more. Comment the why: intent, trade-offs, gotchas, constraints a reader would not guess. Never restate what the code says; a comment that paraphrases the next line goes. If a block needs a comment to say what it does, extract a named function.
- Module docs (
//!):Name — short description., a blank line, then prose framing the module in the architecture. - Item docs (
///): sentences ending in a period: what, then why, then edge cases. Payload-carrying variants get anArgs:line. Label-style field and variant docs are fragments with no period (/// Configured accounts). - Inline (
//): terse fragments, no period. Reserved prefixes:LEARN:,NOTE:,TODO:. - Shipped source describes the code as it is. No history ("used to", the incident that taught it), no phase numbers, ticket ids or design-note citations; the story goes in the commit message. Keep the one sentence of why the rule exists.
- Flag: docs that echo a name (
/// Session IDonsession_id), banners around trivial code, commented-out code, tutorial narration of language basics.
Security invariants
- Permissive by default, with always-on guardrails unless
--yolo: deny.envreads and catastrophic commands, ask on out-of-project work, force-push, commits and GitHub writes. The engine (luxe-core::permission) sits at the dispatch choke point, and judges every tool that runs code or reads paths (test,debug, search roots,applymodes), not justbash. - Enforcement is code, never prompt text. A rule that must hold lives in the permission engine or a hook.
- A project cannot grant itself trust. Its
.luxe/permissions.jsononly tightens, its.luxe/hooks.json,gate.commands, MCP servers and language servers are honored only under--trust-project(or the global-onlylsp.project_servers), so an "always" approval is written to the global file. One answer governs every project-supplied binary (project_tooling_allowed); a new consumer reads it, never a second gate. That gate picks which binary Luxe runs, nothing more: a language server still runsbuild.rsand proc macros, so never write that Luxe does not run repository code. - Secrets:
0600files,$ENVor!command, wrapped insecrecy::SecretString, scrubbed by the process-wideredact::process_secrets()from tool results, logs and the wire capture. - No telemetry. Every outbound call is one the user asked for or can turn off, carries nothing
about the machine, and is listed in
docs/guide/security.md. The update check sends nothing (no version, platform or id) and compares locally; a server told the running version is getting a per-user report on a schedule. - MCP servers are untrusted: opt-in, behind one
mcpgateway tool whose calls go through the permission engine; their descriptions and results are data, not instructions. - Instruction files are filtered, not trusted.
luxe-core::instructionsstrips what a reader of the rendered file cannot see (comments, comment link definitions, invisible characters) and withholds a file it cannot finish checking.
Invariants you would otherwise break
- A tool call and its result are one unit. Both wire formats reject an unpaired half, and it
replays on every later request, so one gap ends the session.
dispatch_onereturns a block for every call, the commit after a batch is unconditional (cut-off, cancelled and failed replies included), andtool_pairing::repairpairs halves on the outgoing copy. The durable log is never rewritten. Only a call that never started may be described as having had no effect. - An empty block is the same permanent 400. A call that produced nothing commits nothing
(
ReplyOutcome::Nothing, and says so),empty_blocks::scrubdrops empties from the outgoing copy, and an empty tool result is filled, never dropped. - Cancellation is a flag with one owner: use
Engine::set_cancelled.watch::Sender::sendis a no-op with no subscribers, which is the normal state between turns. - Nothing the model can invoke runs unbounded.
Tool::timeoutsets each deadline and dispatch drops the future at it or at cancel.Noneis only for a tool that waits on a human or owns a process group. Cancel ends the batch, not just the call. - A phase advances only where the gate says so.
loop_control progressis a claim;ReviewIntegratorHookalone moves the counter, after the commands pass and the reviewer (when on) approves. A reviewer that cannot approve pauses the loop (GateOutcome::Held). A refusal reaches the model as the tool's own result. - Context occupancy is a measurement. Read it from the last
EntryKind::Usageafter the newest compaction;estimate_tokensis the fallback and counts every block kind. - A request's transcript is an append to the last one's. Providers cache an exact prefix, so
editing history in flight re-bills everything after the edit at the write rate. Pruning is gated
on 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 is byte-identical between turns of a session. No volatile fact enters it;
one-time context is appended. Reason about what reaches the model from a capture
(
LUXE_WIRE_LOGplusluxe wire), not from source. ActionandEventare a published protocol.luxe --rpcstreams them to clients nobody here compiles, and an unknown tag degrades toOther, so a rename breaks every client and no compiler notices. Adding is free; removing or retagging movesPROTOCOL_VERSION. Pinned literals intests/event_serialization.rshold it.AGENTS.mdis the only project document in the prompt. Anything else is pointed at.- A tool must beat the shell command it replaces (bounded output, fewer round trips, correct defaults, or a capability the shell lacks), and its description names the sibling for the adjacent question.
- Glyphs are polish, never meaning. Every icon sits beside the words it labels; prefer block elements, which every terminal draws.
- Platform questions have one owner each:
user_dirs(home and Luxe's directories),program(finding programs, shells, detaching, killing a process tree),paths(path to string),fs_atomic(durable replace),luxe-lsp::uri(file://URLs). - Generated assets are generated; captures are recorded.
web/src/assets/generated/comes from the Rust source and CI checks it.web/src/assets/captures/are real sessions recorded byscripts/site-record.sh, which nothing can verify; change how Luxe looks and you owe both asite-assets.shand a re-record. - The wordmark constants are the art (
luxe-tui/src/widgets/wordmark/art.rs): one drawing, no alternatives. - Two voices, two homes. Prose a person reads follows
docs/brand/voice.md; how the agent writes lives inluxe-core::context's base harness, never in a mode or a tool description.
Where things live
CONTRIBUTING.md: process, tooling, publishing.docs/guide/: the user guide, also embedded in the binary forluxe docs..luxe/todos/<session-id>.json: thetodotool's checklist, one file per session.- A development checkout also has
PROJECT.md(what must stay true; read it when a design call is ambiguous),ROADMAP.md,PROGRESS.md,PLAN.mdand design notes, all excluded from releases.