tmux-manager

README

tmux-manager

A Dracula-themed TUI for tmux session management

Create, switch, and kill sessions with tm. Define your workspace in YAML and restore it on reboot.

One command — installs Go (if needed), builds from latest release, and runs setup automatically.

---

✨ Features

• TUI session management — ↑↓ navigate, Enter attach, Ctrl+N/D/R operate
• YAML workspaces — define session, window, and pane layouts as code
• Auto-restore — tm restore brings your workspace back after reboot
• cfg tag — YAML-managed sessions are tagged cfg in the TUI
• Dracula theme — developer-friendly color scheme

---

📸 Screenshot

---

📦 Installation

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

Installs Go (if missing), builds tmux-manager from the latest GitHub release, then runs tm setup automatically — no extra steps needed.

setup handles everything automatically:

Item	Description
~/.local/bin/tm	Create symlink
~/.zshrc	Register nocorrect tm alias
~/.profile	Register tm restore for auto-restore on boot
~/.config/tmux-manager/sessions/	Create config directory
~/.config/tmux-manager/tmux.conf	Dracula-themed status bar + keybindings
~/.tmux.conf	Register source-file for tmux-manager config

To update, run tm update from any terminal.

---

🚀 Usage

tm                      # Launch TUI
tm restore              # Restore sessions from YAML
tm restore --dry-run    # Show what would be restored
tm setup                # Install symlink and shell integration
tm setup --uninstall    # Remove symlink and shell 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 selected session
Ctrl+D	Delete selected session
Ctrl+C	Quit

---

⚙️ Configuration

~/.config/tmux-manager/sessions/*.yaml

Minimal — single pane

sessions:
  monitoring:
    panes:
      - command: htop

Side-by-side split

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

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

Complex layout

sessions:
  dev:
    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

sessions:
  myapp:
    windows:
      - name: code
        directory: ~/projects/myapp
        panes:
          - command: nvim
          - command: lazygit
            direction: right
      - name: infra
        directory: ~/projects/myapp
        panes:
          - command: docker-compose up
          - command: docker logs -f
            direction: down

Multiple sessions in one file

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

  db:
    panes:
      - command: psql myapp
        directory: ~/projects/myapp

---

📋 Field Reference

Field	Required	Description
sessions	✅	Session map (keys = tmux session names)
sessions[].windows		Window list
sessions[].windows[].name		Window tab name (defaults if omitted)
sessions[].windows[].directory		Working directory for the window (~/ supported)
sessions[].windows[].command		Command for a single-pane window
sessions[].windows[].panes		Pane layout within the window
sessions[].panes		Pane layout for the default window
panes[].command		Command to run in the pane
panes[].directory		Working directory for the pane (~/ supported)
panes[].name		Pane title (sets tmux pane title)
panes[].direction		Split direction: right · down (omit for first pane)

---

🔄 Auto-Restore

tm setup adds this to ~/.profile:

tm restore 2>/dev/null

After a reboot, SSH login automatically creates sessions defined in your YAML files. Existing sessions are skipped (idempotent).

---

🎨 cfg Tag

Sessions managed via YAML are distinguished in the TUI with a cfg tag:

◉  good-giraffe-drawing    attached    cfg
○  myapp-dev               1 windows   cfg
●  temp-session             attached

---

tmux-manager — manage sessions, not commands.