Yazelix Nova docs

Yazelix Nova is a Nix-packaged terminal workspace. You need Nix with flakes enabled.

nix profile add --refresh github:luccahuguet/yazelix/stable

Open the desktop workspace through Mars:

yzx launch

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

yzx enter

nix run github:luccahuguet/yazelix/stable -- launch
nix run github:luccahuguet/yazelix/stable#yazelix-no-mars -- enter

Run the owned preflight without opening Mars or Zellij:

nix run github:luccahuguet/yazelix/stable -- doctor

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

Package names follow yazelix[-no-mars][-no-helix][-no-yazi]. The suffixes remove Mars, managed Helix, or managed Yazi while retaining the remaining Nova integration.

nix profile add --refresh github:luccahuguet/yazelix/stable#yazelix-no-mars

Use yzx enter with a Mars-free package. Helix-free packages need an installed editor selected through editor.command. Yazi-free packages need matching host yazi and ya commands.

See the canonical installation and package guide for the full matrix, platform evidence, Home Manager, and installed sizes.

Start the packaged tutor after entering Nova:

yzx tutor begin

• yzx launch opens Mars, then the managed workspace
• yzx enter opens the managed workspace in the current terminal
• yzx config opens the Nova configuration UI
• ~/.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

Open Nova’s Ratconfig interface:

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.

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 canonical configuration guide 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.

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 canonical update guide 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 Mars or Zellij.

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.

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 -> Mars -> managed Zellij workspace
yzx enter  -> current terminal -> managed Zellij workspace
yzx run    -> prepared Nova environment -> requested program

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

The full package includes:

• Mars 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-mars][-no-helix][-no-yazi]. Each suffix removes that managed package while retaining the remaining integration. Mars-free packages use 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:

• the file tree is a managed Yazi sidebar
• 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

Mars owns the terminal. Yazelix Zellij owns multiplexing, Ratconfig owns the config UI toolkit, and focused first-party packages own popups, pane orchestration, the top bar, screens, cursors, and Yazi themes. Nova pins and composes their package outputs.

See the canonical architecture for component contracts and verification gaps.

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

Use it for:

• appearance mode
• shell 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 canonical configuration guide 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