Yazelix v15.1

Preview

The repo keeps one maintained static preview

Overview

Yazelix is a workspace-focused terminal environment built around Yazi, Zellij, and Helix, with first-class Neovim support too

The supported product in this branch is the trimmed v15 Yazelix

Yazelix now uses the managed yazelix.toml config surface, with the normal flake surface provided by the packaged yazelix runtime plus the top-level Home Manager module, while repo work uses the flake maintainer shell defined in maintainer_shell.nix

What v15 Is

• A narrower workspace product instead of a package-and-environment manager glued onto one
• One supported line again: v15 is live, v14 is historical and unsupported
• First-party Ghostty on Linux and macOS, with WezTerm, Kitty, Alacritty, and Foot still supported when you provide them on PATH
• Fast popup and popup-menu panes with explicit managed identity
• Three built-in sidebar-aware workspace shapes, managed sidebar/editor routing, and a fixed packaged runtime toolset
• No runtime-local devenv, no yazelix_packs.toml, no yazelix packs or yzx packs, no automatic config migrations, and no yzx refresh

v15.0 is the trimmed non-Rust reboot: 15.5% fewer code lines than the historical peak, a much clearer product boundary, a slimmer runtime and command surface, notably faster popup/menu panes, and room for selective Rust in v15.x where it clearly pays for itself, while v16 remains the Rust-forward release target

Daily Workflow

• yzx launch: Open Yazelix in a managed terminal window
• yzx enter: Start Yazelix in the current terminal
• yzx env: Enter the Yazelix tool environment without the UI
• yzx popup: CLI entrypoint for the managed popup pane, usually lazygit; most users trigger the same toggle with Alt+t, and closing it reruns the Yazi sidebar refresh path so git state stays current
• yzx menu --popup: CLI entrypoint for the popup command palette; most users trigger the same toggle with Alt+Shift+M
• yzx update upstream: Upgrade the Yazelix package that owns the current runtime in the default Nix profile
• yzx update home_manager: Refresh the owning Home Manager flake input, then print the home-manager switch step

Workspace Model

• Zellij orchestrates the workspace, with Yazi as a managed sidebar and your chosen editor in the managed editor pane
• Toggle focus between the sidebar and editor with Ctrl+y, and toggle the sidebar itself with Alt+y
• Switch between the built-in sidebar-aware workspace shapes and other workspace layouts; see Layouts
• When you open something from the sidebar with Helix or Neovim, Yazelix targets the managed editor pane through the pane orchestrator instead of relying on pane scanning heuristics
• yzx reveal is the stable editor-integration surface for jumping the current file back into the managed sidebar
• Alt+t toggles the managed popup pane and refreshes the Yazi sidebar git view when that popup closes, while Alt+Shift+M toggles the popup command menu on the same fast floating-pane path

Why Yazelix

Yazelix is a reproducible terminal IDE that integrates Yazi + Zellij + Helix, delivering a consistent, fast "superterminal" locally or over SSH with zero manual setup through smart pane/layout orchestration, sidebar reveal/open flows, a curated built-in toolset, sane defaults, Helix/Zellij conflict cleanup, auto-configured tools like starship, zoxide, and carapace, and useful bundled tools such as lazygit

It already ships with Zellij and Yazi plugins, some maintained in this repo, including the pane orchestrator and sidebar-focused Yazi flows

It has features like reveal in Yazi from Helix or Neovim, opening files from Yazi in your configured editor, and switching workspace layouts without leaving the workspace

Supports top terminals and popular shells, with Ghostty as the first-party bundled terminal, WezTerm, Kitty, Alacritty, and Foot as supported alternatives when present on the host PATH, and everything configured through yazelix.toml while the packaged runtime provides the fixed Yazelix toolset

Get everything running in less than 10 minutes with no extra dependencies beyond Nix

Install once, get the same environment everywhere

Want the high-level product map? See Architecture Map; want the current runtime boundary? See v15 Trimmed Runtime Contract

Acknowledgments

See Yazelix Collection for a full list of all projects, tools, and plugins Yazelix integrates, including links to each project and their homepages

Latest Tagged Release: v15.1

v15.1 hardens install ownership, popup env, and Home Manager packaging

• Stopped packaged and one-off runtime entrypoints from rewriting host shell dotfiles, kept runtime setup inside ~/.local/share/yazelix, and narrowed yzx status back to runtime/config inspection with clearer stale-shell recovery guidance.
• Added the explicit editor token for zellij.popup_program, propagated the canonical runtime env into popup flows, and set VISUAL alongside EDITOR so popup editors and TUI tools reuse the configured Yazelix editor contract.
• Narrowed the packaged public bin/ surface to yzx, moved bundled runtime tools under libexec/, and kept packaged and Home Manager installs away from binary-collision traps while still shipping the full runtime toolset.
• Hardened Linux Home Manager and desktop-launch reliability by passing the runtime-owned nixGL wrapper through the module build, improving Ghostty launch diagnostics, and documenting a minimal flake example plus clearer update-owner recovery.
• Replaced the remaining popup and workflow examples that still referenced Claude with Codex examples.

For exact tagged release notes, see CHANGELOG or run yzx whats_new after installing that release For the longer project story, see Version History

Historical Context

Yazelix v14 is the historical Yazelix Classic snapshot: the broad, heavily integrated, devenv-era version of the project, with yazelix packs, yzx packs, dynamic runtime management, richer terminal breadth, Home Manager and manual install support, and the widest power-user command/config surface

Classic is not the active product line in this branch, and the v14 tag remains available only as the final historical snapshot for users who specifically need that broader shape; it is not a supported line anymore

v15.0 is the trimmed non-Rust reboot, not a broad package-and-environment manager: it drops the old runtime-local devenv layer, trims the command and config surface, and keeps a clearer core around fast workspace entry, layouts, managed workspace actions, explicit update ownership, and the popup/menu-centered workspace UX

On the current v15 branch, the trimmed contract is already narrower: no yazelix_packs.toml, no runtime-local devenv, no launch-profile reuse semantics, no automatic config migrations, a fixed packaged runtime toolset, built-in Ghostty on Linux and macOS, and explicit update owners through yzx update upstream or yzx update home_manager

The important split is this: Yazelix Classic was both a terminal workspace and a runtime/package-environment manager, while v15 is the narrower workspace product because dynamic runtime management was not a good long-term fit for Yazelix scope

For the current trimmed branch contract, see docs/specs/v15_trimmed_runtime_contract.md

Experiments

• Nixless (System) Mode – Experimental work lives on the nixless-system-mode branch and might never land in main

Compatibility

• Platform: Works on Linux and macOS
• Terminal: Ghostty is built into Yazelix on Linux and macOS, while WezTerm, Kitty, and Alacritty remain supported PATH-provided alternatives and Foot remains a Linux-only PATH-provided alternative
• Editor: Any editor works, with Helix and Neovim getting first-class support (reveal in sidebar, open buffer in a running instance, managed editor-pane targeting) and configuration through [editor].command in yazelix.toml
• Shell: Bash, Fish, Zsh, or Nushell - use whichever you prefer

Installation

nix profile add github:luccahuguet/yazelix#yazelix
yzx launch

One-off use without installing also works:

nix run github:luccahuguet/yazelix#yazelix -- launch

Prefer declarative installs? Use the top-level Home Manager module in home_manager/README.md

📖 Complete Installation Guide → - Detailed step-by-step installation instructions

Updating

Choose one update owner for each Yazelix install, and do not mix both update paths for the same installed runtime

• Profile installs: use yzx update upstream
• Home Manager installs: use yzx update home_manager

yzx update upstream prints and runs:

nix profile upgrade --refresh yazelix

yzx update home_manager runs in your current flake directory and refreshes the yazelix input with:

nix flake update yazelix

Run it only from the Home Manager flake that owns this install

If your Home Manager flake uses a different Yazelix input name, run nix flake update <your-input-name> yourself instead

Then yzx update home_manager prints home-manager switch for you to run yourself

Updating replaces the installed runtime that future launches use, while already-open Yazelix windows keep running their current live runtime until you explicitly relaunch them or run yzx restart; Yazelix does not silently hot-swap live sessions in place

Helix Integration

Helix supports optional yzx reveal integration through Alt+r, and Yazelix now reserves Alt+r globally: in the managed editor it forwards Alt+r into Helix for reveal, outside the editor it falls back to the editor/sidebar focus flow, and Ctrl+y and Alt+y remain the dedicated workspace navigation keys

📖 Complete Helix Keybindings Guide → - Recommended keybindings for enhanced editing experience

Neovim Integration

For Neovim-Yazi integration, bind yzx reveal to any editor-local shortcut that does not conflict with your terminal or Zellij bindings; a good default is <M-r>:

This assumes yzx is on your editor PATH

-- Yazelix sidebar integration - reveal current file in Yazi sidebar
vim.keymap.set('n', '<M-r>', function()
  local buffer_path = vim.fn.expand('%:p')
  if buffer_path ~= '' then
    vim.fn.system({ 'yzx', 'reveal', buffer_path })
  end
end, { desc = 'Reveal in Yazi sidebar' })

📖 Complete Neovim Keybindings Guide → - Setup instructions and workflow tips

Version Check

Check installed tool versions:

yzx status --versions

Editor Pane Orchestration

When opening files from Yazi, Yazelix will:

• Ask the Yazelix pane orchestrator plugin for the managed editor pane in the current tab
• Reuse that pane directly when it exists, instead of scanning nearby panes or depending on stack position
• Create a new pane titled editor when no managed editor pane exists yet
• Use the same managed-pane flow for both Helix and Neovim; configure the editor via [editor].command in yazelix.toml

POSIX/XDG Paths

Yazelix respects XDG directories for config, data, state, and cache; see POSIX/XDG Paths for details: ./docs/posix_xdg.md

SSH / Remote

Yazelix shines over SSH: the TUI stack (Zellij, Yazi, Helix) runs cleanly without any GUI, giving you a fully configured, consistent “superterminal” on barebones hosts such as an AWS EC2 instance, while the Yazelix environment delivers the same tools, keybindings, and layouts you use locally, minimizing drift on ephemeral servers

Customization & Configuration

Yazelix uses a layered configuration system that safely merges your personal settings with Yazelix defaults:

• Core settings: Edit ~/.config/yazelix/user_configs/yazelix.toml for shell, editor, terminal, and package preferences
• Yazi customization: Use the built-in [yazi] settings in yazelix.toml for things like plugins, theme, sorting, and binary overrides, and use ~/.config/yazelix/user_configs/yazi/ for deeper merged overrides such as init.lua, keymap.toml, or yazi.toml additions (see Yazi Configuration)
• Zellij customization: Use the built-in [zellij] settings in yazelix.toml for Yazelix-owned Zellij knobs, and use ~/.config/yazelix/user_configs/zellij/config.kdl for your deeper managed Zellij overrides (see Zellij Configuration)
• Your configs persist across Yazelix updates without git conflicts
• Intelligent merging: Generated Yazi and Zellij runtime configs are rebuilt from Yazelix defaults plus your managed overrides instead of forcing you to edit tracked runtime files

📖 Complete Customization Guide → - Detailed instructions for customizing every tool

Editor Configuration

📝 Editor Configuration Guide → - Complete guide for configuring editors

Quick setup:

• Default (recommended):

  [editor]
  command = ""

• Neovim:

  [editor]
  command = "nvim"

• System Helix:

  [editor]
  command = "hx"
  
  [helix]
  runtime_path = "/path/to/runtime"  # Only when your Helix runtime is outside normal discovery paths

• Other editors:

  [editor]
  command = "vim"

Alternative: CLI-Only Mode

To use Yazelix tools without starting the full interface (no sidebar, no Zellij), use:

yzx env

This loads the curated Yazelix tool surface into your current shell, with Yazelix env vars set and clean messaging, and automatically launches the shell configured in your yazelix.toml; if you prefer the legacy behavior, run yzx env --no-shell to stay in your current shell

Internal runtime helpers stay private under libexec/ instead of leaking into your interactive PATH, so host-distributed apps launched from that shell do not accidentally inherit Yazelix-owned core userland tools ahead of the system PATH

If you want the Yazelix tool PATH without switching into your configured shell, use:

yzx env --no-shell

Packages & Customization

What Gets Installed: See the full catalog of tools and integrations in the Yazelix Collection: docs/yazelix_collection.md

• Essential tools: Yazi (file manager), Zellij (terminal multiplexer), Helix (editor), shells (bash/nushell, plus your preferred shell), fzf, zoxide, Starship
• Bundled helpers: lazygit (or lg), mise, carapace, macchina, and the fixed helper tooling behind the trimmed v15 core
• Optional history: atuin remains an optional initializer when the binary is available, but the old shell.enable_atuin config knob is gone
• Yazi preview helpers: p7zip, jq, poppler, fd, ripgrep are part of the fixed runtime surface
• Environment setup: Proper paths, variables, and shell configurations

Customize Your Installation: If you followed step 4 in the installation guide, you already have your ~/.config/yazelix/user_configs/yazelix.toml config file ready, you can modify it anytime and restart Yazelix to apply changes, and you can see yazelix_default.toml for all available options and their descriptions

Terminal Emulator Selection:

• Ghostty (default preference): Modern, fast terminal written in Zig with great performance
• WezTerm (recommended fallback): Best image preview support in Yazi
• Kitty: Fast, feature-rich, GPU-accelerated terminal
• Alacritty: Fast, GPU-accelerated terminal written in Rust
• Foot: Wayland-native terminal (Linux-only)
• Auto-detection: Fallback order follows your configured terminal list
• Configure your preference in yazelix.toml with terminals = ["ghostty", "wezterm", ...] (first item is primary)
• v15 terminal contract: Ghostty is first-party and bundled by Yazelix, while other configured terminals are still supported when you provide them on the host PATH

See the full Customization Guide here.

---

Home Manager Integration

Yazelix includes optional Home Manager support for declarative configuration management through the top-level flake's homeManagerModules.default output; see home_manager/README.md for setup instructions

When should you not use yazelix?

• If you hate having fun

Initializer Scripts

Yazelix auto-generates initialization scripts for Starship, Zoxide, Mise, and Carapace for your configured shell set during environment setup and refresh; see docs/initializer_scripts.md for details

yzx Command Line Interface

🔧 Complete CLI Reference: yzx help - Shell-agnostic command suite

📖 Complete yzx CLI Documentation → - Comprehensive command reference and usage guide

Quick Commands:

• yzx launch - Launch Yazelix in new terminal (current directory by default)
• yzx enter - Start Yazelix in current terminal
• yzx launch --path DIR - Launch in specific directory
• yzx launch --home - Launch in home directory
• yzx launch --terminal ghostty - Force a particular terminal for this launch
• yzx launch --verbose - Print detailed launch diagnostics
• yzx env [--no-shell] - Load Yazelix tools without UI (--no-shell keeps your current shell)
• yzx run <command> [args...] - Run a single command inside the Yazelix environment
• yzx update - Show the supported update-owner paths
• yzx update upstream - Upgrade the active default-profile Yazelix package
• yzx update home_manager - Refresh the current Home Manager flake input, then print home-manager switch
• yzx popup - Toggle the managed popup program, usually lazygit, and refresh the Yazi sidebar git state when it closes
• yzx config [--path] - Show the active config or print its resolved path
• yzx edit config - Open the main managed Yazelix config file in your editor
• yzx restart - Restart Yazelix in a fresh window
• yzx doctor [--verbose] [--fix] - Health checks and diagnostics
• yzx dev profile [--cold] [--clear-cache] - Profile startup phases and write a structured report under ~/.local/share/yazelix/profiles/startup/
• yzx status [--versions] - Show current Yazelix status and optional tool versions

Troubleshooting

🔍 Quick diagnosis: yzx doctor - Automated health checks and fixes

📖 Complete Troubleshooting Guide → - Comprehensive solutions for common issues

Editor Terminal Integration

Want to use Yazelix tools (Nushell, zoxide, starship, lazygit) inside your editor? Zed, VS Code, and Cursor all work seamlessly with yzx env

Quick Setup:

1. Open your editor's integrated terminal
2. Run yzx env to load all Yazelix tools without the UI in your configured shell
3. Enjoy the full Yazelix environment in place Need to stay in your editor's existing shell? Run yzx env --no-shell instead

For more advanced integration options, see our Zed + VS Code terminal integration guide

Styling and Themes

Yazelix includes transparency settings and theme configurations for a beautiful terminal experience, with terminal emulator configs that include transparency settings you can comment or uncomment and Helix themes that include transparent options; see docs/styling.md for customization details

For Helix themes, you can use transparent themes by editing your Helix config:

# theme = "base16_transparent"
theme = "term16_dark"  # Recommended transparent theme

Layouts

Yazelix includes adaptive layouts that organize your workspace; use three_column for Claude Code and AI tools, and see docs/layouts.md for details and customization

Keybindings

Yazelix uses Zellij as the workspace layer, so the most important bindings are global workspace bindings rather than editor-local shortcuts; run yzx keys inside Yazelix for the live summary, and see docs/keybindings.md for the full reference

Keybinding	What It Does
Ctrl+y	Toggle focus between the managed editor and Yazi sidebar
Alt+y	Open or close the sidebar
Alt+r	Smart reveal/focus key; forwards into the editor when appropriate
Alt+[ / Alt+]	Switch between layouts
Alt+m	Open a new terminal in the current tab workspace root
Alt+t	Toggle the configured managed popup program, usually lazygit, and refresh the Yazi sidebar git state when it closes
Alt+Shift+M	Open the yzx command palette popup
Alt+1..9	Jump directly to tabs 1 through 9
Alt+w / Alt+q	Move to the next or previous tab
Alt+Shift+H / Alt+Shift+L	Move the current tab left or right
Alt+Shift+F	Toggle pane fullscreen

Yazi still has its own keymap too: press ~ inside Yazi for its built-in help, and use the most useful Yazelix-specific sidebar flows such as Enter to open through the managed editor integration, Alt+z to pick a directory with zoxide and retarget the workspace, and Alt+p to open the selected directory in a new pane as the current tab workspace root

Helix and Neovim integration is intentionally small: use Ctrl+y and Alt+y for workspace navigation, use Alt+r / yzx reveal when you want the editor to reveal the current file in the managed Yazi sidebar, and see docs/helix_keybindings.md and docs/neovim_keybindings.md for editor-local setup details

I'm Lost! Too Much Information

Start by learning Zellij on its own, then optionally Yazi, and re-read this README afterwards

Contributing to Yazelix

See contributing