zide: A Zellij IDE-like Layout Environment

Zide is a combination of Zellij layouts and convenience bash scripts that creates an IDE-like layout environment. It mainly consists of a file picker (such as yazi) in one pane, and your editor of choice in the main pane. You can browse the file tree in your picker pane, and then any files that are selected or opened do so in the editor's pane.

The project was inspired by the yazelix project, but simplifies it down to work in most shells (instead of requiring nushell), more editors (vs just Helix), and essentailly any file picker, with less required configuration.

Features

1. Start a zellij layout with a filepicker on the left and your editor on the right
2. Browse for files in any visual file picker of your choosing, and open any selected files or directories in your editor pane
3. Open multiple files at once in your editor if your picker supports a multiselect UI
4. When opening a directory, set that directory as the working directory in your editor automatically
5. Load different config files for yazi or lf based on the loaded layout

This project has been tested and works well with the following modal editors:

• Helix (hx)
• Kakoune (kak)
• NeoVim (nvim)
• Vim (vim)

And the following file pickers:

• yazi
• nnn
• broot
• lf
• fff
• felix

But will probably work with just about any TUI file manager.

Why?

I recently started using Helix as my editor of choice. I loved most everything about it, except that there was no tree-style file browser to open files. While the fuzzy finder is fantastic for quickly getting to files I know about, I often work in large monorepos where I don't know the directory or file naming structure in advance, and a visual filepicker is extremely useful. On top of that, yazi is an incredibly powerful and useful tool for file management, and integrating it seemlessly with Helix was high on my list of priorities.

Installation

Download or clone the project files and place them somewhere convenient on your system (such as $HOME/.config/zide).

$ git clone [email protected]:josephschmitt/zide.git $HOME/.config/zide

Then add the bin/ directory to your PATH.

# Add this to your shell profile
export PATH="$PATH:$HOME/.config/zide/bin"

Dependencies

This project integrates zellij with a file picker of your choosing and an editor, and so you'll need these installed for any of this to work (if no specific file picker is set, it defaults to yazi).

There are some additional layouts included that use a lazygit floating pane for easy git integration, so you'll need lazygit installed if you plan on using that. Otherwise, the rest is written in plain bash so it should work on a wide variety of systems without further dependencies.

Usage

  $ zide [OPTIONS] <working_dir> <layout>

Run the zide command to start using Zellij with the zide-style IDE-like layout. It accepts two positional arguments, both of which are optional:

1. <working_dir> Defaults to ., aka your current working directory. Whatever directory you pass as this argument will be the directory that the file picker, your editor, and any future panes will start out in. If you want to open the IDE to a specific project, I suggest passing in that project's directory as this argument (as opposed to navigating after startup) so the working directory is correctly set.
2. <layout> Defaults to the ZIDE_DEFAULT_LAYOUT env var if set, otherwise to default. You can see the list of available layouts in the layouts/ directory.

When executed, the zide command will do one of two things:

1. If you're not currently in a zellij session, it'll start one
2. If you're in an existing zellij session, it'll create a new tab

Options

1. -p, --picker: File picker to use. Available file pickers are listed in bin/lib. This is equivalent to setting ZIDE_FILE_PICKER env var.
2. -n, --name: Optional name to give the newly opened session (when starting a new session) or tab (when launching from an existing session). If a session with this name already exists, it'll use a default random session name.
3. -N: Name the newly opened session or tab after the directory being opened (ignored if --name is set). If a session with this name already exists, it'll use a default random session name.

Available Layouts

The following layouts can all be found in the layouts/ directory as separate .kdl files. You can choose which layout to start with by either passing it to the zide command, or setting the ZIDE_DEFAULT_LAYOUT env var.

default

By default starting zide will use a layout consisting of 2 vertical split of panes with a filepicker on the left occupying a small slice of it, and your editor on the right occupying the rest, with your current working directory set as the directory in both your editor and the filepicker.

If you add one more pane, you'll have the choice between two swap layouts: "compact" and "wide". These map to the old (now deprecated) compact and wide layouts, but all contained in a single super layout using swap layouts.

compact (Deprecated)

This is the old default layout without the new swap layouts. Starts with the same layout as the new default, but without the option to swap to wide.

wide (Deprecated)

This is an old layout that has the same layout as the new "wide" swap layout. The wide layout has a 3rd, 80-column wide pane to the right.

tall

The tall layout takes advantage of tall screens or windows and lays the panes out horizontally, with the picker occupying the top of the layout in a narrow view, and the editor below. Due to zide's new-found config switching, if you use yazi or lf as your file picker, this layout will automatically switch to a 3-pane view.

stacked

The stacked layout uses Zellij's pane stacking feature to create 3 horizontal panes stacked on top of each other, but only 1 pane is visible at any one time. Switching panes will then make that pane visible, and collapse the rest.

---

Each default layout also includes a _lazygit variant that includes a floating pane running lazygit for easier git access.

Any additional layouts you add or configure in the zide layouts/ directory will be available to use from the zide command, and will be git ignored.

Configuration

$ zide --help

For basic help, you can use the -h or --help flags on any of the available commands to get details on how to configure them.

Custom Layouts

If you want to make your own layouts, duplicate any of the built-in layouts in the layouts/ directory and give them custom names. You'll be able to refer to those names when providing a custom layout to the zide command.

You can make any type of layout you like and use any and all of Zellij's awesome layout features. The one absolute requirement is that your editor pane must be next to the picker pane. There's no way to uniquely identify the different panes in zellij (outside of a plugin, anyway), therefore these scripts depend on calling zellij action focus-next-pane to focus your editor from your picker.

Environment Variables

This project provides customization via the use of environment variables:

1. ZIDE_DEFAULT_LAYOUT: Default layout. Available layouts can be found in the zide layouts/ directory. Feel free to add some layouts of your own here (they're gitignore'd).
2. ZIDE_FILE_PICKER: The file picker command to use, defaults to yazi if none is set.
3. ZIDE_ALWAYS_NAME: When set to true, it'll always use the basename of the current working directory as the name of a new Zellij zide session or tab. Equivalent to always using the -N flag.
4. ZIDE_USE_YAZI_CONFIG: When using yazi as a file picker, this will point it to the yazi/yazi.toml included with this project instead of using the default config. This config sets yazi's ratio so that it operates in a single pane mode, which is more similar to how IDE's work. If you want to continue using your standard yazi config, set this env var to false (defaults to true). Alternatively, if you want to point to a different custom config directory, set this env var to that value. Additionally, you can conditionally load specific config files based on the layout you're in by appending :<layout> to your path and declaring multiple paths.

   export ZIDE_USE_YAZI_CONFIG="$HOME/.config/yazi-3p:stacked $HOME/.config/yazi-1p"

   In the above setup, it'll load the yazi-3p config directory when using the stacked layout to display a 3-pane layout in Yazi, otherwise load the standard 1-pane config. Make sure the "default" value that should match any layout is the last one in the list and has no :<layout> declared.
5. ZIDE_USE_LF_CONFIG: Same idea as ZIDE_USE_YAZI_CONFIG, but for lf as the picker. This project includes a basic custom config to run lf in single pane mode, which you can turn off by setting this env var to false. Or, if you want to point it to your own config to use with zide, set the env var to that value. This env var also supports layout-based configs like Yazi does above.

File Picker Configurations

Yazi

If you're using yazi and want to use a custom config other than your default and the one included in this project, you can point to a custom config directory in the ZIDE_USE_YAZI_CONFIG var.

# ~/.config/yazi-custom/yazi.toml

[manager]
ratio = [0, 1, 0]
show-hidden = true
# Some more config options here

export ZIDE_USE_YAZI_CONFIG="$HOME/.config/yazi-custom"

This will use that config when running in zide, but not when running yazi normally.

lf

When using zide with lf, you'll probably want to start it in single column mode. Similarly to Yazi above, zide comes with a simple config file it points to when using lf that turns this on by default called ZIDE_USE_LF_CONFIG. Similarly, set it to false to disable it, or give it a value to point it to a config outside of this project.

# ~/.config/custom-configs/lf/lfrc
set preview false
set ratios 1

export ZIDE_USE_LF_CONFIG="~/.config/custom-configs"

How it works

This project consists of 4 parts:

1. Pre-configured zellij layouts
2. The zide command to launch you into zide mode
3. A wrapper script around launching file pickers called zide-pick
4. A wrapper script that controls opening files in your editor called zide-edit

zide

The main zide command controls opening new zide tabs, either in an existing session if inside one or starting a new one. It sets some environment variables, updates the working directory, and starts zellij.

zide-pick

The zide-pick command is a small wrapper around the file pickers. It handles launching the correct picker based on either the --picker flag or the ZIDE_FILE_PICKER environment variable. This lets us avoid having to hard-code what picker to use in our layouts.

It also has one more very important job, which is changing the EDITOR env var to be zide-edit instead of your actual editor, so that the pickers open up our script instead of the real editor when picking files.

zide-edit

The zide-edit command takes the place of your EDITOR. Instead of launching your EDITOR, it automates switching to your open editor pane, and sends it the correct zellij action commands so that it opens those files in the open editor pane.

zide-rename

The zide-rename command is a convenience script for renaming zellij tabs. You can provide it a parameter of a tab name, and it'll use that to rename the currently focused tab. However, its main use case is in a layout as an auto-closing pane. Usage in this way will automatically name new tabs after whatever directory they're being opened to.

---

Conceptually, this is the basic flow of the system.

We start up zellij with our layout (say two panes, left is yazi via our zide-pick wrapper script, and right is our editor, hx). When you choose files in yazi, yazi will attempt to open those files in EDITOR, which now points to zide-edit. The zide-edit script then switches the focused pane using zellij action focus-next-pane (which hopefully is the pane with your editor). It then writes the following commands to the pane to execute in the editor:

1. zellij action write 27: This sends the <ESC> key, to force us into Normal mode in your editor.
2. zellij action write-chars :open file1.txt subdir/file2.txt: This essentially just sends the :open file1.txt subdir/file2.txt command to your editor, which will tell it to open those files.
3. zellij action write-chars :cd subdir/: If you chose a directory in your filepicker it'll also send the cd command to set the working directory to that directory in your editor.
4. zellij action write 13: Send the <ENTER> key to submit the commands.