# 3mux: A Terminal Multiplexer With i3 Keybindings and Mouse Resize

> 3mux is a Go terminal multiplexer that borrows pane management from i3 and adds search, scrollback and mouse-driven resizing on top of a tmux-like base. It suits keyboard-oriented terminal users, and it is a weak substitute for anyone who needs tmux's session scripting and plugin surface.

**aaronjanse/3mux** — Terminal multiplexer inspired by i3

- Repository: https://github.com/aaronjanse/3mux
- Stars: 1,854 · Forks: 47
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/aaronjanse-3mux

## What 3mux Sets Out to Be

3mux is a terminal multiplexer written in Go whose stated inspiration is the i3 window manager. The pitch is tmux with a smaller learning curve and friendlier defaults, and the feature list is where that claim gets tested: session management that is optionally interactive and self-documenting, search, scrollback, and mouse support that covers dragging to resize panes, clicking to select a pane, and the scroll wheel.

The audience is a terminal user who splits panes constantly and already thinks in directional terms. Instead of a command prefix plus a submenu, 3mux uses Alt plus a direction to move focus, and Alt plus a letter as the equivalent of the same gesture. That is a deliberate narrowing of scope: this is a window manager for the terminal, not a session orchestrator for servers.

It ships under the MIT licence, so the code can be read, modified and redistributed with attribution. The repository is not archived, and the last push was on 2026-07-06.

## Alt Plus a Direction Replaces the tmux Command Prefix

The key table is short enough to memorise in a minute. Alt+Enter or Alt+N creates a pane. Alt+h, Alt+j, Alt+k and Alt+l select an adjacent pane, and the arrow keys do the same thing. Alt+Shift with the same set moves the selected pane instead of focusing it, which is the gesture i3 users reach for when rearranging a layout.

Two modes sit outside the normal flow. Alt+R enters resize mode, where arrow keys or h/j/k/l change the size of the selected pane and any other key exits. Alt+/ enters search mode, where you type a query and step between hits with the arrow keys or n and N. Alt+Shift+F makes the selected pane fullscreen, described as useful for copying text.

The mode design is worth noting because the exit condition is loose. A resize mode ends on any other key, which means a stray keystroke can end it, and search mode relies on the same n/N stepping used by tools like less. The documentation states that modifiers in shortcuts are case-insensitive, so Alt and alt behave the same way.

## Mouse Drag, Click Select, and Wheel Scrollback

Mouse support is the part that separates 3mux from a bare command-line multiplexer, and the three behaviours are named separately: drag to resize a pane, click to select a pane, and scrollwheel to move through scrollback. Each of those is a common source of friction in tmux, where resizing usually means a sequence of prefix keys and a prompt, and where scrollback is typically reached through a copy mode with its own key set.

The README also points out that many terminal emulators already support selecting text while holding Shift, which means text selection does not require going through the multiplexer at all. Combined with the fullscreen shortcut, the design intent is that copying a block out of a pane is a two step operation rather than a mode switch.

Scrollback and search are both listed as built-in features, with search operating over what is on screen and in the buffer. The documentation does not describe how the search index is built, how large the retained buffer is, or whether search can reach output that has already been rotated out of view, so the practical limit of the search is not something you can read off the documentation.

## Three Installation Routes: Homebrew, Nix Flakes, go get

The README gives three ways to install 3mux. Homebrew is the shortest, and it also runs a package index update first:

```bash
brew update
brew install 3mux
```

Nix flakes are the second route, and the documentation marks it as requiring Nix 2.4 or newer. It runs the project straight from GitHub without a local install:

```bash
nix run github:aaronjanse/3mux
```

Building from source is the third. You install Golang, fetch the module, and run the binary:

```bash
go get github.com/aaronjanse/3mux
```

Running 3mux launches the multiplexer. The module path and the go get invocation are the same string, which makes the source route easy to script but also ties you to a module layout that declares go 1.14 in go.mod. Upgrading follows the same pattern:

```bash
go get -u github.com/aaronjanse/3mux
```

A repology badge is also shown for 3mux, which points at the packaged versions available across Linux distributions.

## Config Lives Under XDG_CONFIG_HOME, Not in a Dotfile You Can Guess

3mux searches XDG_CONFIG_HOME for its configuration. If that search fails, the project writes a config to a default path on the first run:

```text
~/.config/3mux/config.toml
```

The file format is TOML, which matches the BurntSushi/toml dependency in go.mod. The behaviour of writing a default file on first run is convenient in the sense that you do not have to create anything before launching, and it is also a way to discover the available keys: the generated file is where the defaults live. The flip side is that the shortcut list you can edit is the same list the program already imposes, and the documentation does not spell out which keys can be rebound, only that modifiers in shortcuts such as Alt are case-insensitive.

For scripts, there is a small detection hook. A shell can test whether the THREEMUX environment variable equals 1 to know it is running inside a multiplexer, and can branch its output behaviour accordingly.

## The Go Package Layout Behind the Terminal Interface

The repository is organised as a set of Go packages whose names describe the layers of the problem. At the top level sit main.go, config.go, input.go, help.go, attach.go and serve.go. Alongside them are directories for pane handling, rendering, virtual terminals handling under vterm/, the window manager under wm/, terminal escape sequence handling under ecma48/, and a fuzz directory.

That layout explains a design choice that the README does not call out. 3mux keeps its own window manager package, which is consistent with an i3-derived model where the program owns the layout of the screen rather than delegating it to the shell, and the vterm and ecma48 directories indicate that virtual terminal state and escape sequence parsing are handled internally rather than borrowed from another project.

Dependencies are modest and mostly focused: a TOML parser, an XDG lookup helper, a pty library, a terminal width calculator, a poller for input, and a daemonisation helper. A fuzz directory in the tree points at input parsing as an area that gets adversarial attention, which fits a program that reads raw key sequences and escape codes.

## tmux and screen Bindings Are a Compatibility Layer, Not a tmux Clone

3mux implements a small set of tmux and screen bindings, and the tables are labelled Supported tmux Bindings and Supported screen Bindings, which is careful wording for what is actually a short compatibility list. From tmux, Ctrl+b followed by the double quote splits horizontally, percent splits vertically, and the brace characters move the pane left or right. From screen, Ctrl+a followed by the pipe splits horizontally, Ctrl+a S splits vertically, and Ctrl+a Tab cycles forward through panes.

That is the full extent of the compatibility as documented. There is no mention of tmux configuration file parsing, scripting with tmux commands, detached or persistent server sessions, or a plugin system, so 3mux should be read as an independent multiplexer with a handful of familiar chords, not as a drop-in replacement for a configured tmux.

The related project linked from the README is tmux-tilish, which points at tmux in general rather than at a competing implementation of this design. If your workflow is built on tmux config files and shared session scripts, that difference matters more than the shared key chords.

## Where 3mux Stops Working: Terminal.app and an Old Release Trail

There is a documented platform limit. Arrow-key-controlled pane management is currently unsupported on Terminal.app, and the project tells you to use the default vim-like keybindings there instead. The fix on macOS is a preferences change rather than a code change: in Terminal.app you enable Use Option as Meta Key under Preferences, Profiles, Keyboard, and in iTerm2 you set Option Key to Esc+ under Preferences, Profiles, Keys. If you skip that step, the Alt based shortcuts that make up the core of the interface will not arrive at the program, and the failure looks like 3mux ignoring the keyboard.

The release history is the second constraint worth weighing. The newest tagged release is v1.1.0, dated 2021-03-13, with v1.0.1 and v1.0.0 dating to May 2020. The repository is not archived and the last push was on 2026-07-06, so work is still landing in the tree, but the gap between that push and the most recent tag is long enough that a version pinning exercise is worth doing before you point your build at it.

## Conclusion

3mux suits terminal users who want i3-style pane movement, built-in search and mouse resizing without learning a tmux command language, and it is a poor fit for anyone who depends on tmux scriptability, detached sessions or plugins, since only a handful of tmux bindings are listed as supported. Before adopting it, confirm that your terminal emulator can send Option as Meta, because the documentation flags Terminal.app as unsupported for arrow-key pane management, and weigh that against the release trail, where the newest tag is v1.1.0 from 2021-03-13 and the last push was on 2026-07-06.

## FAQ

### How do I install 3mux?

The README gives three routes: `brew install 3mux` on macOS with Homebrew, `nix run github:aaronjanse/3mux` with Nix 2.4 or newer, or building from source with `go get github.com/aaronjanse/3mux` after installing Golang. Running 3mux launches the multiplexer.

### Where does 3mux store its configuration file?

3mux searches XDG_CONFIG_HOME for its config, and if it cannot find one it writes a config to `~/.config/3mux/config.toml` on the first run. The file is TOML format, matching the BurntSushi/toml dependency in go.mod.

### Does 3mux work on Terminal.app?

Partly. The project states that arrow-key-controlled pane management is currently unsupported on Terminal.app and asks you to use the default vim-like keybindings instead. Enabling Use Option as Meta Key under Preferences, Profiles, Keyboard is what allows the Alt shortcuts to reach the program.

### How can a script tell that it is running inside 3mux?

Check whether the THREEMUX environment variable is equal to 1. The README states that this is how you can detect running inside 3mux.

### Can I use tmux keybindings in 3mux?

Only a few. The listed tmux bindings are Ctrl+b with double quote to split horizontally, Ctrl+b with percent to split vertically, and Ctrl+b with the brace characters to move the pane left or right. Screen bindings cover Ctrl+a with the pipe, Ctrl+a S, and Ctrl+a Tab.

## Sources

- [aaronjanse/3mux on GitHub](https://github.com/aaronjanse/3mux)
- [Issues](https://github.com/aaronjanse/3mux/issues)
- [License: MIT](https://github.com/aaronjanse/3mux/blob/master/LICENSE)
- [README](https://github.com/aaronjanse/3mux/blob/master/README.md)
- [Releases](https://github.com/aaronjanse/3mux/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aaronjanse-3mux