Note: Older entries reference the legacy
yazelix.nixconfiguration. Yazelix now usesyazelix.toml, but historical notes retain the original terminology for accuracy.
See the origin story in docs/the_start.md.
- v13.1: Safer multi-tab cwd routing, stronger
yzx cwdworkspace sync, and better Zellij diagnostics - v13: Plugin-managed editor/sidebar orchestration, deterministic sidebar controls, and cleaner Zellij workspace navigation
- v12: User-declared packs, Nixpkgs unstable, declarative themes, and tighter terminal/Zellij/Yazi integration
- v11: Blazingly fast launches, instant config reloads, Home Manager parity, and zero friction
- v10: Launch interface consolidation, IDE integration, project-oriented workflow, and enhanced UX!
- v9: zjstatus, yzx env, yzx doctor, no_sidebar mode, packs, new logo, desktop entry, and more
- v8: Lots of polish, support for any editor, home-manager config, better zellij tab navigation, persistent sessions and more!
- v7: Nix installs and configures everything for you! (announcement)
- v6: Reveal, Integrate, Automate: Smarter sidebar, Git status, and seamless file opening.
- v5: The POWER of yazi PLUGINS!
- v4: A true sidebar opens files in a helix buffer! (announcement)
- v3: Helix with a File Tree! Now with helix-friendly keybindings, and monorepo! (announcement)
- v2: Yazi-Helix File Tree v2, now with a Closeable Sidebar! (the name 'Yazelix' did not exist yet; announcement)
- v1: My first Zellij/Yazi/Helix/Nushell setup, inspired by a Reddit interaction, with no integration and a lot of hacks (announcement)
- Cross-Tab Yazi Cwd Isolation -
yzx cwdand related sidebar sync flows now target the current tab's managed Yazi pane instead of whichever sidebar state file was updated most recently in the session - Stronger Workspace Cwd Routing - The
yzx cwdflow gained better tab retargeting, managed-editor cwd sync, sidebar sync, and cleaner tab naming, making directory changes behave more like a first-class workspace action - Zellij and Workspace Diagnostics -
yzx doctornow checks Zellij plugin health directly, and Yazelix documents the plugin permission flow more clearly when diagnosing broken workspace behavior - Workspace UX Polish - Added
yzx keys, aligned Yazi workspace keybindings, made Zellij default mode configurable, and cleaned upAlt+Shift+mpane handling - Agent and Update Flow Follow-Through - Added
justcode, experimented with pi-agent support, then removed the unstable localpi_rustpackaging path while tightening the canary/update flow
v13: Plugin-managed editor/sidebar orchestration, deterministic sidebar controls, and cleaner Zellij workspace navigation
- The Biggest Pain Points Are Fixed – v13 replaces fragile pane-scanning flows with a real Zellij plugin (written in rust!) that tracks the managed
editorandsidebarpanes 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
editorpane 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+ybinding instead of being entangled with layout-family switching onAlt+[andAlt+] - Deterministic Workspace Navigation –
Ctrl+ytoggles focus between the managed editor and sidebar, whileAlt+[andAlt+]switch predictably between thesingle,vertical split, andbottom terminallayouts - Better Config Inspection –
yzx confignow supports focused section views forhx,yazi, andzellij, plusyzx config open - Simpler Update and Testing Commands –
yzx updateandyzx dev testwere simplified into clearer defaults that are easier to remember and safer to use - Clearer Refresh and Environment Feedback –
yzx envnow shows rebuild activity more clearly, launch paths skip noisy shell-hook welcomes, and Yazelix warns when runtime versions drift - Command Palette –
yzx menugives you a searchable command palette for the main Yazelix actions, including a popup mode inside Zellij onAlt+Shift+m - Refresh Workflow –
yzx refreshmakes it easier to rebuild the Yazelix environment without launching the UI, whileyzx restartcleanly switches the current window onto the refreshed profile (as before)
v12: User-declared packs, Nixpkgs unstable, declarative themes, and tighter terminal/Zellij/Yazi integration
- User-Declared Packs – Packs are defined in
packs.declarationsand enabled viapacks.enabled, with refreshed presets (Rust/Go split,jjpack, simpler git, YAML support). - Yazi Plugin System – Declaratively enable/disable plugins via
[yazi] plugins = ["git", "starship"]inyazelix.toml. Bundled plugins (git, starship, lazygit) can be disabled or replaced with your own installed viaya pkg add. - Yazi User Configs – Full merging support for
yazi.toml,keymap.toml, andinit.luafromconfigs/yazi/user/. User settings override defaults while preserving Yazelix's editor integration. - Zellij & Yazi Themes – Theme/sorting controls, bundled Yazi flavor themes, and a documented cross-theme set shared by Zellij/Helix/Yazi.
- Terminal – Ordered terminal list that defines primary launch target and fallback order for auto-detection,
manage_terminalsto disable Yazelix-managed terminal packages for system-installed terminals, and automatic environment rebuilds before launch/restart on terminal config changes. - Zellij – Pinned zjstatus with configurable widget tray (
zellij.widget_tray) and per-item toggles. - Launch & Config – Direct TOML config parsing, setup-only bootstrap option, modularized core commands, POSIX
shdesktop launcher. - Nixpkgs Unstable – Uses unstable for all packages.
- Updates & UX – Smarter update suite:
yzx update devenv|lock|zjstatus|repo|all, cleaner lock refresh, sweep robustness, extensive bug fixes, and better warnings/compat fixes.
v11: Devenv launch workflow, TOML-first config, way faster cold starts, Neovim parity, a built-in performance toolkit, and richer pack presets
- Devenv-Based Launch Workflow – Yazelix now runs through
devenv shell; devenv’s SQLite cache automatically detects config changes so cold launches from a desktop entry oryzx launchdrop from ~4s to ~0.5s, and you only pay a longer rebuild when you actually edityazelix.toml. Yazelix is now Blazingly fast! - TOML Configuration Format –
yazelix.tomlis the single source of truth (auto-created on first launch) with clear legacy warnings when an oldyazelix.nixis detected. - First-Class Neovim Support – Neovim retains feature parity with Helix (reveal in sidebar, same-instance opening, pane detection).
- Performance Benchmarking –
yzx benchmeasures terminal launch performance with statistical analysis. - Launch Profiling –
yzx profilepinpoints 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_TERMINALenvironment 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
clphelper command.clpjust callsclip 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.
- zjstatus polish: swap layout widget (colored, hide‑if‑empty), colored shell/editor, smarter overlength hiding with tabs prioritized, improved inactive/active tab variants (fullscreen/sync/floating), and cleaner status without tab separators.
- CLI: new
yzx whycommand for a concise "elevator pitch". - Launch interface consolidation: Simplified the previous dual-command flow into a single
yzx launchcommand with intuitive flags:yzx launch(default): new terminal in current directory (project-oriented)yzx launch --here: start in current terminalyzx launch --path DIR: launch in specific directoryyzx launch --home: launch in home directory- All flags are composable for maximum flexibility while maintaining a clean interface
- IDE integration enhancements: Added quiet mode to
yzx envfor seamless IDE terminal integration:- Suppresses verbose output when
YAZELIX_ENV_ONLY=true - Clean, minimal output suitable for IDE/editor terminals (Zed, DataGrip, etc.)
- Eliminates ASCII art and chatty setup messages in quiet mode
- Suppresses verbose output when
- Enhanced yzx env functionality: Improved shell handling and user experience:
- Now launches configured shell by default (more intuitive than keeping current shell)
- Added
--no-shellflag for users who want to keep their current shell - Aligned bash and nushell implementations for consistent cross-shell behavior
- Project-oriented workspace behavior: All launch commands now start in current working directory by default, creating a more intuitive project-focused workflow that eliminates the need to navigate from home directory
- Docs: POSIX/XDG paths doc + README link; SSH/Remote section in README.
- Desktop integration: Fixed window branding to show "Yazelix" in taskbars/docks, with proper StartupWMClass for desktop entry association.
- Terminal bundling: Added bundled terminal emulators (Ghostty, WezTerm, Kitty, Alacritty) with automatic nixGL GPU acceleration. Only downloads your preferred terminal, with Ghostty always included as fallback.
- Ghostty cursor trails: New presets (blaze, snow, cosmic, ocean, forest, sunset, neon, party, eclipse, dusk, orchid, reef, inferno) plus a
randomoption that rotates between colorful presets (excludingnoneandparty). Configure viacursor_trailinyazelix.nix. Kitty supportssnow; WezTerm/Alacritty do not support trails. - Shell initializers: Aggregate per‑shell initializer (
yazelix_init.*) to source only what exists. Essential tools (starship, zoxide) are robust; optional tools (mise, carapace, atuin) are omitted when disabled or missing. No more parse‑time source errors. - Terminal configs: New
terminal_config_modewith three modes:yazelix(default): use Yazelix‑managed configs under~/.local/share/yazelix/configs(user configs untouched)auto: prefer user configs if present, else Yazelix configsuser: always use user configs Wrappers andyzx launchhonor this consistently (including via desktop entry) and pass the mode via env.
- Config location: All generated terminal configs moved to XDG state dir
~/.local/share/yazelix/configs/terminal_emulators. - Atuin toggle:
enable_atuinadded (default: false). Nushell uses its native history by default; Atuin can be enabled explicitly.
v9: zjstatus, yzx env, yzx doctor, no_sidebar mode, pack-based system, new logo, desktop entry and more!
- Flexible layout system: Sidebar mode remains the default, with optional no-sidebar mode for different workflows:
- Sidebar mode (default): IDE-like workflow with persistent Yazi file navigation (recommended!)
- No-sidebar mode: Available via
enable_sidebar = false, no Yazi sidebar, saves some screen space. Useful if you use other editors that have a built-in file tree
- Pack-based configuration system: Simplified package management with technology stacks:
- Enable entire tech stacks with
packs = ["python", "js_ts", "config"]instead of commenting individual packages - 5 curated packs:
python(ruff, uv, ty),js_ts(biome, bun),rust(cargo tools),config(formatters),file-management(utilities) - Hybrid approach: use packs for bulk selection,
user_packagesfor individual tools
- Enable entire tech stacks with
- Enhanced Zellij layouts: Added comprehensive layout system with both sidebar and no-sidebar variants:
- Sidebar layouts (default):
basic,stacked,three_column,sidebar_closed- persistent file navigation - No-sidebar layouts:
basic,stacked,two_column- clean, full-screen workflows
- Sidebar layouts (default):
- New sidebar_closed swap layout: Dynamic sidebar toggling: use the sidebar_closed swap layout, reach it with
Alt+[/Alt+]for space optimization when needed - New zjstatus plugin integration: Added custom status bar plugin with shell and editor information:
- Shows your configured shell and editor:
[shell: nu] [editor: hx] YAZELIXwith proper spacing and color coding - Replaces default Zellij status bar with a more informative Yazelix-specific display
- Shows your configured shell and editor:
- Dynamic Three-Layer Zellij Configuration: Completely rewritten configuration system with modular, maintainable approach:
- Layer 1: Zellij defaults (fetched dynamically via
zellij setup --dump-config) - Layer 2: Yazelix overrides (
yazelix_overrides.kdl) - Yazelix-specific settings - Layer 3: User configuration (
user_config.kdl) - Your personal customizations with highest priority - Smart caching: Only regenerates when source files change for faster startup
- XDG-compliant: Generated config saved to
~/.local/share/yazelix/configs/zellij/ - Comprehensive template:
user_config.kdlincludes documented examples for themes, keybindings, plugins, and advanced options - Improved maintainability: Removed old static
config.kdlsystem that required manual updates - Better user experience: Users can now easily customize Zellij by editing a single, well-documented file
- Reference documentation: See
configs/zellij/example_generated_config.kdlfor the complete default Zellij configuration
- Layer 1: Zellij defaults (fetched dynamically via
- Alt+p directory opening: New Yazi keybinding for instant workspace expansion:
- Quick pane creation:
Alt+pin Yazi opens selected directory in new Zellij pane - Smart file handling: For files, opens parent directory; for directories, opens the directory itself
- Proper shell environment: New panes start with correctly configured Nushell in target directory
- Quick pane creation:
- Enhanced startup robustness: Improved Nix detection with automatic environment setup, terminal integration, and clear diagnostics
- Health Check System (
yzx doctor): Diagnostic tool that detects and fixes common issues (Helix runtime conflicts, env vars, config validation, etc.). Supports--verboseand--fix. - Atuin shell history integration: Added atuin to the automatic initializer system
- Project logo and desktop integration: Logo with icons and automatic desktop entry setup
- CLI-only environment mode (
yzx env): Load Yazelix tools without the UI interface- Quick access:
yzx envloads all tools (helix, yazi, lazygit, etc.) in your configured shell - No interface overhead: Skips welcome screen and Zellij launch
- Clean messaging: Shows environment status and available commands
- Perfect for scripts: Ideal for automation, VS Code integration, or when you just need the tools
- Quick access:
- New sponsor button
v8: Lots of polish, support for any editor, home-manager config, better zellij tab navigation, persistent sessions and more!
- Home Manager Integration: Optional declarative configuration management via Home Manager module
- Modular Editor Support: Complete rewrite of file opening logic to support any editor while preserving full Helix integration. Now you can use Vim, Nano, Emacs, or any editor via the
editor_commandsetting inyazelix.nix- Helix users get all advanced features (open in same buffer, reveal in sidebar, etc), while other editors get basic Zellij integration (new panes, tab renaming) - Big File/Folder Project-Wide Refactoring: Complete reorganization of the codebase structure for better maintainability and organization
- Yazelix Config Validation: Added validation system to warn users of invalid configuration options in
yazelix.nix - Configurable Editor Environment Variables: New config options to set EDITOR environment variable when empty, override existing EDITOR, and add custom editor commands
- Configurable Welcome ASCII Art: You can now choose between animated or static ASCII art in the welcome screen using the new
ascii_art_modeoption in youryazelix.nixconfig. Setascii_art_mode = "animated"(default) orascii_art_mode = "static"for a non-animated welcome. - Shell-agnostic
yzxcommand: Introduces a unifiedyzxcommand that works across all supported shells (bash, fish, zsh, nushell) with full subcommand support. No more shell-specific limitations - useyzx help,yzx get_config,yzx versions, etc. from any shell! - Seamless Yazelix restart:
yzx restartlaunches a new Yazelix instance before killing the old one, providing a smooth and reliable restart experience. - Yazelix Collection page: Yazelix now includes a dedicated collection page (
docs/yazelix_collection.md) listing all integrated tools and inspirations. - Added macchina to welcome screen: Added a system info summary using macchina (neofetch alternative) to the welcome screen. It can be disabled in the config.
- Dynamic Config Validation: Yazelix now uses a dynamic config validator that checks your config against yazelix_default.nix every time Yazelix starts. It warns about unknown fields, missing fields, and invalid values for key options (like default_shell, helix_mode, terminals, ascii_art_mode). No more silent config errors!
- Improved Helix Pane Detection: Yazelix now checks the topmost pane and the next two below for a Zellij pane named
editor(the Helix pane) when opening files from Yazi, reusing it if found, or opening a new one if not. See Helix Pane Detection Logic for details. - Ergonomic Tab Navigation: Added browser-like tab navigation in Zellij:
Alt+numberto jump directly to tabs 1-9Alt+w/qto walk (focus) next/previous tabAlt+Shift+H/Lto move tabs left/right- Cleaned up legacy/conflicting keybindings for a more user-friendly experience
- Persistent Sessions Configuration: Added support for persistent Zellij sessions with flexible configuration parsing. Configure
persistent_sessions = trueandsession_name = "your_session"inyazelix.nixto reuse the same session across restarts - Full version history and project evolution is now documented in detail, right here!
- Warning: After upgrading to Yazelix v7, terminate any running zellij sessions and old terminals to prevent conflicts
- Introduces a Nix-based development environment via
flake.nix, simplifying dependency installation and ensuring consistent versions for Zellij, Yazi, Helix, Nushell, lazygit, Starship, and other tools - Introduces
yazelix.nixconfiguration file for customizing dependencies, shells, and build options! - Adds lazygit, a fast, terminal-based Git TUI for managing Git repositories
- Adds Starship, a customizable, fast prompt for Nushell, enhancing the terminal experience with Git status and contextual info
- Adds markdown-oxide, a Personal Knowledge Management System (PKMS) that works with your favorite text editor through LSP, inspired by and compatible with Obsidian
- Allows you to build Helix from source automatically
- Installs and configures dependencies automatically
- Introduces (optional) yazelix welcome screen with helpful tips and better error handling during environment setup
- Adds terminal transparency settings because we reaaally believe in transparency
- Adds
launch_yazelix.nuscript to launch your preferred terminal with the Yazelix-specific config. Theyzxalias is automatically available in your shell once the Yazelix shell configurations are sourced. - The
clipcommand from nuscripts is included, allowing you to copy text to the system clipboard directly from Nushell. Use it likels src/*.py | get name | to text | cliporopen data.csv | clip, etc - Introduces dynamic Zellij configuration generation on demand using
nushell/scripts/setup/generate_zellij_config.nu, which combines Zellij's default settings with Yazelix-specific overrides fromconfigs/zellij/yazelix_overrides.kdl, making it easy to stay up-to-date with Zellij defaults while preserving custom settings - Allows for declaration user-defined git-ignored nix packages directly in yazelix.nix
- Improves the "reveal file in sidebar" feature by using Yazi's
revealcommand to automatically highlight and select the specific file, eliminating manual searching in directories with many files - Introduces dynamic version table generation using
nu nushell/scripts/utils/version_info.nu
- Git Plugin for Yazi: Added a plugin to the Yazi sidebar that shows file changes, improving Git integration.
- Reveal-in-Yazi Command: Introduced a command (Alt-y in Helix) to reveal the current file in Yazi, implemented via Nushell and Yazi's emit-to command.
- Limitation: Only works for Helix instances opened from Yazi.
- Improved File Opening Logic: When opening a file from Yazi, Yazelix now always finds a running Helix instance if it exists and is in the correct Zellij pane.
- Enhanced Tab Naming: When opening a file from Yazi, the Zellij tab is automatically renamed to the underlying Git repo or directory name.
- Detailed Logging: Added detailed logging for Nushell scripts and improved logging instructions for Zellij/Yazi.
- Robustness and Polish: Codebase is more robust and features are more polished, especially the "open from Yazi" workflow.
- Config Recommendation: Recommended making Yazelix’s Yazi config the default, with environment variable setup instructions for Nushell users.
- Keybinding Robustness: Fixed keybindings not working after Zellij session resurrection (#40).
- Dynamic Tab Naming: When opening a file from Yazi, the Zellij tab is renamed to the directory of the file you opened (#42).
- Tab Movement: Re-added the option to move tabs left/right, but only in tab mode.
- Improved Pane Stacking: Focuses on stacking the single pane by default for a more intuitive layout (#10).
- Better Helix Detection: Improved logic for detecting whether Helix is running, making file opening more reliable.
- Config Updates: Updated Zellij config to v0.41.0, including new plugin manager and configuration plugin support.
- Yazi Plugin Integration: Yazi's author contributed Lua code to make the status bar look awesome in the sidebar.
- General Robustness: Multiple README and config updates for clarity, troubleshooting, and improved user experience.
- Rounded Corners: The UI now features rounded corners for a more modern look.
- Sidebar Integration: When you hit enter on a file or folder in Yazi, if Helix is open in a pane next to Yazi, it will open in a Helix buffer.
- All it took was some shell scripting magic...
- It will also change your working directory, so when you press
SPACE fyou open the picker in the correct folder.
- Improved New-tab Layout: New panes are now just Yazi in a 100% width pane, working like a picker.
- You just open a file or folder from Yazi and it goes to its proper place as a sidebar to the right.
- Fullscreen Panes: Added a dedicated keybinding (
alt f) to make panes fullscreen. - Repo Renamed: The repo was previously called
zellijfor easy cloning, but now it's properly namedyazelix.- The project's name is Yazelix, not Zellij. The repo name now matches the project.
- See the updated setup instructions in the documentation.
- Nushell Dependency: Nushell is now a dependency (technically not an improvement for everyone, but it is for me!).
- open_file Script Rewritten in Nushell:
- Now works with files with spaces in the filename.
- More sensitive to detecting Helix on the next pane (previously, it would sometimes not detect Helix and open a new instance instead of a new buffer).
- Changes directory into the folder of the file being opened, or into the folder itself if you clicked on a folder.
- I much prefer writing Nushell over Bash for this logic.
- Monorepo: Before, the yazi config files were in a separate repo, now it's all integrated here! Monorepo ftw. (Thanks to Zykino from Zellij's discord for that tip!)
- Yazi Status-bar: Yazi's maintainer (what an honor!) added an init.lua file that makes the status-bar in yazi look really good in the small width it has.
- Project Naming: The project finally got a name: Yazelix. It simply had no name before and that was a mistake.
- Keybinding Remaps: Remapped 6 keybindings from Zellij to avoid conflicts with Helix.
- Use
alt mfor new panes and the rest of the remaps are in Zellij's status-bar. - This is configured in the
layouts/yazelix.kdlfile, if you want to change something.
- Use
- Sidebar Control: Now you can open and close the sidebar.
- Simplified Dependencies: No more nushell dependency. Nushell is a beautiful table-centric cross-platform shell written in Rust, but the way I used it was an ugly hack.
- Simpler Layout Files: The KDL files are more streamlined.
- Removes zjstatus Plugin: The plugin had to be downloaded and configured, while adding nothing game-changing, and I had no ideia how to bundle it in yazelix
- Status-bar is Back, baby!: Life without it isn't easy. The status-bar (help bar) makes the setup much more user-friendly.
v1: File Tree Setup using Yazi, Zellij, Helix, and Nushell (announcement)
Yazelix started as a response to a Reddit interaction, where I shared my Zellij-based setup after being asked for details about integrating Yazi, Helix, Zellij, and Nushell.
My original setup was a Zellij layout using Yazi, Helix, and Nushell:
- Yazi ran in a small (20% width) pane in every new Zellij tab, providing file explorer functionality.
- Helix: Every file I selected in Yazi opened in a new pane within the same Zellij tab.
- Layout: I predefined it with two vertical panes beside Yazi. If more than three panes were opened, the leftmost pane stacked to save space.
- Nushell: I used Nushell to call Helix, so it could load my environment variables (a 'gambiara' workaround).
- zjstatus: I used zjstatus as a better tab-bar plugin, which made the Zellij layout file long but worth it for improved tab management.
- Config files: Yazi Config Files, Zellij Config Files
- Inspiration: I was inspired by a post using Yazi and Kitty, but my version was simpler to implement and used Zellij.
This version had no integration, required Nushell for Helix launching, and was a bit hacky, but it was a practical and shareable starting point for what would become Yazelix.