How sxyazi/yazi works
1. This is a Rust monorepo for Yazi, a terminal file manager. The architecture is split into many small crates, with a clear separation between:
- the interactive TUI application,
- the core domain/state layer,
- async task execution,
- filesystem and virtual filesystem access,
- plugin/Lua runtime support,
- terminal/image rendering adapters,
- and packaging/build tooling.
2. The main executable is yazi-fm. It is the user-facing terminal app and acts as the composition root: it wires together input handling, routing/dispatch, rendering, notifications, task progress, and the manager/selection/preview views. The repo also includes yazi-cli for auxiliary commands and yazi-boot for startup/diagnostic actions, but yazi-fm is the center of runtime behavior.
3. The core application model lives in yazi-core. This crate holds the long-lived state and business logic for tabs, directory navigation, search/filtering, open actions, preview state, tasks, notifications, and “which/confirm/help/input” modal flows. It is the main boundary between UI events and domain operations: the TUI dispatches actions into core, and core emits updated state and side effects.
4. The filesystem layer is split across yazi-fs, yazi-vfs, and yazi-sftp.
- yazi-fs provides local path, metadata, sorting, mount, and provider abstractions.
- yazi-vfs generalizes filesystem access and adds remote/provider support, including SFTP-backed operations.
- yazi-sftp implements the SFTP protocol itself.
This separation lets the rest of the app treat local and remote files through similar interfaces while keeping protocol-specific logic isolated.
5. The async task pipeline is handled by yazi-scheduler and yazi-runner.
- yazi-scheduler coordinates jobs, progress, cancellation, transactions, and worker orchestration across file operations, processes, preloads, plugins, fetches, and sizing work.
- yazi-runner executes plugin-side jobs such as loaders, fetchers, previewers, and preloader tasks.
In diagram terms, these crates sit between core state and actual I/O/process work, absorbing concurrency and progress reporting.
6. The event/action translation layer is unusually explicit. There are generated or decomposed action crates such as yazi-parser, yazi-actor, and yazi-proxy.
- yazi-parser parses incoming action names/events into typed operations.
- yazi-actor groups action handlers by UI mode and domain area.
- yazi-proxy provides dispatch proxies for app submodules.
This suggests the app uses an internal action bus rather than tightly coupling UI events to state mutations.
7. The plugin and Lua subsystem is a major architectural boundary. yazi-plugin contains Lua presets and runtime support for UI plugins, previewers, spotters, fetchers, and other extension points. yazi-binding exposes Rust-side bindings and configuration models to Lua, while yazi-runner and yazi-scheduler execute plugin-related work. The plugin layer is how Yazi customizes UI rendering, previews, content detection, and user commands without embedding all logic in the Rust app.
8. The data distribution service (DDS) is implemented with yazi-dds. It provides a client/server pub-sub mechanism for cross-instance communication and state persistence, but it is embedded in the application model rather than requiring an external daemon. This subsystem is important for diagramming because it is a separate communication plane from the normal file-manager UI flow.
9. The UI/runtime support stack is layered:
- yazi-widgets contains reusable input and scrolling widgets.
- yazi-term and yazi-tty abstract terminal/TTY behavior.
- yazi-emulator models terminal capabilities/dimensions.
- yazi-adapter renders images through terminal-specific backends such as Kitty graphics, IIP, Sixel, Überzug++, or Chafa fallback.
This layer is responsible for presentation, terminal feature detection, and image preview output, while the app logic remains elsewhere.
10. The configuration and schema layer is centralized in yazi-config. It defines TOML-based presets for keymaps, theme, layout, open rules, previewers, fetchers, spotters, VFS settings, popup behavior, and platform-specific options. This crate is the main configuration boundary, translating user config into strongly typed runtime structures used by the app, plugins, and filesystem tooling.
11. The shared foundation crates provide reusable primitives across the whole repo:
- yazi-shared contains string/path/url/scheme/event/pool/time utilities and common data types.
- yazi-shim wraps third-party crates to stabilize APIs.
- yazi-binding provides rich domain types for files, handles, runtime, theme, input, and config.
These are infrastructure crates rather than features; they keep higher-level crates focused on behavior.
12. The platform and FFI surface is isolated in yazi-ffi and parts of yazi-shared/yazi-emulator. yazi-ffi contains macOS-specific system integrations such as disk arbitration and IOKit. This indicates the repo supports platform-native filesystem/media integration while maintaining a cross-platform core.
13. The build and packaging/tooling layer is also substantial:
- yazi-build, yazi-boot, yazi-codegen, and yazi-macro support code generation, build-time actions, and macro expansion.
- scripts, flake.nix, snap, and GitHub workflows handle release, validation, icon generation, packaging, and CI.
These do not affect runtime flows directly, but they are important boundaries for how the monorepo is assembled and distributed.
14. The main runtime data flow is: terminal input → TUI/router/dispatcher → core app state → scheduler/runner for async work → filesystem/VFS/plugin/DDS backends → updated state/progress/notifications → render back to terminal. Image previews and remote operations branch out through dedicated adapters/providers, but they rejoin the same core state and task progress pipeline.
Main entry points: yazi-core yazi-core · yazi-fm yazi-fm · yazi-plugin yazi-plugin · yazi-scheduler yazi-scheduler
Components 34
Runtime
User-facing executable and runtime coordination.
- yazi-fm · Composition root for the terminal file manager: input, routing, rendering, notifications, task progress, and views.
yazi-fm - Dispatcher · Translates parsed actions into app-side dispatch and execution flow.
yazi-fm/src/dispatcher.rs - Router · Routes terminal events and application commands to the active handler or mode.
yazi-fm/src/router.rs - Executor · Runs async/runtime work and bridges app requests to background execution.
yazi-fm/src/executor.rs
Core state
Long-lived app state, modes, and domain operations.
- yazi-core · Central application model for tabs, navigation, search, preview, tasks, and modal flows.
yazi-core - Manager · Core directory manager logic for browsing, selection, filtering, and file actions.
yazi-core/src/mgr/mgr.rs - Tab state · Tab history, folders, selection, preview locks, and tab-local preferences.
yazi-core/src/tab/tab.rs - Task state · Core task definitions and prework/process tracking used by scheduler and UI.
yazi-core/src/tasks/tasks.rs - Notify · Notification messages, levels, and options emitted across the app.
yazi-core/src/notify/notify.rs - Proxy · Shared proxy interface used to connect action dispatch to submodules.
yazi-core/src/proxy.rs
Filesystem
Local, virtual, and remote filesystem access.
- yazi-scheduler · Coordinates jobs, progress, cancellation, transactions, workers, and async orchestration.
yazi-scheduler - yazi-vfs · Unified filesystem abstraction spanning local and remote provider implementations.
yazi-vfs - yazi-fs · Local filesystem primitives for paths, metadata, sorting, mounts, and providers.
yazi-fs - yazi-sftp · SFTP protocol implementation used by remote filesystem providers.
yazi-sftp
Plugins
Lua runtime and plugin execution pipeline.
- yazi-runner · Executes plugin-side loaders, fetchers, previewers, and preloader tasks.
yazi-runner - yazi-plugin · Lua presets, runtime support, UI components, and plugin utilities.
yazi-plugin - yazi-binding · Rust-side binding layer exposing domain types, config models, and runtime data to Lua.
yazi-binding
Support
Terminal, rendering, config, and shared foundation crates.
- yazi-dds · Embedded data distribution service for cross-instance communication and state persistence.
yazi-dds - yazi-config · Typed TOML configuration and presets for keymaps, layout, themes, plugins, preview, and VFS.
yazi-config - yazi-widgets · Reusable input and scrolling widgets used by the terminal interface.
yazi-widgets - yazi-term · Terminal behavior and state abstraction.
yazi-term - yazi-tty · TTY handle and platform-specific terminal I/O wrapper.
yazi-tty - yazi-emulator · Terminal capability and dimension modeling for layout and rendering.
yazi-emulator - yazi-adapter · Terminal image rendering backends and driver selection for previews.
yazi-adapter - yazi-shared · Common utilities and data types for paths, events, pools, URLs, time, and other foundations.
yazi-shared - yazi-shim · Stable wrappers around third-party crates used across the monorepo.
yazi-shim - yazi-ffi · macOS-specific system integration such as disk arbitration and IOKit.
yazi-ffi - yazi-parser · Parses incoming action names and events into typed operations.
yazi-parser - yazi-actor · Grouped action handlers by mode and domain area for the application bus.
yazi-actor - yazi-proxy · Proxy functions that forward app actions to the right submodule boundary.
yazi-proxy
Tooling
Build, packaging, and auxiliary command crates.
- yazi-cli · Auxiliary commands for DDS and package operations.
yazi-cli - yazi-boot · Bootstrapping and diagnostics commands for startup and environment checks.
yazi-boot - yazi-build · Build-time crate for generating or orchestrating build steps.
yazi-build - yazi-codegen · Code generation helper crate used during build or generation workflows.
yazi-codegen
Connections 34
- yazi-fm → Dispatcher: dispatches · Application input is converted into internal actions and commands.
- yazi-fm → Router: routes · Terminal and application events are routed to the active mode or handler.
- yazi-fm → Executor: spawns · The app delegates async work and background execution to the runtime executor.
- yazi-fm → yazi-core: drives · UI events mutate core state and consume the resulting updates.
- yazi-fm → yazi-widgets: renders with · Interactive panels and inputs use reusable widget primitives.
- Dispatcher → yazi-parser: parses · Action names and event payloads are decoded into typed operations.
- Dispatcher → yazi-proxy: forwards · Parsed actions are forwarded through the proxy dispatch boundary.
- yazi-actor → yazi-core: mutates · Action handlers apply domain changes to core state.
- yazi-proxy → yazi-actor: dispatches · The proxy routes requests into the appropriate handler group.
- yazi-core → Manager: owns · Core manager logic owns navigation, selection, filtering, and file operations.
- yazi-core → Tab state: tracks · Tab-local state and history are maintained as part of the domain model.
- yazi-core → Task state: tracks · Task metadata and prework/process state are part of core state.
- yazi-core → Notify: emits · Notifications are modeled and emitted by the domain layer.
- yazi-core → yazi-scheduler: queues · Core state schedules file, process, plugin, and fetch work through the scheduler.
- yazi-scheduler → yazi-runner: executes · Scheduled plugin-related work is carried out by the runner.
- yazi-scheduler → yazi-vfs: orchestrates · Filesystem operations and remote provider work flow through the virtual filesystem boundary.
- yazi-vfs → yazi-fs: adapts · Virtual filesystem abstractions build on the local filesystem layer.
- yazi-vfs → yazi-sftp: speaks · Remote provider support is backed by SFTP protocol implementation.
- yazi-fs → yazi-sftp: delegates remote · Local abstractions stay separate from protocol-specific remote access.
- yazi-plugin → yazi-binding: uses · Lua runtime and presets consume the Rust-side binding and domain types.
- yazi-plugin → yazi-runner: runs on · Plugin loaders, fetchers, previewers, and preloaders execute through the runner.
- yazi-plugin → yazi-scheduler: requests work · Plugin work is coordinated as scheduled jobs with progress and cancellation.
- yazi-binding → yazi-config: reads · Binding models mirror typed configuration structures used at runtime.
- yazi-dds → yazi-cli: served by · The CLI interacts with DDS commands and package workflows.
- yazi-dds → yazi-core: syncs · Cross-instance state and events are integrated with the application model.
- yazi-config → yazi-plugin: configures · User presets define plugin components, previewers, fetchers, and spotters.
- yazi-config → yazi-vfs: configures · Configuration also covers VFS services and remote access behavior.
- yazi-term → yazi-tty: wraps · Terminal state sits on top of TTY handling.
- yazi-term → yazi-emulator: models · Terminal capabilities and dimensions are modeled for rendering and layout.
- yazi-adapter → yazi-emulator: targets · Image rendering backends adapt to terminal capabilities.
- yazi-adapter → yazi-term: renders to · Image output is emitted through the terminal layer.
- yazi-parser → yazi-actor: feeds · Typed actions feed grouped handlers.
- yazi-build → yazi-codegen: invokes · Build tooling includes code generation support.
- yazi-boot → yazi-cli: supports · Bootstrapping and diagnostic actions complement auxiliary commands.