v8:

v8.5 with zjstatus:

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)

• To hide the sidebar, make your pane fullscreen! (Ctrl p + f or Alt Shift f)

• 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: Searches up to 4 panes for an existing editor instance. If found, moves it to the top and opens the file there. If not found, launches the editor in a new pane.
  • 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" (press Alt y in Helix/Neovim to reveal the file in Yazi, Alt y in Yazi to focus editor, 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

• See boot sequence for details on how Yazelix starts up

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 a single Nix file with sensible defaults

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

Install once, get the same environment everywhere

• 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.

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

• Devenv-Based Launch Workflow – Yazelix now runs through devenv shell --impure; devenv's SQLite cache automatically detects config changes so cold launches from a desktop entry or yzx launch drop from ~4s to ~0.5s, and you only pay a longer rebuild when you actually edit yazelix.toml. Yazelix is now Blazingly fast!
• TOML Configuration Format – yazelix.toml is the single source of truth (auto-created on first launch) with clear legacy warnings when an old yazelix.nix is detected.
• First-Class Neovim Support – Neovim retains feature parity with Helix (reveal in sidebar, same-instance opening, pane detection).
• Performance Benchmarking – yzx bench measures terminal launch performance with statistical analysis.
• Launch Profiling – yzx profile pinpoints environment setup bottlenecks and profiles cold vs warm startup paths.
• Enhanced UI Controls – Configurable Zellij options: disable_zellij_tips (default: true), zellij_rounded_corners (default: true).
• Streamlined Startup – Welcome screen disabled by default for faster launches (info still logged).
• Sweep Testing Framework – Matrix testing for all shell/terminal/feature combinations (yzx sweep shells|terminals|all).
• Terminal Detection – Proper terminal identification via YAZELIX_TERMINAL environment variable.
• Conditional Shell Hooks – Shell hooks load Yazelix tooling only inside managed shells, preventing surprises in regular terminals.
• Yazi Directory Sync – Opening files from Yazi moves the sidebar to the file's parent directory so the view stays in sync with editor context.
• Simplified Clipboard – Replaced the custom clipboard module with Nushell's standard library implementation and added the clp helper command. clp just calls clip copy
• Comprehensive Pack System – 10 curated technology packs organized into language_packs and tool_packs:
  • Language Packs (7): Python, TypeScript, Rust, Go, Kotlin, Gleam, Nix – complete toolchains with LSP, formatters, linters, and dev tools.
  • Tool Packs (3): Git (onefetch, gh, delta, gitleaks, jj, prek), Config (taplo, mpls), File Management (ouch, erdtree, serpl).
  • Enhanced Packs: Expanded Rust pack (6 tools), improved TypeScript pack with oxlint and typescript-language-server, Python pack with ipython.

• Dynamic Yazi Plugin System – Yazi plugins are now configured in yazelix.toml under the [yazi] section. Core plugins (auto_layout, sidebar_status) are always loaded, and user plugins can be added to the plugins list. External plugins installed via ya pkg add are preserved across config regenerations.
• Configurable Yazi Theme and Sorting – Customize your Yazi experience directly in yazelix.toml with theme and sort_by options, with instant reload on restart.
• Simplified Yazi Configuration – Removed complex TOML merging system in favor of simple config generation. For advanced customization beyond yazelix.toml options, edit the source configs directly in ~/.config/yazelix/configs/yazi/yazelix_*.toml files.

• lazygit.yazi Integration – Launch lazygit directly from Yazi with the gl keybinding. Seamlessly jump into git workflows without leaving the file manager.
• Starship Prompt in Yazi Header – The starship.yazi plugin displays contextual information (git branch, virtual environments, project details) in Yazi's header, complementing git.yazi's file-level indicators.
• Consistent TOML Formatting – Added taplo configuration for multi-line array formatting with trailing commas, improving git diffs and config readability.

• Expanded Yazi Theme Support – Bundled 24 community Yazi flavors (25 total with default), the first cross-platform solution to include all flavors out-of-the-box. Use random-dark (19 themes) or random-light (5 themes) for variety on each restart.
• Cross-Compatible Theme Guide – Documented 9 themes that work across Zellij (37 total), Yazi (25 total), and Helix (199 total) for consistent theming.
• Bug Fixes – Fixed disable_tips setting (was parsed but never applied since v11), improved config robustness by stripping all yazelix-controlled settings from base config.

• Code Modularization – Split core command suite into focused modules (yzx/launch.nu, yzx/env.nu), reducing yazelix.nu from 546 to 306 lines for better maintainability.
• DRY Consolidation – Created shared environment_bootstrap.nu module to eliminate duplicate initialization logic across entry points.
• Improved First-Time Setup – Added --setup-only flag for clean bootstrap experience and fixed installation guide ordering (Nix before Nushell).

• Streamlined Environment Setup – Refactored architecture to read yazelix.toml directly instead of passing 11 parameters through Bash, eliminating type conversion complexity.
• Single Source of Truth – Environment configuration now reads TOML once, consistently, with properly typed values throughout.
• Bug Fixes – Fixed welcome screen duplication, bool/string parameter mismatches, and interactive launch sequence.

• Simplified Terminal Configuration – Terminal selection now uses a single ordered list (terminals = ["ghostty", "kitty"]) instead of separate preferred_terminal and extra_terminals fields.
• Advanced Terminal Control – Added manage_terminals option to disable Yazelix-managed terminal packages for users with system-installed terminals.
• Smart Autodetection – Gracefully handles empty terminal list with automatic detection fallback.

• Automatic Environment Rebuild – Fixed chicken-egg problem when changing terminal configuration. Yazelix now auto-detects config changes and rebuilds the environment to install newly configured terminals.

• Nix-Pinned zjstatus – zjstatus is now sourced from a Nix input and synced on shell entry, making updates reproducible.
• Configurable Widget Tray – Control zjstatus widgets with zellij.widget_tray in yazelix.toml, with easy per-item toggles.
• Documentation – Added widget tray guidance in Zellij configuration docs.
• Seamless Terminal Installation – When manage_terminals = true, switching terminals in yazelix.toml no longer requires manual rebuild - just run yzx restart or yzx launch.

• Smarter Updates – yzx update now separates CLI updates from lockfile updates, adds yzx update repo for pulling upstream changes, and supports yzx update all for a full refresh.
• Safer Lockfile Refresh – yzx update lock prompts before updating to upstream inputs, with a clear note about maintainer cadence.
• Cleaner Sweeps – Terminal sweeps skip missing terminals instead of failing, keeping test output focused.

Full version history: Version History

• 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 running instance, pane detection). Configure via editor_command setting in yazelix.toml
• Shell: Bash, Fish, Zsh, or Nushell - use whichever you prefer
• See the version compatibility table here (generated dynamically!)

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

For Helix-Yazi integration, add this to your Helix config (~/.config/helix/config.toml):

[keys.normal]
# Yazelix sidebar integration - reveal current file in Yazi sidebar
A-y = ":sh nu ~/.config/yazelix/nushell/scripts/integrations/reveal_in_yazi.nu \"%{buffer_name}\""

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

For Neovim-Yazi integration, add this to your Neovim config (~/.config/nvim/init.lua):

-- Yazelix sidebar integration - reveal current file in Yazi sidebar
vim.keymap.set('n', '<M-y>', 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

Check installed tool versions:

nu nushell/scripts/utils/version_info.nu

When opening files from Yazi, Yazelix will:

• Check the topmost pane and up to 3 panes below for a Zellij pane named editor (works for both Helix and Neovim).
• If your editor is found, it is moved to the top and reused; if not, a new editor pane is opened.
• This is needed because when opening or closing Zellij panes in the stack, the editor pane can move around (often down by 2 positions).
• Supports both Helix and Neovim with identical behavior - configure via editor_command in yazelix.toml.

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

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

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 flake delivers the same tools, keybindings, and layouts you use locally, minimizing drift on ephemeral servers.

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 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, pane detection)
• System Helix: editor_command = "hx" - Requires matching helix_runtime_path, full integration
• Other editors: editor_command = "vim" - Basic integration (file opening, tab naming only)

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

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.

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

• 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

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

Yazelix auto-generates initialization scripts for Starship, Zoxide, Mise, and Carapace for your configured default shell, regenerated every startup. See docs/initializer_scripts.md for details.

🔧 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 env [--no-shell] - Load Yazelix tools without UI and drop into your configured shell (--no-shell keeps your current shell)
• yzx doctor [--verbose] [--fix] - Health checks and diagnostics
• yzx profile [--detailed] [--history] - Profile launch performance and identify bottlenecks
• yzx info - Show system information and current settings
• yzx versions - Display all tool versions

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

📖 Complete Troubleshooting Guide → - Comprehensive solutions for common issues

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.

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

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 are discoverable in each tool (e.g., ~ in Yazi, ? in lazygit). See docs/keybindings.md for full details, custom keybindings, and usage tips.

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

See contributing