tmux-manager

README

tmux-manager

TUI session manager for tmux — define workspaces in YAML, restore on reboot.

---

Why tmux-manager?

You already manage tmux sessions manually — creating, naming, splitting panes, running the same commands every time you reboot. tmux-manager automates all of that.

• Browse sessions in a keyboard-driven TUI
• Define workspaces in YAML — sessions, windows, pane splits, commands
• Restore everything on boot with tm restore
• One-command install — sets up Go, tmux, shell integration, and status bar

Screenshot

Install

curl -fsSL https://raw.githubusercontent.com/dohwi/tmux-manager/main/install.sh | bash

This single 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.

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

Update

tm update           # Update to the latest release
tm update --check   # Check for updates without installing

Usage

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 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 window, single pane

sessions:
  monitoring:
    windows:
      - panes:
          - command: htop

Side-by-side split

sessions:
  dev:
    windows:
      - panes:
          - command: nvim
            directory: ~/projects/myapp
          - command: lazygit
            direction: right
            directory: ~/projects/myapp

┌────────────┬──────────┐
│    nvim    │ lazygit  │
└────────────┴──────────┘

Complex layout

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

Multi-window

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

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:

tm restore 2>/dev/null

After a reboot, SSH login automatically restores your YAML-defined sessions. Existing sessions are skipped (idempotent).

Requirements

• tmux ≥ 3.2 (auto-installed by tm setup)
• Go ≥ 1.24 (auto-installed by install script)
• Linux or macOS

Contributing

See CONTRIBUTING.md for guidelines. PRs and issues welcome.

License

MIT © 2024–2026 dohwi