Yazelix v13.2

Preview

v8:

v13:

Overview

Yazelix integrates Yazi, Zellij, and Helix (hence the name!), with first-class support for Neovim too.

• Yazelix now uses the devenv-based shell (devenv.nix) and yazelix.toml. The legacy flake interface (flake.nix, yazelix.nix) has been removed.

• Use your preferred shell: Bash, Fish, Zsh, or Nushell - Yazelix works with all of them

• Zellij orchestrates everything, with Yazi as a sidebar and your chosen editor (Helix by default)

• Toggle focus between the sidebar and editor with Ctrl y, and toggle the sidebar itself with Alt y

• Every keybinding from Zellij that conflicts with Helix is remapped see here

• When you hit Enter on a file/folder in the "sidebar":

  • With Helix or Neovim: Targets the managed editor pane through the Yazelix Zellij plugin. If that pane exists in the current tab, the file opens there. If not, Yazelix launches a new editor pane titled editor.
  • With other editors: Opens the file in a new pane with your configured editor
  • It automatically renames the Zellij tab to the file's underlying Git repo or directory name

• Features include:

  • "Reveal file in sidebar" (bind reveal_in_yazi.nu to any editor-local shortcut you prefer in Helix/Neovim, and use Ctrl y to jump between the editor and sidebar, see Keybindings)
  • A Yazi plugin to enhance the status bar in the sidebar pane, making it uncluttered, colorful, and showing file permissions
  • A Git plugin showing file changes in the Yazi sidebar
  • Dynamic column updates in Yazi (parent, current, preview) via the auto-layout plugin, perfect for sidebar use
  • Modular editor support: Helix and Neovim have full integration features, or use any other editor via the editor_command setting

• This project includes config files for Zellij, Yazi, terminal emulators, Nushell scripts, Lua plugins, and a lot of love

Why Yazelix

Yazelix is a reproducible terminal IDE that integrates Yazi + Zellij + Helix. It delivers a consistent, fast “superterminal” locally or over SSH with zero manual setup: smart pane/layout orchestration, sidebar reveal/open flows, curated packs, and sane defaults. It also solves helix/zellij keybinding conflicts (no need to ever lock zellij), auto‑configures great tools like starship, zoxide, carapace (that normally require editing shell config files), and includes many tools from the Yazelix Collection, like lazygit

It already comes with cool zellij and yazi plugins, some of which I maintain myself

It has features like reveal in Yazi (from Helix or Neovim) and opening files from Yazi in your configured editor

Supports top terminals (Ghostty, WezTerm, Kitty, Alacritty) and popular shells (Bash, Zsh, Fish, Nushell). Easy to configure via yazelix.toml, with devenv.nix providing the environment

Get everything running in less than 10 minutes. No extra dependencies, only Nix

Install once, get the same environment everywhere

Vision

• Using the terminal should be easy, beautiful, practical and reproducible
• Good defaults over customization. Have both when possible
• Yazelix is always on the edge of project versions
• Yazelix is always evolving, it's a living being
• What is even Yazelix?
• Yazelix lets you say I use Yazelix btw
• Boy, do we Nix
• Integration, integration, integration
• Made with love.

Acknowledgments

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

Improvements in v13.2

• Workspace Hardening - New-tab workspace defaults, tab-local workspace routing, and the Alt+m / Alt+p workspace flows were tightened so Yazelix behaves more predictably across tabs
• Zellij Integration Hardening - The pane orchestrator and layout/config generation were further hardened to reduce stale state, helper-pane traps, and workspace drift
• Keybinding Model Polish - yzx keys and the README/docs now describe the current workspace actions more clearly, especially around Alt+m, Alt+p, and editor/sidebar movement

Improvements in v13.1

• Cross-Tab Yazi Cwd Isolation - yzx cwd and related sidebar sync flows now resolve the current tab's managed Yazi pane instead of guessing from session-global state, fixing the cross-tab cwd leak that could show up when every tab starts with Yazi
• Stronger Workspace Cwd Routing - The yzx cwd flow now has better tab retargeting, managed-editor cwd sync, cleaner tab naming, and tighter Yazi workspace keybinding alignment
• Better Workspace Diagnostics and Controls - yzx doctor can diagnose Zellij plugin health, yzx keys exposes the current keymap surface more clearly, and Zellij default mode handling is now configurable
• Agent and Update Flow Polish - Yazelix now ships the justcode command, added pi-agent support before later removing the unstable local pi_rust packaging, and further hardened the canary/update path

Improvements in v13

• The Biggest Pain Points Are Fixed – v13 replaces fragile pane-scanning flows with a real Zellij plugin that tracks the managed editor and sidebar panes and routes workspace actions directly instead of relying on shell heuristics
• The Sidebar Can Always Find the Editor – The sidebar can now always find the managed editor pane and open files in it reliably, and it is much faster because Yazelix no longer has to walk through panes or rely on pane-scanning heuristics
• Sidebar and Layout Controls Are Finally Separate – Sidebar open/close now has its own Alt+y binding instead of being entangled with layout-family switching on Alt+[ and Alt+]
• Deterministic Workspace Navigation – Ctrl+y toggles focus between the managed editor and sidebar, while Alt+[ and Alt+] switch predictably between the single, vertical split, and bottom terminal layouts
• Cleaner Keybinding Model – Editor/sidebar navigation is unified, editor-local reveal bindings are documented explicitly, and the temporary wrapper-pane transport was replaced with direct plugin messages
• Runtime Plugin Reliability – The pane orchestrator now ships through a content-hashed runtime wasm path, avoiding stale-plugin cache confusion during development and restart flows
• Launch Robustness – yzx restart now forces a fresh devenv entry path instead of reusing stale terminal state
• Better Config Inspection – yzx config is much more useful now, with focused section views for hx, yazi, and zellij, plus yzx config open
• Simpler Update and Testing Commands – yzx update and yzx dev test were simplified into clearer defaults that are easier to remember and safer to use
• Clearer Refresh and Environment Feedback – yzx env now shows rebuild activity more clearly, launch paths skip noisy shell-hook welcomes, and Yazelix warns when runtime versions drift
• Command Palette – yzx menu gives you a searchable command palette for the main Yazelix actions, including a popup mode inside Zellij on Alt+Shift+m
• Refresh Workflow – yzx refresh makes it easier to rebuild the Yazelix environment without launching the UI, while yzx restart cleanly switches the current window onto the refreshed profile

Full version history: Version History

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 (via Homebrew on macOS), Kitty, WezTerm, Alacritty; Foot on Linux only
• Editor: Any editor works. Helix and Neovim have first-class support (reveal in sidebar, open buffer in a running instance, managed editor-pane targeting). Configure via editor_command in yazelix.toml
• Shell: Bash, Fish, Zsh, or Nushell - use whichever you prefer
• See the version compatibility table here (generated dynamically!)

Installation

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

Helix Integration

Helix supports optional reveal_in_yazi.nu integration through Alt+r. Yazelix now reserves Alt+r globally: in the managed editor it forwards Alt+r into Helix for reveal, and outside the editor it falls back to the editor/sidebar focus flow. 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 reveal_in_yazi.nu to any editor-local shortcut that does not conflict with your terminal or Zellij bindings. A good default is <M-r>:

-- 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('nu ~/.config/yazelix/nushell/scripts/integrations/reveal_in_yazi.nu "' .. buffer_path .. '"')
  end
end, { desc = 'Reveal in Yazi sidebar' })

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

Version Check

Check installed tool versions:

nu nushell/scripts/utils/version_info.nu

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.

Version History & Changelog

For a detailed history of all major Yazelix version bumps and changelogs, see Version History.

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 (for example, an AWS EC2 instance). 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/yazelix.toml for shell, editor, terminal, and package preferences
• Yazi customization: Configure plugins, theme, and sorting in yazelix.toml under the [yazi] section (see Yazi Configuration)
• Zellij customization: Add personal overrides in configs/zellij/personal/ directory
• Your configs persist across Yazelix updates without git conflicts
• Intelligent merging: TOML sections merge properly, avoiding duplicate keys and conflicts

📖 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 = null - Uses yazelix's Helix, no conflicts, full integration
• Neovim: editor_command = "nvim" - Full integration (reveal in sidebar, same-instance opening, managed editor-pane targeting)
• System Helix: editor_command = "hx" - Requires matching helix_runtime_path, full integration
• Other editors: editor_command = "vim" - Basic integration (file opening, tab naming only)

Alternative: CLI-Only Mode

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

yzx env

This loads all tools (helix, yazi, lazygit, etc.) into your current shell, with Yazelix env vars set and clean messaging, and automatically launches the shell configured in your yazelix.toml. Prefer the legacy behavior? Run yzx env --no-shell to stay in your current shell.

If you prefer a raw environment shell without launching Yazelix, you can use:

devenv 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
• Recommended tools (enabled by default): lazygit (or lg), mise, cargo-update, ouch, etc
• Optional history: atuin integration is now controlled by enable_atuin (disabled by default).
• Yazi extensions (enabled by default): p7zip, jq, poppler, fd, ripgrep (for archives, search, document previews)
• Yazi media extensions (disabled by default): ffmpeg, imagemagick (for media previews - ~1GB)
• 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/yazelix.toml config file ready! You can modify it anytime and restart Yazelix to apply changes. See yazelix_default.toml for all available options and their descriptions.

Terminal Emulator Selection:

• Ghostty (default): Modern, fast terminal written in Zig with great performance
  • Linux: Provided by Yazelix via Nix
  • macOS: Install via Homebrew: brew install --cask ghostty (Nix doesn't support macOS app bundles)
• WezTerm (recommended fallback): Works on both platforms via Nix, best image preview support in Yazi
• Kitty: Fast, feature-rich, GPU-accelerated terminal (works on both platforms)
• 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)
• Managed terminals: Set manage_terminals = true to install wrappers and terminal packages via Nix. Set it to false to use system-installed terminals only.

See the full Customization Guide here.

---

Home Manager Integration

Yazelix includes optional Home Manager support for declarative configuration management. See home_manager/README.md for setup instructions.

Notes

• devenv shell automatically passes through the HOME environment variable, so Yazelix can resolve user-specific paths without extra flags
• Tweak configs to make them yours; this is just a starting point!
• For extra configuration, see: WezTerm Docs
• Add more swap layouts as needed using the KDL files in configs/zellij/layouts
• Use lazygit, it's great

When should you not use yazelix?

• If you hate having fun
• If you suffer from a severe case of nix-allergy

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 launch --here - 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 launch --skip-refresh - Launch while skipping explicit refresh trigger (may use stale env)
• yzx env [--no-shell] [--skip-refresh] - Load Yazelix tools without UI (--no-shell keeps your current shell, --skip-refresh may use stale env)
• yzx refresh [--force] [--verbose] [--very-verbose] - Refresh devenv cache/environment without launching UI (-v shows configured package scope + concise build progress, -V shows full debug output)
• yzx run <command> [args...] - Run a single command inside the Yazelix environment
• yzx config [--full] [--path] - Show the active config, hiding packs by default
• yzx config hx|yazi|zellij - Show a focused config section
• yzx restart --skip-refresh - Restart while skipping explicit refresh trigger (may use stale env)
• yzx doctor [--verbose] [--fix] - Health checks and diagnostics
• yzx dev profile [--cold] [--clear-cache] - Profile launch performance and identify bottlenecks
• yzx status [--versions] [--verbose] - Show current Yazelix status, tool versions, and shell hook details

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. The terminal emulator configs include transparency settings you can comment/uncomment, and Helix comes with transparent theme 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 more. See docs/layouts.md for details and customization.

Keybindings

Keybindings are discoverable in each tool (e.g., ~ in Yazi, ? in lazygit). See docs/keybindings.md for full details, custom keybindings, and usage tips.

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