A tiling window manager for the terminal.

What it does

A daily driver: every milestone of the roadmap is done. Six panels, the way the README groups them.

1 · tiling

Panes place themselves.

Dwindle splits the focused pane along its longer side, like Hyprland. Or group panes into tabs, float one over the tiling, keep a scratchpad, or lay a workspace out as niri's strip of scrolling columns. Window rules and saved layouts on top.

2 · sessions

Close the terminal. Nothing closes.

ranma runs as a server: closing the terminal, or losing SSH, only detaches, and ranma again picks up where you were. Workspaces and sessions with fuzzy switchers. An upgrade moves running servers to the new build without closing anything.

3 · copy mode

Copy from history, over SSH too.

Copy mode is alacritty's vi mode, with history search. What you yank reaches the system clipboard by OSC 52, from a pane on the far side of an SSH connection as well. Files paste into a pane that runs ssh.

4 · images and keys

The kitty protocols, both of them.

Images draw in panes with the kitty graphics protocol. The kitty keyboard protocol works both ways, so a program asking for exact keys gets them. Outside WM mode bytes pass through raw; a paste is trusted to bracketed paste, not guessed.

5 · the bar

waybar's shape, without waybar's config.

Modules in Lua or shell, left, centre and right. Run ranma inside ranma and the nested ones share the outer bar rather than stack their own. Toasts from ranma notify when a build finishes.

From the screenshot's configuration, below.

6 · mobile

A phone can drive it.

While a phone drives the screen, ranma switches to a mobile view built from scriptable pieces. And it runs on the phone itself, in Termux.

Configured in Lua, themed in TOML.

The configuration behind the screenshot, as it is in doc/examples/screenshot. Lua for behaviour, TOML for looks. Both are parsed strictly: a name ranma doesn't know is an error that names it.

10
11
12
13
14
15
16
17
18
 ⋯
33
34
35
36
37
38
39
40
41
42
43
44
45
46

ranma.set { theme = "sumi" } -- themes/sumi.toml, beside this file

-- The left pill: a fixed label. The built-in `session` module would show the
-- session's name, but only once there is more than one session.
ranma.module("label", {
  render = function()
    return { text = "ranma", style = "accent" }
  end,
})
⋯
ranma.module("cpu", { format = "\u{f4bc} %s" }) -- nf-oct-cpu
ranma.module("mem", { format = "\u{f035b} %s" }) -- nf-md-memory
ranma.module("clock", {
  interval = 60,
  render = function()
    return "\u{f43a} " .. os.date("%H:%M") -- nf-oct-clock
  end,
})

ranma.bar {
  left = { "label", "workspaces" },
  center = { "pane_strip" },
  right = { "cpu", "mem", "host", "clock" },
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 ⋯
46
47
48
49
50
51

# sumi — ink, washi paper and hinoki wood. The airy variant.
#
#   ink      #141317  ground            washi    #e8e1d3  text
#   hinoki   #d9a55b  focus / accent    ai       #7b93c9  floats, tabs
#   shu      #e0533d  WM mode / urgent  matcha   #9db37a  occupied
#   kasumi   #6e665c  dim               sumi-2   #2a2724  module pills

[colors]
border_active = "#d9a55b" 
border_inactive = "#3a3631" 
border_floating = "#7b93c9" 
bar_bg = "default"
bar_fg = "#e8e1d3" 
bar_dim = "#6e665c" 
bar_accent = "#d9a55b" 
bar_urgent = "#e0533d" 
⋯
[border]
style = "rounded"
floating_style = "double"
title = "top"
title_align = "left"
title_format = " {index} · {title} "

Why not tmux, zellij or tuios?

They are good, and you may want one of them instead. ranma gets where it is mostly by refusing scope, not by out-engineering anyone.

Linux (x86_64, aarch64), macOS (Apple silicon, Intel) and Android in Termux (aarch64), into ~/.local. Run it again to update; it checks the new binary against your config and moves running servers onto it.

Or with a package manager

Every channel ships the same release binary, except cargo install and Nix, which build it.

• Arch (AUR)

  x86_64, maintained by Rafael Dominiquini
  ranma-bin
• Homebrew

  macOS, Linux
  brew install masshirodev/tap/ranma
• Nix

  or the flake’s packages.<system>.default / overlays.default
  nix run github:masshirodev/ranma
• Rust, the binary

  cargo-binstall
  cargo binstall ranma
• Rust, built

  Rust 1.88+ and a C compiler
  cargo install ranma
• npm

  Node stays running beside each client
  npm install -g @masshirodev/ranma
• By hand

  tarballs, .deb and .rpm on each release
  https://github.com/masshirodev/ranma/releases

sudo install -d /etc/apt/keyrings
curl -fsSL https://masshirodev.github.io/ranma/ranma.asc | sudo tee /etc/apt/keyrings/ranma.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/ranma.asc] https://masshirodev.github.io/ranma/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/ranma.list
sudo apt update && sudo apt install ranma

sudo curl -fsSL -o /etc/yum.repos.d/ranma.repo https://masshirodev.github.io/ranma/ranma.repo
sudo dnf install ranma
# openSUSE:
sudo zypper addrepo https://masshirodev.github.io/ranma/ranma.repo && sudo zypper install ranma