yazelix

Yazelix Nova

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. Yazelix Forest provides the default managed Helix file tree, and the narrow Yazelix zj-radar fork provides the collapsible Zellij rail. Nova 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.

Preview

Nova vs Classic

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 component dependencies 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.

Install and launch

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 verified and dogfooded main revision, normally at least seven days apart. Urgent fixes may arrive sooner with the same verification. Channels share one linear history: stable ⊆ main ⊆ edge; promotions include every intervening commit. Use main for frequent updates or an immutable nova-v* tag for an exact release. edge is the opt-in experimental dogfood channel. See the promotion policy.

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.3 STABLE, NOVA 1.3 MAIN, or NOVA 1.3 EDGE, depending on the version and channel installed.

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.

Try without installing

nix run github:Yazelix/nova/stable -- launch
nix run github:Yazelix/nova/stable -- enter

If the one-off launch fails, inspect the owned runtime setup with:

nix run github:Yazelix/nova/stable -- doctor

Install in a Nix profile

nix profile add --refresh github:Yazelix/nova/stable
yzx launch

Install with Home Manager

Use the Home Manager module for a declarative install. The default example preserves Nova's locked dependencies; configure the binary cache to reuse published builds. Dependency overrides may require source builds.

Moving from Yazelix Classic

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 -- launch

If 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.

First five minutes

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 begin

yzx help lists every command. yzx doctor gives a compact, colored health summary without opening Rio or Zellij; yzx doctor --verbose expands diagnostic evidence, while yzx status owns paths and settings. Inside Yazelix, press Alt Shift M to open the command palette, including help, tutor and Radar agent-activity setup.

Doctor and status inspect without creating or repairing configuration, runtime files or plugin permissions. Missing runtime files are initialized by the existing launch/run commands; diagnostics report them without preparing a session.

Hold Ctrl to underline links and Ctrl-click to open them in Rio on Linux; use Cmd on macOS. This works inside Zellij as well as in a plain terminal.

Ratconfig

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.

Workspace keys

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 circularly	Move pane up circularly	Move tab right
Alt Shift	Sidebar	Git	Ratconfig	Agent

Yazi, the menu, and Anima use their initials:

• Alt Shift Y toggles the full Yazi popup.
• Alt Shift M toggles the command menu.
• Alt Shift A opens a transient random visual popup named anima. In animations, including Aquarium, Left/h/p selects previous and Right/l/n selects next; any other key exits. Static and logo exit on any key. Switching preserves the original welcome timer. This is not a session lock. Set keybindings.screen to remap or unmap it for newly launched sessions.

Run yzx anima aquarium for Anima's original pixel-art reef, with schooling fish, kelp, coral, bubbles, a ray, and a sand crab. Whale and shark visitors take turns crossing larger tanks during longer playback. Set welcome.style = "aquarium" to select it at startup. asciiquarium remains a compatibility alias in commands and welcome configs; it displays the native scene, not classic ASCII artwork.

Run yzx anima plasma for flowing color fields, yzx anima chladni for geometric nodal patterns, or yzx anima physarum for trail networks. All three work as welcome.style choices and through native previous/next browsing. Random selection includes all current native animations, including Aquarium; static and logo remain explicit-only choices. Native animations display fading name, credit, and navigation cards, with black backing confined inside the rounded border. Outside Nova, the standalone command is anima.

Press a popup's key again to close or hide it and return to the tiled workspace. Managed popups leave an open sidebar rail visible, resize in place when the sidebar toggles without restarting, and return to equal configured side margins when the sidebar is collapsed. Other floating panes keep running until explicitly shown again. Other useful bindings are:

Scope	Key	Action
Workspace	Ctrl q	Quit the Yazelix session
Workspace	Ctrl Alt t	Toggle tab mode; Ctrl t reaches the focused application
Workspace	Alt Shift T	Open a new workspace tab
Workspace	Alt Shift W	Close the active workspace tab
Workspace	Alt m	Open a new pane
Workspace	Alt j / Alt k	Focus the next / previous work pane, wrapping within the stack
Workspace	Alt Shift F	Toggle the focused pane fullscreen
Workspace	Alt Shift A	Show a random visual popup
Editor	Ctrl y	Toggle focus between Forest and the editor
Radar provider	Ctrl Alt n / Ctrl Alt p	Cycle attention tabs forward / backward
Radar provider	Ctrl Tab / Ctrl Shift Tab	Cycle sessions forward / backward
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

Every new tab starts with the configured sidebar and a focused quick zoxide search. Enter opens the selected directory; Tab switches to full Yazi, and Tab in that startup Yazi returns to quick search at the directory you reached. Both views show their controls in a local footer. Alt Shift T and Ctrl Alt t, then n, create tabs at your home directory; x in tab mode also closes a tab. The direct shortcuts pass through in locked mode. A session exits when its final terminal pane closes, so UI plugins cannot leave an empty tab without a focus anchor. A successful choice retargets the tab, creates the managed editor, then removes that exact picker. Exiting the picker without a successful handoff closes its exact tab; a surviving editor tab remains focused, while cancelling the only picker ends the session. Choosing a folder leaves Forest visible while focusing the native Helix picker. Alt Shift Y opens the separate persistent Yazi popup later.

The sidebar