path: root/README.md

# sl0ppij — an opinionated Zellij fork

> This is **not** upstream Zellij. It is a fork maintained at
> <https://git.sl0p.foo/sl0ppij.git>, tracking [zellij-org/zellij][upstream] with a
> small set of opinionated additions, mostly about how panes *look*.
>
> Upstream's README follows below, unchanged.

[upstream]: https://github.com/zellij-org/zellij

## What this fork adds

Everything lives in the existing `ui { pane_frames { ... } }` block, and every option
defaults to upstream behaviour — an unmodified config renders exactly as stock Zellij.

```kdl
ui {
    pane_frames {
        // Where the pane title sits in the frame. Upstream hardcodes it flush
        // left for full frames. (Frameless mode already centred it.)
        title_alignment "center"        // "left" | "center" | "right"   (default: left)

        // Outer gap: real empty terminal between panes, WM style.
        // Expressed in ROWS. A pane insets right/bottom always and left/top
        // only at the screen edge, so two neighbours show exactly `gap`
        // between them -- not double -- and the screen edges match.
        gap 1                           // default: 0

        // Inner padding between a pane's frame and its content.
        // CSS-style shorthand, but the 4-value order is UP DOWN LEFT RIGHT,
        // deliberately NOT CSS's clockwise top-right-bottom-left:
        //   padding 1          all four sides
        //   padding 1 2        up/down = 1, left/right = 2
        //   padding 1 2 3 4    up=1 down=2 left=3 right=4
        padding 1                       // default: 0

        // Show no pane title until something actually names the pane: either
        // you rename it, or the running program sets a title. Upstream always
        // shows a "Pane #N" placeholder. Tracked as a flag rather than by
        // matching the string, so a program that genuinely titles itself
        // "Pane #3" is not mistaken for an unnamed pane.
        hide_default_pane_names true

        // Desaturate the CONTENT of unfocused panes, 0-100 (default 0 = off).
        // Colours are blended toward their own perceptual luminance, so an
        // unfocused pane keeps its brightness but drains of colour. This is
        // real colour transformation, not the SGR "faint" attribute.
        //
        // Cost: focus is per client, so clients can no longer share rendered
        // output and each renders separately. Fine for a single user, worth
        // knowing about in a multi-user session. Sixel/kitty IMAGES are not
        // affected and stay in colour.
        inactive_grayscale 85

        // Columns per row. Terminal cells are ~2x taller than they are wide, so
        // 1 row of gap needs ~2 columns to look like the same distance.
        // Applies to `gap`, and to the 1-value form of `padding`. The 2- and
        // 4-value padding forms are taken literally. Set to 1 to disable.
        gap_aspect 2                    // default: 2

        // Collapse to a named swap layout when the terminal gets narrow, and
        // restore the previous one when it grows back. 0 disables (default).
        // See "Responsive layouts" below -- this one needs swap layouts in your
        // layout file to do anything.
        responsive_min_cols 90          // default: 0 (off)
        responsive_layout "stacked"     // default: "stacked"
    }
}
```

### Responsive layouts

When the terminal is narrower than `responsive_min_cols`, the tab switches to the
swap layout named by `responsive_layout`; when it grows back, the layout that was
active before the collapse is restored. Splitting a wide window into thirds is great
until the window is 70 columns wide and each pane gets 23.

This selects a swap layout **by name**, so it only does something if your layout
file defines one with that name:

```kdl
layout {
    pane split_direction="vertical" {
        pane
        pane
        pane
    }
    swap_tiled_layout name="tiled" {
        tab {
            pane split_direction="vertical" {
                pane
                pane
                pane
            }
        }
    }
    swap_tiled_layout name="stacked" {
        tab min_panes=2 {
            pane stacked=true {
                children
            }
        }
    }
}
```

(One node per line: zellij's KDL parser rejects the `{ pane; pane; }` one-liner form.)

Name-based rather than a new size-aware `LayoutConstraint` on purpose: that type
crosses both the plugin protobuf API and the client/server contract, and the
committed prost assets cannot be regenerated without `protoc`.

Two deliberate behaviours:

- **Hysteresis.** Collapse happens below `responsive_min_cols`, but restore only
  above `responsive_min_cols + 10`. Without that dead band, dragging a window edge
  that lands exactly on the threshold flips the layout on every motion event, and
  every flip resizes every PTY in the tab.
- **Manual arrangement wins.** Once you have rearranged panes yourself (what zellij
  calls a *damaged* swap layout), the responsive switch stops acting, on the same
  principle as upstream's `auto_layout`. An explicit arrangement outranks an
  automatic one. Note this includes opening a pane with an explicit direction
  (`NewPane "Right"`, `zellij action new-pane -d right`): that is an explicit
  arrangement, so a tab built that way will not collapse. A plain `NewPane` is
  not, and will.
- **Escaping the collapse is always possible.** "Damaged" is judged as of *before*
  each resize, because `resize_whole_tab`'s own auto-layout pass sets that flag
  itself and only clears it again if it found a layout that fits — on a very
  narrow terminal it may find none, which would otherwise look like a manual
  rearrangement that never happened. And once collapsed, restore stays reachable
  regardless, so damage occurring while collapsed cannot strand the tab in the
  narrow layout.

### Capping the stacked-pane picker

A stack reserves one row per member plus a padding row, so a deep stack spends
most of the screen listing itself. `stack_list_max_rows` caps it:

```kdl
ui {
    pane_frames {
        stack_list_max_rows 3        // default: 0 (show every member)
        stack_list_layout "grid"     // "rows" (default) | "grid"
    }
}
```

In `grid` mode entries are packed several per row, so the cap becomes a **space
budget** rather than a count: eight panes in a wide terminal fit on one row, and
`+N more` never appears. Cell width comes from the widest label, so the column
count adapts to the titles rather than being configured; long titles simply
yield fewer columns, and one column is the floor.

The list windows around the focused entry and reports the remainder as `+N more`
in the padding row it already reserves, so the indicator never costs a row or
steals one from a real entry. **Click that row to expand** the stack to its full
length; it becomes `- fewer`, which collapses it again. Entries keep their **real** position in the stack
rather than renumbering from 1, so the numbering still means something once the
window has scrolled. Ordinary focus movement slides the window, which is why
there is no separate binding for it.

Expansion is a click rather than hover on purpose: the row count feeds pane
geometry, so growing the list resizes the visible pane's PTY. Once per
deliberate click is fine — the same cost as any pane resize — whereas on hover
it would reflow a real terminal, and any full-screen program in it, on every
mouse move.

Nothing is unreachable while collapsed: the window slides as focus moves, so
the picker is a scrolling viewport rather than a truncation.

### Pane arrangements

A `children` placeholder normally inserts every pane as a **flat sibling**, which
is why a layout can only express "N equal columns", "N equal rows" or "one
stack" without hand-writing a variant per pane count (see the `max_panes=5` /
`max_panes=8` / `max_panes=12` ladders in a typical swap layout file). An
`arrangement` builds a tree for N panes instead:

```kdl
swap_tiled_layout name="grid" {
    tab min_panes=3 {
        pane arrangement="grid" {
            children
        }
    }
}

swap_tiled_layout name="master-stack" {
    tab min_panes=2 {
        pane arrangement="master-stack" {
            children
        }
    }
}
```

| arrangement | result |
|---|---|
| `grid` | roughly square: `ceil(sqrt(n))` columns, rows filled left to right (4 panes → 2x2, 5 → 3 then 2) |
| `master-stack` | one master pane taking 60% of the width, the rest stacked beside it |

Requires a `children` node (an arrangement has nothing to act on without one, so
omitting it is a config error rather than a silent no-op), and cannot be combined
with `stacked=true`.

It generates a `TiledPaneLayout` rather than geometry directly, so everything
downstream comes along for free: the minimum-size feasibility check, swap-layout
constraints, damage tracking, and the responsive collapse above. That last one
composes especially well — a grid is simply infeasible on a narrow terminal, so
it is skipped and the collapse takes over.

The arrangement has no protobuf representation (like `default_fg`/`default_bg`),
so plugins cannot set it and it does not survive a round trip through the plugin
API.

### Drag a pane title to rearrange it

Dragging a tiled pane by its title bar and dropping it on another pane swaps the
two, so panes can be rearranged with the mouse instead of only through MOVE mode.

The title bar EXCLUDING its corners is the move handle; the corners remain resize
handles, so two-axis resize from the top still works. Plain top-edge resize is gone,
which costs nothing in practice: every boundary is shared, so the boundary above a
pane is the bottom edge of the pane above it and can be dragged from there.

The reordering is previewed LIVE: the swap is actually applied as you drag, so the
real layout shows what you would get, and releasing simply keeps it. Dragging away
undoes the preview and restores the original arrangement. The pane being dragged
stays highlighted so it remains identifiable as the layout moves around it.

A drag that never leaves its own pane previews nothing, so a plain click still just
focuses and double-click-to-rename still works. Stacked panes are excluded — in a stack the
title row is how you focus a member.

### Double-click a pane title to rename it

Double-clicking the **top edge** of a pane's frame focuses that pane and drops
straight into rename mode — the same state the rename keybind produces.

Frame corners are excluded (they are resize handles), and a single click on the top
edge still starts the usual resize drag. Currently tiled panes only: on floating panes
the title is the drag handle for moving the pane, so that path is left alone for now.

Also in the fork, not configurable:

- Renaming a tab REPLACES the existing name on the first keystroke, the way a text
  field with its contents selected behaves, instead of appending to it. Backspace
  and delete count as editing rather than replacing, so they still work on the old
  name.

- A compact scroll indicator (`↑42`) in place of upstream's `SCROLL: 42/1000`, shown
  only when actually scrolled up rather than whenever scrollback exists.
- `sl0p.foo` branding in the default tab-bar plugin.

## Which changes apply live

`config.kdl` is watched, but only some things reach a running session:

| change | applies |
|---|---|
| `title_alignment`, `gap`, `padding`, `gap_aspect` | **live**, no restart |
| `responsive_min_cols`, `responsive_layout` | **live**, applies on the next resize |
| `rounded_corners`, and other stock options | **live** (upstream behaviour) |
| anything requiring a new binary | **new session** — a running server keeps its old inode |

## Building

Upstream's `[profile.release]` uses fat LTO and `codegen-units = 1`, which costs ~3
minutes for a one-line change. For iteration use the `fastdev` profile added here —
same `opt-level = 3`, no LTO, parallel codegen, incremental cache kept:

```bash
cargo build --profile fastdev -p zellij     # ~3s incremental  -> target/fastdev/zellij
cargo build --release -p zellij             # ~3min            -> ship this one
```

See `.fastfeedback/SPEED.md` for narrow test commands and measured timings.

The test suite is **green** (`cargo test -p zellij-server -p zellij-utils`), so any
failure is a real one. It was not always: the fork carried 35 failing snapshot tests
from its first commit until 5f2c28ab, because `aa51848d` changed the frame rendering
without refreshing the `insta` snapshots. If you change anything about how frames or
pane titles render, expect to regenerate snapshots — and read the diffs before
accepting them.

## Known rough edges

- **`gap` and `padding` only apply with `pane_frame_style "full"`.** With `"titles"` or
  `"none"` they are ignored: the cells around a pane's content there belong to the
  inter-pane boundary renderer (`ui/boundaries.rs`), and insetting into that region
  would leave cells nobody repaints (stale glyphs on resize) or paint over the
  boundaries themselves. Rather than half-apply, a frameless pane is simply not inset.
  Your config keeps its values; they just take effect if you switch back to full
  frames.
- **Floating panes** get `padding` but no `gap`: they are positioned explicitly, so an
  inter-pane gap does not apply.
- **Stacked panes** apply the gap uniformly; stack header spacing may look slightly off
  at larger gaps.
- **Responsive layouts need a swap layout with a matching name.** `responsive_layout`
  selects by name; if no swap layout has that name the tab silently stays as it is,
  with nothing logged. It is also column-only — there is no `responsive_min_rows`.
- The fork's options are **not** exposed over the plugin protobuf API. Plugins have no
  use for them and adding proto fields would mean regenerating the committed prost
  assets in `zellij-utils/assets/prost/`.

## Version string

Fork builds report a `+sl0pN` build-metadata suffix, so `zellij --version` is
distinguishable from upstream:

```
$ zellij --version
zellij 0.45.0+sl0p1
```

Build metadata rather than a `-sl0pN` prerelease on purpose: cargo ignores build
metadata when matching version requirements, so the intra-workspace
`zellij-utils = "0.45.0"` dependencies still resolve. A prerelease suffix does not,
and would require editing every member manifest.

Bump the suffix per published fork build; reset to 1 when rebasing onto a new
upstream release. Note that a version bump changes `ZELLIJ_PLUGIN_ARTIFACT_DIR`, so
the bundled wasm plugins are recompiled once on first run.

## Staying current with upstream

```
origin     ssh://git@git.sl0p.foo:39327/srv/git/sl0ppij.git   (this fork; main = fork work)
upstream   https://github.com/zellij-org/zellij.git           (vanilla)
```

The local `main` branch is kept clean on `upstream/main` so fork commits can be rebased
onto new Zellij releases.

---

<h1 align="center">
  <br>
  <img src="https://raw.githubusercontent.com/zellij-org/zellij/main/assets/logo.png" alt="logo" width="200">
  <br>
  Zellij
  <br>
  <br>
</h1>

<p align="center">
  <img src="https://raw.githubusercontent.com/zellij-org/zellij/main/assets/demo.gif" alt="demo">
</p>
<h4 align="center">
  [<a href="https://zellij.dev/documentation/installation">Installation</a>]
  [<a href="https://zellij.dev/screencasts/">Screencasts & Tutorials</a>]
  [<a href="https://zellij.dev/documentation/configuration">Configuration</a>]
  [<a href="https://zellij.dev/documentation/layouts">Layouts</a>]
  [<a href="https://zellij.dev/documentation/faq">FAQ</a>]
</h4>
<p align="center">
  <a href="https://discord.gg/CrUAFH3"><img alt="Discord Chat" src="https://img.shields.io/discord/771367133715628073?color=5865F2&label=discord&style=flat-square"></a>
  <a href="https://matrix.to/#/#zellij_general:matrix.org"><img alt="Matrix Chat" src="https://img.shields.io/matrix/zellij_general:matrix.org?color=1d7e64&label=matrix%20chat&style=flat-square&logo=matrix"></a>
  <a href="https://zellij.dev/documentation/"><img alt="Zellij documentation" src="https://img.shields.io/badge/zellij-documentation-fc0060?style=flat-square"></a>
</p>

<br>
    <p align="center">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/bc5daac4-140a-4b83-8729-71c944ee1100">
      <img src="https://github.com/user-attachments/assets/55156624-a71a-46b5-939e-f562e3b2dd7f" alt="Sponsored by ">
    </picture>
    &nbsp;
    &nbsp;
    <a href="https://www.gresearch.com/">
        <picture>
          <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/d609936a-abf8-4406-8cfc-889f76a09d74">
          <img src="https://github.com/user-attachments/assets/742ae902-fe9d-41c6-baf2-4bc143061da3" alt="gresearch logo">
        </picture>
    </a>
</p>

# What is this?

[Zellij](#origin-of-the-name) 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](https://zellij.dev/documentation/layouts.html), true multiplayer collaboration, unique UX features such as floating and stacked panes, and a [plugin system](https://zellij.dev/documentation/plugins.html) allowing one to create plugins in any language that compiles to WebAssembly.

Zellij includes a built-in [web-client](https://zellij.dev/tutorials/web-client/), making a terminal optional.

You can get started by [installing](https://zellij.dev/documentation/installation.html) Zellij and checking out the [Screencasts & Tutorials](https://zellij.dev/screencasts/).

For more details about our future plans, read about upcoming features in our [roadmap](#roadmap).

## How do I install it?

The easiest way to install Zellij is through a [package for your OS](./docs/THIRD_PARTY_INSTALL.md).

If one is not available for your OS, you could download a prebuilt binary from the [latest release](https://github.com/zellij-org/zellij/releases/latest) and place it in your `$PATH`. If you'd like, we could [automatically choose one for you](#try-zellij-without-installing).

You can also install (compile) with `cargo`:

```
cargo install --locked zellij
```

#### Try Zellij without installing

bash/zsh:
```bash
bash <(curl -L https://zellij.dev/launch)
```
fish/xonsh:
```bash
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](CONTRIBUTING.md).

## Configuration
For configuring Zellij, please see the [Configuration Documentation](https://zellij.dev/documentation/configuration.html).

## 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***

[![roadmap](https://github.com/user-attachments/assets/bb55d213-4a68-4c84-ae72-7db5c9bf94fb)](https://zellij.dev/roadmap)

## Origin of the Name
[From Wikipedia, the free encyclopedia](https://en.wikipedia.org/wiki/Zellij)

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
<a href="https://terminaltrove.com/"><img src="https://avatars.githubusercontent.com/u/121595180?s=200&v=4" width="80px"></a>