# tmux-config: a worked example of a tmux setup, with the reasoning left in

> tony/tmux-config is not a plugin and not a package. It is a .tmux.conf, a vendored copy of tmux-mem-cpu-load and a README that explains every key binding, which makes it useful as a starting point to edit rather than a dependency to install.

**tony/tmux-config** — :green_book: Example tmux configuration - screen + vim key-bindings, system stat, cpu load bar.

- Repository: https://github.com/tony/tmux-config
- Website: http://tony.github.com/tmux-config/
- Stars: 1,873 · Forks: 470
- Language: Shell
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/tony-tmux-config

## A configuration file with an explanation attached

The repository description calls itself an example tmux configuration, with screen and vim key-bindings, system stat and a cpu load bar, and the README opens by reminding the reader that tmux is a terminal multiplexer.

That framing is the point. There is no package to install, no plugin manager entry and no release. The repository is a .tmux.conf at the top level, an install.sh, a vendor directory holding a submodule, and a README.

The README is what makes it more than a file to copy. Every binding is listed with the sequence to type and what it does, the reload command is given, and the setup for the status bar is written out as a series of steps rather than assumed. A person reading it learns not only what this configuration does but why the choices were made, which is the difference between a configuration and an example of one.

The licence is MIT, with the README stating LICENSE: MIT, and the author is Tony Narlock. The last push to the repository was on 2026-05-24, and there are no GitHub releases, which is consistent with a repository whose deliverable is a file rather than a versioned artefact.

The audience is a developer setting up tmux, or a developer who has a working setup and wants to see how somebody else solved the status line, the keymap and the window layout.

## The prefix is Ctrl-A, and the reason is screen

One decision runs through the whole keymap, and the README explains it in a single line: the prefix is mapped to Ctrl-A for screen users.

The prefix is the key you press before any tmux shortcut, and changing it away from the default Ctrl-B is a matter of taste and of muscle memory. Choosing Ctrl-A means the configuration is immediately usable by somebody who spent years in GNU screen, where Ctrl-A was the prefix. The README says this sequence must be typed before any tmux shortcut, which is the part newcomers get wrong, and it is stated early.

Beyond the prefix, the bindings are a hybrid of the two traditions the description mentions, screen and vim. The window and pane operations follow the screen layout, with a double quote to split the window horizontally and v to split it vertically, and the movement keys follow vim, with h, j, k and l moving left, down, up and right.

There is also a deliberate choice in the confusing pair. A configuration that mixes screen and vim idioms has to settle on one convention for splitting, and this one uses a double quote for a horizontal split and v for a vertical one.

The full list is short enough to read in a minute, and that is the argument for looking at this repository rather than at a generic default configuration. The set includes a quick-action menu on space, pane rotation on o, a jump to the last panel on semicolon, window creation on c, window switching on n and p, jumping to a numbered window, and killing a window with an ampersand.

## The status bar needs a binary you compile yourself

The system stat and cpu load bar in the description come from tmux-mem-cpu-load, and the README is explicit that this is support for that tool rather than something built in.

The build is a short sequence, and the README covers the mistake most people make, which is forgetting the --recursive flag on the clone and then finding the vendor directory empty. If that happened, the fix is git submodule init followed by git submodule update. Then you move into the vendored directory, create a _build directory and change into it, run cmake to generate the makefiles, run make to compile, and install the binary with sudo make install, which puts it at /usr/local/bin/tmux-mem-cpu-load. The README notes that the sudo is not needed on OS X or macOS.

The whole thing works on Linux and OS X, and the install step needs a C toolchain, cmake and make. That is a real cost for a status bar, and it is the price of the tool the configuration depends on.

The installation of the configuration itself is correspondingly simple, and the README splits it into three steps, each in its own block. You clone the repository with --recursive into a dot directory in your home, you symlink the configuration file to your home directory, and you change into the configuration directory.

```bash
git clone --recursive https://github.com/tony/tmux-config.git ~/.tmux
ln -s ~/.tmux/.tmux.conf ~/.tmux.conf
cd ~/.tmux
```

The symlink is the detail worth noticing, because it is what makes the configuration editable in place and updatable with a git pull, rather than being a copy that drifts from the upstream file.

## tmux 3.2 features are used without ceremony

The configuration uses several features that only exist in recent tmux, and the README marks them as such.

It requires tmux 3.2 or later, with the best experience on 3.4 or later. The bindings that depend on the newer version are the popup shell on t, which opens a shell in a window covering 80% of the screen, and the popup on g, which shows git log --oneline --graph. Both are annotated with 3.2+ in the README, so somebody on an older tmux will know why they do not work.

The layout bindings are documented as well. m switches to the main-horizontal layout with the main pane at 66% of the height, and M switches to main-vertical with the main pane at 50% of the width.

Two more modern conveniences appear in the usage section. A popup for a git log is bound to g, and the reload command is tmux source-file ~/.tmux.conf, which applies changes to a running session without restarting tmux. The README gives the interactive form as well, Control and a followed by a colon and then source-file ~/.tmux.conf, for when the command line is not convenient.

The starting, attaching and detaching commands are the plain ones: tmux to start a session, tmux attach to reattach an existing one, and Control and a followed by d to detach. And there is an optional powerline section for people who want the fancier status line, which requires adding configuration to ~/.tmux.conf and installing powerline fonts for the system, since the glyphs will not render correctly without them.

## The rest of the author's tools are the natural companions

The README does not stop at tmux, and the surrounding projects are the reason this repository sits in a family rather than alone.

The main one is tmuxp, for saving and loading tmux workspaces through JSON or YAML. That is the piece most people adopt alongside a configuration, because a keymap covers the keys you press and tmuxp covers the sessions you work in, and the two solve different problems.

Then there is libtmux, a Python library for controlling tmux, which is the scripting layer, for the case where a script needs to create a session, send keys, or read a pane's output. And vcspull, for cloning and synchronising git, hg and svn projects through JSON or YAML, which uses the same declarative file idea for source control that tmuxp uses for workspaces.

The author also maintains vim-config, described as a modular, lazy-loading vim configuration with support for C, C++, Python, Go and JavaScript, and a modular dot-config example. The .dot-config approach is the idea underneath all of it: a configuration split into small pieces that are loaded on demand rather than one large file that has to be edited as a unit.

There is also a community mechanism. If you have a tmux configuration you would like to share, whether a fork of this project, someone else's, or your own, the README asks you to submit it to awesome-tmux-configs. The repository is presented as one example in a collection, and that framing is the honest one: this is a working configuration that other people are meant to fork, edit and contribute back.

## Conclusion

tmux-config fits a developer who wants a working tmux setup with a status bar and a documented keymap to start from, and who is comfortable editing a configuration file. It does not fit a team looking for a managed tmux layer with defaults, plugins and updates, because nothing here is packaged or versioned beyond the repository itself. Before you adopt it, read the key binding list and check that the Ctrl-A prefix and the screen-style splits do not clash with what you already use, and build the tmux-mem-cpu-load binary if you want the status bar, since the config assumes it is installed at /usr/local/bin.

## FAQ

### How do I install the tony/tmux-config configuration?

Clone the repository recursively into ~/.tmux with git clone --recursive, symlink the configuration with ln -s ~/.tmux/.tmux.conf ~/.tmux.conf, and change into the directory. The README also covers building the vendored tmux-mem-cpu-load binary that the status bar needs, using cmake and make, and installing it to /usr/local/bin.

### Which tmux version does this configuration need?

It requires tmux 3.2 or later, with the best experience on 3.4 or later. The popup shell on t and the git log popup on g depend on 3.2 features, and the README marks both with 3.2+.

### What is the prefix key in this tmux configuration?

It is Ctrl-A, mapped that way for screen users, and it must be typed before any tmux shortcut. The window and pane operations follow the screen convention, splitting horizontally with a double quote and vertically with v, while pane movement uses the vim keys h, j, k and l.

### How do I reload the tmux configuration after editing it?

Run tmux source-file ~/.tmux.conf, or from inside tmux press Control and a followed by a colon and then the same source-file command. The README lists the update command in its own section, next to the instructions for starting and attaching sessions.

### What other tools does the author recommend alongside this configuration?

tmuxp for saving and loading workspaces through JSON or YAML, libtmux as a Python library for controlling tmux, vcspull for cloning and synchronising git, hg and svn projects through JSON or YAML, and a modular, lazy-loading vim configuration.

## Sources

- [Issues](https://github.com/tony/tmux-config/issues)
- [Project website](http://tony.github.com/tmux-config/)
- [README](https://github.com/tony/tmux-config/blob/master/README.md)
- [tony/tmux-config on GitHub](https://github.com/tony/tmux-config)

---

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