Yazelix Nova docs

Yazelix Nova is a Nix-packaged terminal workspace. You need Nix with flakes enabled. 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.

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

Open the desktop workspace through Nova Rio:

yzx launch

Start the same managed workspace in the current terminal or over SSH:

yzx enter

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

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 native rounded corners take precedence when enabled. 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.

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.

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. Enter opens the selected directory; Tab switches to full Yazi. Tab in startup Yazi returns to quick search at the directory you reached.

Open yzx config to edit the managed config, agent, Git, menu, screen, sidebar, and sidebar-focus 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 Yazi Alt z 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 or Home Manager package that owns the install. 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
• the Yazelix Zellij fork 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
• Alt z retargets the tab workspace and editor together

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 the Nova Zellij fork delta.

See the repository architecture for component contracts and verification gaps.

Nova uses Zellij 0.46 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. The Nova Zellij fork keeps the pinned upstream Zellij base and adds the runtime seams listed here.

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 Zellij starts from upstream Zellij 0.46 and uses its native Kitty direct-placement path. The fork retains focused fixes for Yazi image correctness alongside the runtime seams below.

Upstream’s explicit_theme_hue and native theme actions own startup appearance. The remaining Yazelix delta is deliberately narrow:

Three-island hints change Zellij’s native status bar. Nova Bar is a separate plugin for the top bar. Image-preview coverage, removal conditions, and the pinned upstream base live in the Nova Zellij fork 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