Yazelix Nova docs

Yazelix Nova is a Nix-packaged terminal workspace. Install it with Nix and flakes enabled, or without Nix on x86_64 Linux. This guide describes the audited Stable revision shown in the site footer. Main and Edge may carry later behavior.

Immutable nova-v* tags select exact releases. A Nix lock file keeps its selected revision until you update it.

Pick one path. Nix works on Linux and macOS and bundles Nova Rio. The installer needs no Nix but runs only on x86_64 Linux. On macOS and ARM Linux, use Nix.

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

yzx launch

yzx enter

curl -LsSf https://nova.yazelix.com/install | sh

curl -LsSfo install.sh https://nova.yazelix.com/install
sh install.sh

curl -LsSf https://nova.yazelix.com/install | sh -s -- --version 2.0.0

gh attestation verify yazelix-nova-2.0.0-x86_64-unknown-linux-gnu-no-rio.tar.gz --repo Yazelix/nova

Set a terminal profile to run yzx enter, or open the installed Linux desktop entry. Most days, you do not type another yzx command after Nova opens. Alt Shift K opens Ratconfig. The keybinding map covers the rest of the workspace.

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

Run the owned preflight without opening Rio or Zellij:

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

Plain yzx launch and yzx enter start independent sessions. Add --session NAME to create a fresh named session:

yzx enter --session project
yzx launch --session project

Attach to a live session by its full name:

yzx enter attach project
yzx launch attach project

Creation fails for a live name. Attachment fails for a missing name.

Inside Nova, press Ctrl Alt o, then w to open the session manager. Select a live session to switch, or type a missing name and press Enter with the Yazelix layout selected to create it.

After you switch sessions, popups or Alt h / Alt l may pause for several seconds. Press Alt 1-9 to select a tab, then retry. See Workspace keys for the session-manager chord.

Package names follow yazelix[-no-rio][-no-helix][-no-yazi]:

nix profile add --refresh github:Yazelix/nova/stable#yazelix-no-helix

The four no-rio packages retain yzx enter. yzx launch reports that Rio is unavailable. Helix-free packages need an installed editor selected through editor.command. Yazi-free packages need matching host yazi and ya commands.

See the repository installation and package reference for platform evidence, Home Manager declarations, and binary-cache details.

Start the packaged tutor after entering Nova:

yzx tutor begin

• yzx launch opens Nova Rio, then the managed workspace
• yzx enter opens the managed workspace in the current terminal
• Alt Shift K opens Ratconfig inside Nova
• yzx config opens Ratconfig from another terminal
• ~/.config/yazelix/config.toml stores optional sparse semantic overrides
• ~/.local/share/yazelix stores generated runtime state by default
• yzx doctor checks the owned runtime setup and warns when another yzx comes first on PATH

Inside Nova, press Alt Shift K to open Ratconfig. From another terminal, run:

yzx config

Ratconfig shows packaged defaults, saves explicit overrides, and marks Home Manager-owned files as read-only.

The optional root config is:

~/.config/yazelix/config.toml

Nova does not create this file until you save a root setting. Missing keys inherit packaged defaults. Unsupported or misspelled paths fail validation.

Common fields include:

For example:

[appearance]
mode = "light"

[shell]
program = "fish"

[editor]
command = "nvim"

Ratconfig labels each field with its apply timing. Start a new session for fields marked next launch or next session.

Straight borders may be single or double. Zellij’s rounded_corners rounds only single borders, so double borders keep square corners. Set forest.enabled = false to start managed Helix without Nova configuring or opening Forest.

Radar is the default sidebar. Set sidebar.command = "yzx-yazi" to use Nova’s managed Yazi there, or select another executable and pass its arguments through sidebar.args. Custom sidebar commands do not receive Radar-specific keys, permissions, onboarding, or diagnostics.

Component-specific configuration lives beside config.toml:

Ratconfig exposes exact file actions for these surfaces. Native owners keep their own validation and schema.

To enable automatic Zellij Scroll mode entry, set or update this top-level value in ~/.config/yazelix/zellij/config.kdl, then start a new session:

scroll_mode_sync true

Without this override, scrolling does not enter Scroll mode. Existing sessions keep their configuration. See Scrolling and search for the mode shortcuts.

The Home Manager module owns one enable flag, package selection, sparse programs.yazelix.config.settings, and optional native files. It writes no runtime config unless you declare one of those options.

Store-backed files appear as read-only in yzx config. Edit the named programs.yazelix.config.* option, then run your normal Home Manager switch.

Nova writes generated runtime state to ${XDG_DATA_HOME:-$HOME/.local/share}/yazelix unless YAZELIX_STATE_DIR overrides it. Edit the config inputs, not generated output.

See the repository configuration reference for the complete field and native-file contracts.

Nova extends the Helix and Vim h/j/k/l model across the workspace.

Alt ] or Alt [ switches the tab between the stacked and split arrangements. The split puts one work pane in its own column beside the remaining stack, so it needs two work panes. Alt m opens another. The sidebar stays open or collapsed as you left it, and the command menu’s layout entry does the same switch.

Ctrl Alt h and Ctrl Alt l move the focused work pane between the columns of the split arrangement. The pane keeps focus and the other panes keep their order. They do nothing in the outermost column, in the stacked arrangement, or while a popup is open. Ctrl Alt Shift H and Ctrl Alt Shift L move the active tab. They rely on the Kitty keyboard protocol to keep Shift distinct.

Press a popup key again to hide or close that surface and return to the tiled workspace.

Every new tab starts with a focused quick zoxide search. Search Enter moves Yazi to the selected folder. It leaves the tab folder and editor unchanged. Ctrl O opens the selected folder in the editor and completes startup. Tab or Esc switches to full Yazi. While browsing, Tab or Z opens the same search, and Shift Tab previews the hovered file with Spot.

In the persistent Yazi popup, search Alt Enter sets the selected result as the tab folder without moving Yazi or opening an editor. While browsing, it uses the hovered folder, or the current folder when hovering a file or nothing. Startup Yazi does not offer this separate tab-folder action.

On macOS, set option-as-alt = "Left" or "Both" in ~/.config/yazelix/rio/config.toml to use Option for Alt shortcuts in Nova Rio.

Mouse and trackpad scrolling review terminal history without automatically entering Zellij Scroll mode. Press Ctrl Alt s to enter Scroll mode explicitly. From there, press s, type a query, and press Enter to search. Press Ctrl Alt s again to return to ordinary input.

The default applies to new sessions. To restore automatic mode entry, use the Zellij native-file override.

Clicking a tab switches to it when you release the mouse button.

Open yzx config to edit the managed config, agent, Git, menu, screen, sidebar, sidebar-focus, and bottom-hints chords. The corresponding keybindings.* fields live in ~/.config/yazelix/config.toml and accept a key chord or false. Changes apply to new sessions.

The fixed Alt Shift Y, application-local Alt r, and managed Yazi bindings remain in their native packaged owners. Nova rejects collisions among managed semantic keys.

Ratconfig’s Keys tab is the complete packaged reference. The runtime sources are defaults/zellij/config.kdl, the managed Helix config, and the managed Yazi keymap.

Choose one update owner for each Yazelix install.

Confirm the installed profile entry when needed:

nix profile list

Upgrade the profile-owned package:

nix profile upgrade --refresh yazelix

Pass the exact installed package name when your profile uses another entry name.

Run this from the configuration that declares the Yazelix input:

nix flake update yazelix

Replace yazelix with your input name, then run the configuration’s normal Home Manager or nix-darwin switch command. Do not use nix profile upgrade for a package installed by Home Manager.

The update follows the input’s stable, main, edge, or immutable tag reference. Stable is the normal release channel. Main receives accepted updates more often, and Edge carries experimental dogfood changes.

The updated package applies to future launches. Open Nova sessions keep their current immutable Nix store paths until you close and relaunch them.

See the repository installation reference for package-owner details.

Start with doctor:

yzx doctor

yzx doctor validates Nova’s owned config, helpers, selected editor, Yazi pair, Zellij package, layout, and plugins. A failed preflight prints the failing check without opening Rio or Zellij. Doctor and status inspect without creating or repairing configuration, runtime files, Rio state, or plugin permissions. Existing launch and run commands prepare missing runtime state.

yzx status
yzx status --json
yzx --version

Status reports the selected package, config home, state directory, shell, editor, popup keys, layout, Yazi source, and session context.

yzx radar-setup

Radar checks Codex, Claude Code, and OpenCode in order, reports existing integrations, skips unavailable agents, and asks before changing each supported agent. Start a fresh agent session after setup and review any agent-owned trust step it reports.

The root config is optional:

~/.config/yazelix/config.toml

Open yzx config to inspect known invalid fields and exact native-file actions. Back up config.toml before manual recovery. Removing an optional override restores its packaged default on the next applicable launch.

If an old clone, wrapper, or shell function shadows the current package:

type yzx
command -v yzx

The command should resolve to the Nix profile, the Home Manager package, or the installer’s ~/.local/bin/yzx link that owns the install. yzx doctor warns when another yzx comes first on PATH. Remove a stale wrapper only after you identify its owner.

For a profile install:

nix profile upgrade --refresh yazelix

Home Manager users update the declared input and run their normal switch.

Doctor reports recognized Classic state and migration backups in the active roots. Nova does not load, archive, or remove those paths. External scripts may still reference them.

yzx enter

Use a new session when the updated package or a next-session setting needs to take effect. Zellij owns existing session lifetime and attachment.

Do not repair Nova by editing generated files under ~/.local/share/yazelix. Fix the owned config input or package owner instead.

Yazelix Nova is a Nix-packaged terminal workspace with one front door: yzx.

yzx launch -> Nova Rio -> managed Zellij workspace
yzx enter  -> current terminal -> managed Zellij workspace
yzx run    -> prepared Nova environment -> requested program
yzx-zellij -> Nova's exact packaged Zellij CLI

Bare yzx prints help. launch is the only Nova Rio route. enter needs an interactive terminal and works without a display server.

The full package includes:

• Nova Rio for graphical launch
• Nova’s pinned upstream Zellij build and managed layout
• managed Yazi, Helix, and Nushell
• popup, config, screen, tutor, Git, prompt, and completion tools

Package names follow yazelix[-no-rio][-no-helix][-no-yazi]. Each suffix removes that managed package while retaining the remaining integration. Rio-free packages retain yzx enter. Helix-free and Yazi-free packages use the selected host tools.

Nova renders runtime state under:

~/.local/share/yazelix

This directory is output. Edit the config inputs instead.

The optional sparse semantic config is:

~/.config/yazelix/config.toml

Component-native files live under the same ~/.config/yazelix/ root. Normal host config at ~/.config/{helix,yazi,starship} is not loaded by default.

Nova targets managed panes by identity:

• Forest is the managed Helix file tree
• Radar is the default configurable sidebar. yzx-yazi is an optional replacement
• each new tab starts with a focused quick zoxide search. Tab switches to startup Yazi
• each tab has one canonical workspace root
• managed opens reuse the tab’s editor
• yzx reveal opens the persistent Yazi popup at a target
• Git and agent tools use workspace-scoped popups
• startup-search Ctrl O sets the initial tab folder and opens its editor
• popup Yazi Alt Enter sets only the tab folder. Existing panes keep their own cwd

Nova Rio owns graphical launch. Zellij owns multiplexing. Forest owns the managed Helix tree, Radar owns activity presentation, and Nova Bar owns top-bar tabs, modes, and status. Focused first-party packages own popups, pane orchestration, screens, and Yazi themes. Nova pins and composes their package outputs. Nova and Zellij lists the packaged layout, plugins, and Nova’s Zellij build.

See the repository architecture for component contracts and verification gaps.

Nova uses Zellij as the multiplexer. Tabs, stacked panes, floating panes, layouts, and the plugin API are Zellij. Yazelix ships a default layout, keys, plugins, and yzx around that. Nova builds its own yzx-zellij from pinned upstream Zellij, as described below.

Upstream Zellij owns multiplexing: tabs, tiled and stacked panes, floating panes, sessions, layouts, and plugins. Rounded pane corners, pane frames, and swap layouts are Zellij settings. Nova’s default workspace uses those surfaces.

The product shape around the multiplexer lives in packages, layout, and plugins:

Ratconfig can change a Zellij setting while a session runs. The popup is Yazelix. The value it writes, such as rounded corners, is still Zellij.

Nova builds yzx-zellij from unreleased upstream Zellij main at 333d7898. The build embeds Nova Bar, Radar, the popup, the pane orchestrator, and nova-zjhints, so the built-in plugins need no permission cache entries. Sessions from the earlier Zellij binary stay separate.

Zellij carries two small patches. One keeps startup callbacks for background plugins until the first client connects. The other sends a command-line pipe payload once, so Nova’s helpers get a single reply. The bottom bar, nova-zjhints, is zjhints v0.5.0 with Nova patches for modifier grouping and lighter event handling. It replaces Zellij’s native status bar. The pin, patches, and removal conditions live in the Nova Zellij distribution notes.

Start with yzx config. It displays packaged defaults and writes sparse overrides to ~/.config/yazelix/config.toml.

Use it for:

• appearance mode
• shell, Atuin history, and editor commands
• welcome behavior
• managed popup and sidebar keys
• agent command and arguments
• popup margins and top-bar widgets

Use sidecars for tool-specific preferences that Yazelix does not render:

Home Manager exposes programs.yazelix.enable, package selection, sparse settings, and optional native files. Store-backed files remain read-only in Ratconfig. Change the reported module option and run the normal switch.

Files under ${XDG_DATA_HOME:-$HOME/.local/share}/yazelix are generated output. Change the config input or package owner instead of editing runtime state.

See the repository configuration reference for file layering and validation details.

yzx doctor

type yzx
command -v yzx

The command should resolve to your Nix profile or Home Manager owner path, not an old ~/.local/bin/yzx wrapper or shell function.

nix profile upgrade --refresh yazelix

Home Manager users update their declared input and run the normal switch.

yzx config

The optional root file is ~/.config/yazelix/config.toml. Back it up before manual recovery. Ratconfig exposes invalid fields and exact native-file actions.

Do not manually edit:

~/.local/share/yazelix

Relaunch Nova after fixing the owning input. Open sessions keep their existing package and next-session settings.

Useful issue details:

• OS and architecture
• install owner: Nix profile, Home Manager, or one-off nix run
• yzx --version
• yzx doctor
• yzx status or yzx status --json
• exact command output
• whether the problem reproduces in a fresh yzx enter session