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

One command does everything. Automatically:

1. Installs Go (if missing)
2. Builds tmux-manager from the latest GitHub release
3. Runs tm setup — installs tmux (if missing), configures shell integration, status bar, and auto-restore

No extra steps. Run tm in a new terminal.

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
tmux	Auto-install tmux if missing (apt/brew/dnf/pacman)

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

Format

Always sessions → windows → panes — one unified structure.

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

┌────────────┬──────────┐
│            │ lazygit  │
│    nvim    ├──────────┤
│            │ npm run  │
│            │   dev    │
└────────────┴──────────┘

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 in one file

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

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

---

📋 Field Reference

Field	Required	Description
sessions	✅	Session map (keys = tmux session names)
sessions[].windows		Window list (default: one empty window)
sessions[].windows[].name		Window tab name (session name if omitted)
sessions[].windows[].panes		Pane layout within the 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.

# v0.2.4 test