AGENTS.md

Rules

• Applies repo-wide. Keep changes scoped; do not create issues or pull requests, or post comments.

Project

• Rust 2024 Cargo workspace containing all yazi-* crates; default members are yazi-fm (yazi) and yazi-cli (ya).

Style

• Follow nearby code and use idiomatic Rust and Lua. In Rust, treat directories as modules and files as types: always prefer mod_pub! for directory exports and mod_flat! for file exports. Keep mod.rs and lib.rs limited to exports; put module-wide implementation in a same-named file (for example, core/core.rs). Rust uses snake_case for modules, functions, and fields and PascalCase for types, traits, and variants. Lua uses PascalCase component tables, local M plugin modules, snake_case methods/locals, and _name private fields.
• Separate distinct responsibilities and processing stages with a single blank line, following nearby code. Group related statements together; use blank lines between preparation, validation, I/O, fallback, progress reporting, cleanup, and return values when they mark a distinct step. Keep this spacing when writing or simplifying code; the smallest implementation must still be readable.
• Preserve established terms and type families: Url/UrlBuf/UrlCow, PathDyn/PathBufDyn/PathCow, *Ref, *Arc, *Opt, *State, *Job, *Prog, File, Folder, Tab, Mgr, and Task. Use Url for logical locations and Path for filesystem paths.
• key() identifies a file-list entry; urn() is the raw URL path tail. Use key() for list state and urn() for filesystem-path semantics; do not substitute them mechanically.
• Reuse established plugin and event names (fetch, preload, peek, seek, spot, entry, setup, yank, hover, and select) across Rust, Lua, and configuration.
• Use Rust prefixes (as_, to_, into_, try_, is_, has_) according to their usual semantics; prefer descriptive names.
• Name variables, modules, methods, and other symbols simply, elegantly, and expressively. Be creative while keeping names clear, consistent with established terminology, and idiomatic. When equivalent names are available, align the name's natural default with the type's default; for booleans, prefer a name whose false value represents the common state (for example, seekless when handles normally support seeking), so Default and unwrap_or_default() do not need special initialization.
• When passing arguments, use the parameter's conversion traits directly (such as Into<_> or AsRef<_>); avoid eager conversions like .to_string(), .to_owned(), and .as_ref() unless ownership, type inference, or semantics require them. At Lua boundaries, prefer LuaString to String, use BorrowedBytes when string semantics are unnecessary, and return binding errors as (nil, error) alongside a value (or (false, error) for no-value operations); successful calls return (value, nil) or (true, nil). Reserve direct Err returns for invalid API usage that violates the call contract and can be handled with pcall.
• Let Rust infer types whenever the context is sufficient; when an annotation is needed, put it on the binding (let value: Type = ...) instead of turbofishing the expression.
• Prefer methods provided by UrlLike, PathLike, or StrandLike directly on the original value (for example, buf.parent() over buf.as_url().parent()), rather than converting it first with as_url(), dyn_path(), or to_strand().
• Prefer &*value for dereferencing over AsRef when both are suitable.
• Prefer general-purpose traits and conversion APIs already provided by the codebase or its dependencies over manual construction or adapter closures; for example, use into_lua() where applicable. Unless method resolution is genuinely ambiguous, call value.method() instead of Trait::method(value).

Code Changes

• Search and reuse first. Prefer established types, variants, helpers, and data structures over adding new wrappers or abstractions; introduce a new type only when it represents a genuinely distinct responsibility or invariant. For new features, extend existing infrastructure or data structures with general, reusable capabilities when that keeps the final code concise and the total type count small.
• Use gh to read GitHub issues, pull requests, and their discussions.
• For refactors, inspect the whole target module, its callers, and the surrounding lifecycle first. Understand the system's established assumptions before adding local safeguards; distinguish required invariants from acceptable compromises, and ask when that boundary materially affects the design. Look for duplicated work, redundant I/O, underpowered return values, one-use wrappers, and reusable cross-platform abstractions; implement high-confidence, behavior-preserving simplifications while preserving error, fallback, and platform semantics.
• Prefer the simplest design that satisfies the requirements. Keep diffs minimal and avoid overengineering, unrelated refactors, speculative abstractions, and defensive handling for states the system already excludes. When evaluating code size, count hand-maintained Rust, Lua, and similar source logic; do not treat imports or generated/tool-managed files such as Cargo.toml and Cargo.lock as business-code complexity. When conditions are mutually exclusive and have a clear priority, express them as flat, peer-level if/else if/else branches in that priority order; do not compress the state checks into compound predicates merely to deduplicate a small result body. Prefer clear, flat control flow, expressions, and positive predicates; use standard combinators, early returns, ordered branches, and match guards to avoid nested conditionals, compound negation, and unnecessary wrapper syntax. Treat small, deliberate repetition in branch results as a good trade-off when it makes the decision structure easier to understand. Prefer available convenience macros when they simplify the code. When idiomatic and equivalent, prefer visually parallel forms such as true as usize over usize::from(true). Comment only behavior the code cannot explain.
• Keep responsibility boundaries clear and cohesive. Prefer pure functions, explicit invariants, and idempotent operations when repeated calls are natural and idempotency removes coordination or state. Favor convention over configuration when invariants can eliminate state or coordination. Put reusable code in the lowest suitable shared layer; place business-independent adapters and wrappers that mainly compensate for a dependency's limitations in yazi-shim, and add that dependency there. Avoid unnecessary allocations. Prefer borrowed values and existing wrappers.
• Minimize total maintenance cost, not dependency count. Reuse suitable crates instead of hand-writing synchronization, resource cleanup, or platform adapters merely to avoid a dependency. A dependency already declared at workspace level may be used by any child crate as needed; adding it to a child crate is not a new workspace dependency. Evaluate new crates by the maintained code and correctness obligations they remove versus their integration, compatibility, security, and upkeep costs; add them when the overall trade-off is favorable.
• Initialize crates explicitly from the application entrypoint in dependency order; a module must not initialize another module as a side effect.
• Use stable Rust APIs; nightly is formatting-only—apply Rust formatting directly with rustfmt +nightly **/*.rs. Use only pub, pub(super), and pub(crate)—never pub(in ...).
• Keep async I/O non-blocking, preserve platform/fork behavior, and follow existing error boundaries with ?.
• For renames or refactors, update all related variables, functions, parameters, modules, methods, types, derived types, exports, tests, configuration keys, documentation, Lua bindings, and, when a type and file share a name, the file as well; do not preserve renamed terms through aliases or re-exports.
• When adding a changelog entry, leave the PR number blank for a human to fill in.
• Do not add tests or change test behavior unless requested.

Review and Simplification

• For a review or simplification pass, inspect the whole target module, its callers, and its surrounding lifecycle before drawing conclusions. Use two passes: first establish ownership, cancellation, error, and state invariants; then compare each custom mechanism with the standard library, existing dependencies, and nearby code.
• Check every task and channel for a simpler native primitive (for example, a JoinHandle that can replace a result-only oneshot), and check wrappers, helpers, flags, Option values, defaults, conversions, clones, and manual cleanup for the same opportunity. Include Drop, async boundaries, and cancellation in the comparison.
• Before concluding a simplification review, enumerate every credible candidate. Report which candidates were applied and which were retained, with the behavioral reason and approximate diff impact; do not report only the changes that were ultimately made.
• Keep only changes with a clear semantic or readability advantage, or a measurable reduction in maintained code. Include blank lines in source line counts, but do not remove useful spacing merely to reduce that count. Preserve behavior, error propagation, ownership, cancellation, and platform semantics when a shorter form would weaken them.

Validation

• Prefer targeted debug checks; use multiple -p flags for affected crates before the whole workspace.
• When investigating bugs, add temporary diagnostics when useful (tracing in Rust and ya.dbg in Lua), reproduce in a simulated terminal with YAZI_LOG=debug, and inspect the log file to pinpoint the cause. When debugging on a real terminal, use its IPC remote-control interface whenever supported. Remove temporary diagnostics before handoff.

cargo check -p <package>
cargo test -p <package>
cargo clippy -p <package>
rustfmt +nightly **/*.rs
stylua --color always --check .

• Use cargo check instead of cargo build unless artifacts are needed. Do not use --release unless requested; use scripts/build.sh <target> for release or cross-target packaging.
• Run relevant existing tests when needed, then inspect git diff and verify that only intended files changed.