https://github.com/dohwi/tmux-manager
TUI tool for tmux session management — browse, create, switch, kill sessions. Define pane layouts in YAML and restore workspaces on reboot.
https://github.com/dohwi/tmux-manager
bubbletea cli go tmux tui yaml
Last synced: 4 days ago
JSON representation
TUI tool for tmux session management — browse, create, switch, kill sessions. Define pane layouts in YAML and restore workspaces on reboot.
- Host: GitHub
- URL: https://github.com/dohwi/tmux-manager
- Owner: dohwi
- License: mit
- Created: 2026-05-31T12:10:20.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-06-17T16:29:49.000Z (8 days ago)
- Last Synced: 2026-06-17T16:56:27.251Z (8 days ago)
- Topics: bubbletea, cli, go, tmux, tui, yaml
- Language: Go
- Size: 465 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# tmux-manager
**TUI session manager for tmux — define workspaces in YAML, restore on reboot.**
[](https://github.com/dohwi/tmux-manager/actions/workflows/ci.yml)
[](https://github.com/dohwi/tmux-manager/releases)
[](https://goreportcard.com/report/github.com/dohwi/tmux-manager)
[](LICENSE)
---
## ✨ Features
- 🎯 **Keyboard-driven TUI** — browse, create, and kill sessions in seconds
- 📄 **YAML workspaces** — define sessions, windows, and pane layouts as code
- 🔄 **Auto-restore** — `tm restore` brings your workspace back after reboot
- 🏷️ **cfg tag** — visually distinguish YAML-managed sessions from manual ones
- 🎨 **Catppuccin Mocha theme** — soft pastel status bar, easy on the eyes
- ⚡ **One-command install** — Go, tmux, shell integration, all set up automatically
---
## 📸 Screenshot
---
## 🚀 Quick Start
```bash
curl -fsSL https://raw.githubusercontent.com/dohwi/tmux-manager/main/install.sh | bash
```
That's it. This command:
1. Installs Go (if missing)
2. Builds `tmux-manager` from the latest release
3. Runs `tm setup` — installs tmux (if missing), configures shell integration, status bar, and auto-restore
After installation, just run `tm` in a new terminal.
---
## 📦 Commands
```bash
tm # Launch TUI
tm restore # Restore sessions from YAML
tm restore --dry-run # Preview what would be restored
tm setup # Install symlink and shell integration
tm setup --uninstall # Remove all integration
tm update # Update to the latest release
tm update --check # Check for updates without installing
tm version # Print version
```
### ⌨️ Keybindings
| Key | Action |
|:---:|:-------|
| `↑` `↓` `j` `k` | Navigate sessions |
| `Enter` | Attach to session |
| `Ctrl+N` | Create new session |
| `Ctrl+R` | Rename session |
| `Ctrl+D` | Delete session |
| `Ctrl+C` | Quit |
---
## ⚙️ Configuration
Workspace definitions go in `~/.config/tmux-manager/sessions/*.yaml`.
### Single pane
```yaml
sessions:
monitoring:
windows:
- panes:
- command: htop
```
### Side-by-side
```yaml
sessions:
dev:
windows:
- panes:
- command: nvim
directory: ~/projects/myapp
- command: lazygit
direction: right
directory: ~/projects/myapp
```
```
┌────────────┬──────────┐
│ nvim │ lazygit │
└────────────┴──────────┘
```
### Complex layout
```yaml
sessions:
dev:
windows:
- panes:
- command: nvim
directory: ~/projects/myapp
- command: lazygit
direction: right
directory: ~/projects/myapp
- command: npm run dev
direction: down
directory: ~/projects/myapp
```
```
┌────────────┬──────────┐
│ │ lazygit │
│ nvim ├──────────┤
│ │ npm run │
│ │ dev │
└────────────┴──────────┘
```
### Multi-window
```yaml
sessions:
myapp:
windows:
- name: code
panes:
- command: nvim
directory: ~/projects/myapp
- command: lazygit
direction: right
directory: ~/projects/myapp
- name: infra
panes:
- command: docker-compose up
directory: ~/projects/myapp
- command: docker logs -f
direction: down
directory: ~/projects/myapp
```
### Multiple sessions
```yaml
sessions:
dev:
windows:
- panes:
- command: nvim
directory: ~/projects/myapp
- command: lazygit
direction: right
db:
windows:
- panes:
- command: psql myapp
directory: ~/projects/myapp
```
### Field Reference
| Field | Required | Description |
|:------|:--------:|:------------|
| `sessions` | ✅ | Map of session names to window definitions |
| `sessions[].windows` | | Window list (default: one empty window) |
| `sessions[].windows[].name` | | Window tab name |
| `sessions[].windows[].panes` | | Pane layout within the window |
| `panes[].command` | | Command to run in the pane |
| `panes[].directory` | | Working directory (`~/` supported) |
| `panes[].name` | | Pane title |
| `panes[].direction` | | Split direction: `right` or `down` (omit for first pane) |
---
## 🏷️ cfg Tag
YAML-managed sessions appear with a `cfg` label in the TUI, so you can tell them apart from manually created ones.
```
○ good-giraffe-drawing
detached
○ myapp-dev
1 windows cfg
◉ tmux-manager
attached cfg
```
---
## 🔄 Auto-Restore
`tm setup` adds this to `~/.profile`:
```bash
tm restore 2>/dev/null
```
After a reboot, SSH login automatically restores your YAML-defined sessions. Existing sessions are skipped (idempotent).
---
## 🛠️ What `tm setup` Configures
| Path | Purpose |
|------|---------|
| `~/.local/bin/tm` | Symlink to the binary |
| `~/.zshrc` | `nocorrect tm` alias |
| `~/.profile` | `tm restore` for auto-restore on login |
| `~/.config/tmux-manager/` | Config directory |
| `~/.config/tmux-manager/sessions/` | YAML workspace definitions |
| `~/.config/tmux-manager/tmux.conf` | Catppuccin Mocha status bar + keybindings |
| `~/.tmux.conf` | Sources tmux-manager config |
---
## 📋 Requirements
- **tmux** ≥ 3.2 (auto-installed by `tm setup`)
- **Go** ≥ 1.24 (auto-installed by install script)
- **Linux** or **macOS**
---
## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and pull requests welcome.
## 📄 License
[MIT](LICENSE) © 2024–2026 dohwi