Docs
gmux is a tmux + Ghostty configuration for running coding agents, dev servers, and shells in one workspace. The whole stack is dotfiles and shell scripts — read everything before you run it at github.com/OndrejDrapalik/gmux.
Quick start
One line. The script clones the repo to ~/.gmux, backs up any tmux config it would touch, and symlinks the dotfiles:
curl -fsSL https://gmux.sh/install.sh | sh
Prefer doing it by hand? Same result:
git clone https://github.com/OndrejDrapalik/gmux.git cd gmux mkdir -p ~/.tmux ~/.config/zsh ln -sf "$(pwd)/dotfiles/tmux.conf" ~/.tmux.conf ln -sf "$(pwd)/dotfiles/tmux/base.conf" ~/.tmux/base.conf ln -sf "$(pwd)/dotfiles/tmux/keys-gmux.conf" ~/.tmux/keys-gmux.conf ln -sf "$(pwd)/dotfiles/tmux/keys-vanilla.conf" ~/.tmux/keys-vanilla.conf rm -rf ~/.tmux/scripts cp -R dotfiles/tmux/scripts ~/.tmux/scripts chmod +x ~/.tmux/scripts/*.sh
Then start tmux normally. To keep stock tmux keybindings with the same status bar and observability layer:
GMUX_FLAVOR=vanilla tmux
Optional Ghostty and zsh files (Cmd-key passthrough, theme, fzf-tab styling):
cp ~/.gmux/dotfiles/config/ghostty/config ~/.config/ghostty/config cp ~/.gmux/dotfiles/config/zsh/fzf-tab-config.zsh ~/.config/zsh/fzf-tab-config.zsh
What's inside
Agent working indicators (a window tab spins only while an agent is actually working), a live port watcher that maps dev servers to windows, safe pane refresh that skips agents and servers, and layout helpers, all driven by tmux variables and shell scripts. Two small shell watchers keep those variables fresh; kill them anytime, your sessions live in tmux itself.
The agent detector recognizes 12 harnesses by process tree and screen text: Claude Code, Codex CLI, Gemini CLI, opencode, Cursor Agent, Copilot CLI, Amp, Droid, Grok CLI, Kiro, Kimi CLI, and Cline.
| dotfiles/tmux.conf | Entry point sourcing the base and selected keybinding flavor |
| dotfiles/tmux/base.conf | Theme, status bar, hooks, plugins, port watcher, agent spinner |
| dotfiles/tmux/keys-gmux.conf | Opinionated C-Space keybinding flavor |
| dotfiles/tmux/keys-vanilla.conf | Stock C-b flavor — same observability layer |
| dotfiles/tmux/scripts/ | Agent detection, spinner, port watcher, layout helpers |
| dotfiles/config/ghostty/config | Optional: Cmd-key to tmux Meta passthrough, theme |
Keybinds
Highlights from the gmux flavor (prefix = C-Space). Ghostty shortcuts bypass the prefix entirely by sending Meta sequences tmux binds directly.
| Prefix | C-Space | Easier thumb reach than C-b |
| New window | prefix t | t for tab |
| Navigate panes | prefix h/j/k/l | Vim-style movement |
| Refresh panes | prefix r | Skips running agents and dev servers |
| Work layout preset | prefix 8 | Editor / terminal / full-height right pane |
| Grab scrollback | prefix g | Copy entire scrollback to clipboard |
| Prev / next window | Cmd+1 / Cmd+2 | From Ghostty, no prefix needed |
| Move focus | Cmd+H/J/K/L | From Ghostty, no prefix needed |
The full keybinding tables — remapped keys, layout presets, session save/restore — live in the README.
Make it yours
gmux is meant to be forked, not depended on. Everything is plain tmux config and POSIX shell — change the theme, rebind keys, delete what you don't use. Tools come and go; your tmux.conf survives.
gh repo fork OndrejDrapalik/gmux --clone
Test changes in a sandbox before touching your real setup:
docker build -t gmux-test . docker run -it --rm gmux-test # gmux flavor docker run -it --rm gmux-test vanilla # vanilla flavor