Zellij

[Installation] [Screencasts & Tutorials] [Configuration] [Layouts] [FAQ]

   

What is this?

Zellij is a workspace aimed at developers, ops-oriented people and anyone who loves the terminal. Similar programs are sometimes called "Terminal Multiplexers".

Zellij is designed around the philosophy that one must not sacrifice simplicity for power, taking pride in its great experience out of the box as well as the advanced features it places at its users' fingertips.

Zellij is geared toward beginner and power users alike - allowing deep customizability, personal automation through layouts, true multiplayer collaboration, unique UX features such as floating and stacked panes, and a plugin system allowing one to create plugins in any language that compiles to WebAssembly.

Zellij includes a built-in web-client, making a terminal optional.

You can get started by installing Zellij and checking out the Screencasts & Tutorials.

For more details about our future plans, read about upcoming features in our roadmap.

How do I install it?

The easiest way to install Zellij is through a package for your OS.

If one is not available for your OS, you could download a prebuilt binary from the latest release and place it in your $PATH. If you'd like, we could automatically choose one for you.

You can also install (compile) with cargo:

cargo install --locked zellij

Try Zellij without installing

bash/zsh:

bash <(curl -L https://zellij.dev/launch)

fish/xonsh:

bash -c 'bash <(curl -L https://zellij.dev/launch)'

Installing from main

Installing Zellij from the main branch is not recommended. This branch represents pre-release code, is constantly being worked on and may contain broken or unusable features. In addition, using it may corrupt the cache for future versions, forcing users to clear it before they can use the officially released version.

That being said - no-one will stop you from using it (and bug reports involving new features are greatly appreciated), but please consider using the latest release instead as detailed at the top of this section.

How do I start a development environment?

• Clone the project
• In the project folder, for debug builds run: cargo xtask run
• To run all tests: cargo xtask test

For more build commands, see CONTRIBUTING.md.

Configuration

For configuring Zellij, please see the Configuration Documentation.

VibeCrafted Shell Layouts

This fork also ships built-in VibeCrafted operator layouts meant to back the vibecrafted flow when repo-owned config is not available:

• vibecrafted — operator-first shell surface
• vc-dashboard — mission control monitoring grid
• vc-workflow — implementation workspace
• vc-marbles — convergence workspace
• vc-research — synthesis + research swarm workspace

Use them the same way as the stock built-ins, for example:

zellij -l vibecrafted
zellij -l vc-dashboard
zellij setup --dump-layout vibecrafted
zellij setup --dump-layout vc-dashboard

They are exposed as first-class built-ins, so they also surface in layout discovery flows such as the session/layout management UIs instead of behaving like ad-hoc repo-only files.

The shell-provider layouts resolve mission-control helpers from the standard home store first, then from a companion repo checkout at ~/Libraxis/vibecrafted via VIBECRAFTED_COMPANION_ROOT, and finally from repo-local stores. vc-dashboard also acts as a branded control hub for the native Zellij surfaces we lean on most: live monitoring, session atlas, layout forge, configuration control, plugin curation, workspace navigation, sharing, and the VibeCrafted shell guide.

Installing repo-owned layouts into ~/.config/zellij/layouts/

The Vibecrafted framework ships its canonical layouts (dashboard, marbles, operator, research, workflow) as real .kdl files under <vibecrafted-root>/config/zellij/layouts/. To make them visible to stock zellij --layout <name> invocations, run:

zellij setup --install-vibecrafted-layouts
# or with explicit root:
zellij setup --install-vibecrafted-layouts --vibecrafted-root /path/to/vibecrafted

The installer:

1. Resolves the framework root dynamically. Order: --vibecrafted-root flag → $VIBECRAFTED_HOME env (with a tools/vibecrafted-current fallback for the standard $HOME/.vibecrafted user-home convention) → which vibecrafted canonicalized and walked up until a directory containing config/zellij/layouts/ is found. If none of these succeed, or if the resolved path lacks a populated layouts directory, the installer exits non-zero with a clear error — silent installs against a wrong path are refused.
2. Enumerates layouts from the live filesystem listing of <root>/config/zellij/layouts/*.kdl. There is no hardcoded list in the Rust source. Add a foo.kdl to the repo, re-run the installer, and ~/.config/zellij/layouts/foo.kdl appears without any code change.
3. Cleans up stale symlinks. On every run, symlinks under ~/.config/zellij/layouts/ whose target either no longer exists or points into the vibecrafted tree are removed. Non-symlink files (your hand-written layouts) and symlinks pointing at unrelated frameworks are left alone.
4. Applies a data-driven alias map. If <root>/config/zellij/layouts/aliases.txt exists, each line in the form old=new installs a compatibility symlink at ~/.config/zellij/layouts/<old> pointing at the current <root>/config/zellij/layouts/<new> layout file. Lines starting with # and blank lines are ignored. Aliases whose <new> target no longer exists are dropped (and any pre-existing broken symlink for <old> is removed) rather than silently kept as broken links. Edit aliases.txt, re-run the installer — no rebuild needed.
5. Prints a summary listing every symlink created, re-pointed, already correct, stale-removed, alias installed, alias dropped, and non-symlink file preserved. Re-runs are idempotent — running the installer twice in a row produces identical filesystem state and identical summary output.

Example aliases.txt mapping the legacy names the Vibecrafted framework shipped before the canonical rename:

# Legacy compatibility map — keeps old layout names working after rename.
vc-dashboard.kdl=dashboard.kdl
vc-marbles.kdl=marbles.kdl
vc-research.kdl=research.kdl
vc-workflow.kdl=workflow.kdl
implement-dual.kdl=workflow.kdl
research-grid.kdl=research.kdl
vibecraft.kdl=operator.kdl
vibecrafted.kdl=operator.kdl

About issues in this repository

Issues in this repository, whether open or closed, do not necessarily indicate a problem or a bug in the software. They only indicate that the reporter wanted to communicate their experiences or thoughts to the maintainers. The Zellij maintainers do their best to go over and reply to all issue reports, but unfortunately cannot promise these will always be dealt with or even read. Your understanding is appreciated.

Roadmap

Presented here is the project roadmap, divided into three main sections.

These are issues that are either being actively worked on or are planned for the near future.

If you'll click on the image, you'll be led to an SVG version of it on the website where you can directly click on every issue

Origin of the Name

From Wikipedia, the free encyclopedia

Zellij (Arabic: الزليج, romanized: zillīj; also spelled zillij or zellige) is a style of mosaic tilework made from individually hand-chiseled tile pieces. The pieces were typically of different colours and fitted together to form various patterns on the basis of tessellations, most notably elaborate Islamic geometric motifs such as radiating star patterns composed of various polygons. This form of Islamic art is one of the main characteristics of architecture in the western Islamic world. It is found in the architecture of Morocco, the architecture of Algeria, early Islamic sites in Tunisia, and in the historic monuments of al-Andalus (in the Iberian Peninsula).

License

MIT

Sponsored by