Yazelix Nova is a Nix-packaged terminal workspace built around
Nova Rio, a minimal
Nova Zellij fork,
Yazi, Nushell, Bash, Zsh, and Fish with Atuin history, a lazygit popup (but you can configure other git clients!), and
an optional coding agent popup. It uses the
Nova Helix fork by default
(but editor.command can select your preferred terminal editor). yzx launch
opens the desktop workspace through Rio, while yzx enter opens Yazelix in any
capable terminal emulator or over SSH. Great defaults out of the box!
If Yazelix is useful to you, support its development on GitHub Sponsors.
TLDR: Nova v1.0.0 gives each component one job and delivers the full workspace in one quarter of Classic's code. This comparison stays fixed to that release.
Classic was bloated and built on the wrong ownership model. Its main repository acted as the product runtime, component control plane, configuration repair system, compatibility layer, and maintainer toolbox.
Classic's child repositories did not create firm boundaries. The main repo still carried their maintenance machinery and overlapping runtime logic. Nova gives first-party Yazelix components firm package boundaries. Each component owns its implementation and contract. Nova pins and composes their package outputs.
| Measure | Nova v1.0.0 | Classic |
|---|---|---|
| Code and configuration (Rust, Nix, shell, TOML, etc.) | 23,272 LOC | 91,545 LOC |
| Rust | 19,872 LOC | 80,957 LOC |
| Ownership model | One owner per concern | Overlapping responsibilities across layers |
| Yazelix component boundaries | Independent, versioned packages | Child repos mixed with main-repo ownership |
| Product experience | More features, stronger defaults, tighter integration, and polished UX | Fewer features and a less cohesive workspace |
| Status | Recommended | Frozen migration and rollback path |
Nova v1.0.0 owns 68,273 fewer lines, a 75% reduction. Classic's Rust code alone is 3.5 times larger than Nova's entire code and configuration surface.
Nova v1.0.0 delivers more features in 25% of the code. It has a clearer configuration model, tighter editor and Yazi integration, stronger diagnostics, and a coherent popup-oriented interface. The smaller architecture makes Yazelix easier to improve and better to use.
Classic proved the idea. Nova is the better product and the architecture Yazelix should have had from the start.
TLDR: Install Stable for the dogfooded release, Main for frequent updates, or Edge for experimental changes.
Yazelix requires Nix with flakes enabled. launch opens the packaged Rio window
in a graphical session, while enter starts the same workspace in the current
terminal or over SSH.
The stable branch advances from a checked
and dogfooded main revision at most once per week. Use main for more constant updates or an
immutable nova-v* tag for an exact release. edge is the opt-in experimental
dogfood channel.
Linux launchers show their selected channel as Yazelix Nova (Stable),
Yazelix Nova (Main), or Yazelix Nova (Edge). Stable uses the default
yazelix package; Main and Edge use the explicit yazelix-main and
yazelix-edge outputs so the immutable package owns its launcher label. The
same package identity remains visible inside sessions as NOVA 1.1 STABLE,
NOVA 1.1 MAIN, or NOVA 1.1 EDGE.
Linux is the dogfooded platform. CI builds all packages and a Home Manager
activation on aarch64-darwin. Sustained interactive macOS beta use has found
no known regression; the earlier per-command checklist and Rio GUI remain
unverified.
nix run github:Yazelix/nova/stable -- launch
nix run github:Yazelix/nova/stable -- enterIf the one-off launch fails, inspect the owned runtime setup with:
nix run github:Yazelix/nova/stable -- doctornix profile add --refresh github:Yazelix/nova/stable
yzx launchUse the Home Manager module for a declarative install.
Classic v17.12 translates mutable Classic settings.jsonc or config.toml
files into Nova configuration. It does not rewrite Home Manager declarations
or Home Manager-owned files. Run the bridge once when you need to preserve
mutable Classic settings:
nix run github:Yazelix/nova/v17.12#yazelix -- launchIf your Classic settings match packaged defaults, start with Nova's packaged
defaults and move straight to stable. Home Manager users must replace
Classic-only options with Nova's narrow module surface before switching.
After switching, yzx doctor reports recognized Classic configs/ and
sessions/ state, generated Nushell extern artifacts, and migration backups in
the active Yazelix roots. These are read-only warnings: nova=unused means Nova
did not load the path, while ownership=ambiguous means its contents or owner
cannot be proven from the pathname alone. Nova does not archive or remove the
reported paths, and external scripts may still reference them.
The Nova cutover intentionally replaces the old main history. Existing Git
clones should be replaced with a fresh clone rather than updated with an
ordinary pull. Classic remains available at the frozen classic branch, while
the immutable v17.12 tag remains the migration and rollback bridge.
TLDR: Start with yzx tutor begin, then use the Alt-based h/j/k/l grid to
move around the workspace.
Start the guided tour after launching Yazelix:
yzx tutor beginyzx help lists every command. yzx doctor checks the owned runtime setup
without opening Rio or Zellij. Inside Yazelix, press Alt Shift M to open the
command palette, which includes both help and tutor entries.
Press Alt Shift K to open Ratconfig:
| Key | Action |
|---|---|
1-9 |
Jump to a tab |
Tab / Shift-Tab, h / l |
Change tabs |
j / k, / |
Move through rows or search All settings |
a |
Switch between Overview and All when the tab has a meaningful reduced view |
e, Enter, Space |
Run the selected row's contextual action |
u, q |
Remove the selected explicit override or quit |
The footer lists the selected row's controls.
Yazelix extends Helix/Vim's h/j/k/l motion model into a workspace key grid.
The Alt and Ctrl Alt layers move focus, tabs, or panes, while Alt Shift
groups four workspace surfaces:
| Layer | h |
j |
k |
l |
|---|---|---|---|---|
Alt |
Focus left or previous tab | Focus down | Focus up | Focus right or next tab |
Ctrl Alt |
Move tab left | Move pane down | Move pane up | Move tab right |
Alt Shift |
Sidebar | Git | Ratconfig | Agent |
Yazi, the menu, and Anima use their initials:
Alt Shift Ytoggles the full Yazi popup.Alt Shift Mtoggles the command menu.Alt Shift Aopens a transient full-screen random visual. Press any ordinary screen input to return to the unchanged workspace; this is not a session lock. Setkeybindings.screento remap or unmap it for newly launched sessions.
Press a popup's key again to close or hide it and return to the tiled workspace. Other floating panes keep running until explicitly shown again. Other useful bindings are:
| Scope | Key | Action |
|---|---|---|
| Workspace | Ctrl q |
Quit the Yazelix session |
| Workspace | Alt m |
Open a new pane |
| Workspace | Alt Shift F |
Toggle the focused pane fullscreen |
| Workspace | Alt Shift A |
Show a random full-screen visual |
| Workspace | Ctrl y |
Toggle focus between the editor and Yazi sidebar |
| Workspace | Alt 1-9 |
Go directly to tab 1-9 |
| Editor / Yazi | Alt r |
Reveal in Yazi or return unchanged |
| Yazi | Alt z |
Retarget the tab workspace with zoxide |
If popup or Alt h / Alt l shortcuts briefly stop responding immediately
after switching sessions, use Alt 1-9 to select a tab, then retry. Native tab
selection recovers the observed intermittent state without restarting Yazelix.
Every managed keybindings.* setting accepts either a key chord or false.
Setting one to false removes only that shortcut on the next launch; commands,
menu entries, and popup behavior remain available through their other existing
entry points. Resetting the field in Ratconfig restores its packaged default.
Managed Helix supplies the editor binding. Terminal editors can bind the same
yzx reveal command; see Configuration
for Neovim and terminal Emacs examples.
Ratconfig's Keys tab is the complete packaged reference, and
defaults/zellij/config.kdl remains the runtime source.
| Command | Purpose |
|---|---|
yzx, yzx help |
Print command help |
yzx --version |
Print the exact package-owned Yazelix version |
yzx launch [zellij-args...] |
Open Rio first, then start managed Zellij |
yzx enter [zellij-args...] |
Start managed Zellij in the current terminal |
yzx run <program> [args...] |
Run exact argv inside the prepared Yazelix environment |
yzx config |
Open the Ratconfig-backed config UI |
yzx yazi-config materialize --user-config-dir <path> --state-dir <path> |
Materialize and print the effective Yazi config directory for automation |
yzx menu |
Open the command palette |
yzx doctor |
Check owned runtime setup without launching Rio or Zellij |
yzx status |
Print config/runtime paths and selected settings |
yzx status --json |
Print the versioned machine-readable status record |
yzx env |
Open the managed shell without launching the UI |
yzx tutor [lesson] |
Print guided Yazelix lessons |
yzx anima [style] |
Show a terminal animation with Anima |
yzx reveal <target> |
Start the persistent Yazi popup at a file or directory |
The materializer uses the selected Yazelix package's config and does not start Yazi or prepare the interactive runtime. See Runtime Notes for its output, validation, and exit-status contract.
TLDR: Create a named session when you want a workspace you can return to; attach when it is already running.
Yazelix delegates session lifecycle to packaged Zellij. Plain yzx enter and
yzx launch create independent sessions. Add --session NAME to create a
fresh named session:
yzx enter --session project
yzx launch --session projectUse attach NAME with the full name of a live session. Attach preserves its
tabs, panes, processes, working directories, and Yazi-to-Helix routes without
reapplying the managed layout:
yzx enter attach project
yzx launch attach projectA live-name collision during named creation fails instead of attaching. A missing attach target fails instead of creating a session.
Inside Yazelix, press Ctrl Alt o, then w to open Zellij's session manager.
Selecting a live session switches in place. Typing a missing name opens layout
selection with the Yazelix layout selected; press Enter to create it. Yazelix
supports immutable session names. Native rename and structural restore remain
outside the Nova v1 continuity contract.
Package names follow yazelix[-no-rio][-no-helix][-no-yazi]. Each suffix
removes that managed package while retaining the integration around it.
no-rio is terminal-free: yzx enter uses the current terminal, while
yzx launch explains that Rio is unavailable. It installs no Rio config,
icon, or desktop entry.
no-helix uses the configured host editor; no-yazi requires matching host
yazi and ya commands.
yazelix-main and yazelix-edge are full-package channel outputs with distinct
Linux launcher and in-session identities. They reuse the same dependency graph
as yazelix and do not multiply the capability-variant matrix.
| Package | Rio | Managed Helix | Managed Yazi |
|---|---|---|---|
yazelix |
Yes | Yes | Yes |
yazelix-no-helix |
Yes | No | Yes |
yazelix-no-yazi |
Yes | Yes | No |
yazelix-no-helix-no-yazi |
Yes | No | No |
yazelix-no-rio |
No | Yes | Yes |
yazelix-no-rio-no-helix |
No | No | Yes |
yazelix-no-rio-no-yazi |
No | Yes | No |
yazelix-no-rio-no-helix-no-yazi |
No | No | No |
See Installation and packages for package variants, platform support, SSH use, Home Manager, and updates.
Yazelix assembles focused first-party forks, plugins, libraries, and commands:
| Component | Yazelix role |
|---|---|
| Nova Rio | GUI terminal used by yzx launch; its isolated delta adds only the Rio fixes and launch-time theme override Nova still needs |
| Nova Zellij | Multiplexer fork based on upstream native Kitty graphics with managed runtime appearance switching and three-island status hints |
| Nova Helix | Steel-enabled editor fork with isolated configuration and explicit workspace bridge hooks |
| Zellij Pane Orchestrator | Zellij plugin that owns tab-local workspace roots and coordinates panes, focus, popups, the editor, and agent activity |
| Zellij Popup | Zellij plugin that opens, focuses, hides, and closes configured floating TUI panes |
| Nova Bar | Compact Nova top bar with tabs, modes, session details, status widgets, and activity markers, built on the narrow Yazelix zjstatus fork |
| Ratconfig | Reusable Ratatui configuration editor and TOML patching and migration library |
| Anima | Standalone terminal animations including Matrix rain, plus the separately packaged GPL aquarium exposed through yzx anima |
| Yazi Bistro | Curated complete Yazi flavors with pinned provenance, licenses, and explicit dark/light classification |
| auto-layout.yazi | Yazi plugin that changes the column layout to match the available pane width |
TLDR: Use yzx config for common settings; open a component's native file
when Ratconfig marks a value read-only.
yzx config opens Ratconfig over the managed tree at
~/.config/yazelix/. Yazelix inherits packaged defaults and persists only
explicit overrides. Overview combines recommended settings with every explicit,
invalid, externally managed, or diagnosed field. All includes complete owner
inventories where the owner publishes one, and the strongest honest curated or
observed inventory otherwise. Tabs whose Overview would hide fewer than three
fields or less than one quarter of their inventory simply show All.
Rio owns its complete native configuration at
~/.config/yazelix/rio/config.toml. Yazelix seeds that file once and Ratconfig
opens it as an exact native-file action; neither layer mirrors Rio's schema.
The one reserved field is top-level force-theme, which Nova projects from
root appearance.mode when the file is writable. Every other Rio setting stays
native and user-owned.
The packaged starting point uses a cyan cursor, Rio's native cursor trail, and
native nova-dark/nova-light adaptive themes. Files created by that seed
become user-owned apart from force-theme; existing theme files remain
untouched.
Legacy mars/config.toml and cursors.toml files are preserved but ignored.
The Yazi tab consumes the native presets and official schemas paired with the packaged Yazi version. Overview recommends ten common manager, preview, and flavor controls. All exposes 205 base settings plus the five exact native-file actions; search includes schema settings absent from both packaged and user TOML. Owner-validated booleans, choices, and unconstrained strings are editable. Numeric, structured, dynamic, and otherwise incompletely validated values open their native file instead.
Helix does not publish a machine-readable configuration catalog. Its tab
therefore exposes every packaged Nova Helix default and every value observed
in the sparse user config.toml or dynamic languages.toml, without claiming
that those rows are the complete Helix schema. Overview recommends eight common
or integration-owned values; All and search cover the remaining packaged or
explicit rows. Rows stay read-only with their exact native-file action because
TOML shape alone does not establish Helix validation or safe edit semantics. The
effective keys.normal.A-r row explains Yazelix's reserved reveal binding,
while the two Steel files remain native actions.
appearance.mode selects dark or light for managed Yazelix components and
also controls Ratconfig's palette. With a writable Rio config, Nova projects
the mode to force-theme and launches Rio without a theme override. Saving the
field from Ratconfig inside that managed session updates Rio through its native
config watcher while Ratconfig, Zellij, the bar, and new Yazi opens switch to
the same side. A custom complete Rio config must provide its own adaptive theme
pair to participate.
When the Rio config is read-only, including a store-backed Home Manager file, Nova passes the mode to Rio at launch and captures it for the session. Saving a different root mode does not switch any managed component in that session; the next session applies the saved mode everywhere together.
Zellij stores one dark theme and one light theme over its pinned packaged
inventory. Ratconfig inherits ansi and gruvbox-light, lets either field
retain a custom native name, and saves only explicit overrides. Legacy static
theme assignments remain in the user sidecar for recovery but are ignored by
the managed runtime. Yazelix passes root appearance at launch and Zellij
resolves the matching pair member. In a live-capable managed session, saving
root appearance calls Zellij's native action for that session. Zellij sends the
same mode to the top bar, which switches between its internal dark and light
palettes. Bars loaded by new tabs immediately inherit the session's current
mode, including after a live switch.
Each new managed Yazi reads the active session mode. Ratconfig offers separate
packaged dark and light flavor pools from Yazi Bistro; user-installed
unclassified flavors appear in both. default is the first dark choice and
uses Yazi's native preset by leaving flavor.dark unset. Light mode inherits
Bluloco Light. Explicit native flavor.dark and flavor.light selections
win. Yazelix projects the selected side into generated runtime config without
modifying the user or Home Manager theme.toml; already-running Yazi processes
stay as they are.
Set shell.program in Ratconfig or config.toml to choose packaged Nushell
(default), Bash, Zsh, or Fish for new panes and sessions.
Yazelix initializes Atuin local history and contextual Ctrl+r search for every
packaged shell while leaving Up-arrow with native history. Managed Nushell also
initializes Starship, Carapace completions, and zoxide. Set
shell.atuin = false to disable Nova's managed Atuin integration without
deleting either history store.
See Configuration for settings, popups, native files, Yazi plugins, Rio ownership, and editor behavior.
From a local checkout, use:
nix run .#yazelix -- launch
nix run .#yazelix -- enterSee Development for CI and local checks, Architecture for ownership boundaries, and Runtime Notes for launch and integration contracts.
Yazelisk is Yazelix's basilisk mascot: beautiful and deadly efficient. Friends call her Yaz.
Special thanks to soderluk for grinding with me through unstable periods of Yazelix, when things that should have worked did not. His reports helped shape Yazelix.
Special thanks to tag-und-nacht for detailed macOS, Home Manager, theming, and configuration reports that sharpened Yazelix's cross-platform support and user-config story.
Special thanks to TyceHerrman for thorough macOS and Nix packaging reports, including tested local workarounds and proposed fixes that hardened Yazelix's Darwin builds, child-repo release flow, runtime-tool sourcing, and bundled KGP package behavior.
Yazelix owns 26,394 lines of tracked text project files. The reproducible scorecard excludes Beads, lockfiles, and binary assets. This remains 1,111 lines below the pre-Rio fork surface. The current increase also records the terminal-free package matrix, exact Zellij v0.45.0 fork boundary, Yazi 26.8.15 runtime, native Nushell clipboard commands, portable Yazi PTY checks, the Anima mnemonic, and GitHub's native sponsor surface.