tmuxtui

中文文档

Interactive terminal UI for managing tmux sessions. Browse, create, rename, detach, and kill sessions without memorizing tmux commands.

Features

• Session browser — list all tmux sessions sorted by last used, with window count, working directory, and creation time
• Quick attach — select and attach to any session instantly; auto sets terminal tab title to [tmux] session_name
• Create sessions — new session with custom name and working directory
• Window manager — press c to enter config mode: create, rename, delete windows, and initialize pane layouts
• Pane layout presets — 9 built-in layouts (IDE, Quad, Triple, etc.) with live preview
• Rename / Detach / Kill — full session lifecycle management
• Works everywhere — runs inside or outside tmux (auto-detects and uses switch-client or attach-session)
• init command — register the current directory as a new tmux session in one step

Session persistence

tmux sessions live in the tmux server process memory. Rebooting your machine kills the server and wipes every session — this is a tmux behavior, not something tmuxtui can fix on its own (tmuxtui only persists your favorites list at ~/.config/tmuxtui/favorites.json).

If you want sessions, windows, panes, and even some running programs to survive reboots, install the community-standard pair:

• tmux-resurrect — manual save/restore of the full session tree
• tmux-continuum — automatic periodic save and auto-restore on tmux start

tmuxtui works seamlessly alongside both — they snapshot tmux's state to disk; tmuxtui reads whatever state the server currently has.

Requirements

• Node.js >= 18
• tmux >= 3.2

Install

npm install -g tmux-tui

Usage

Interactive TUI

tmuxtui

Keyboard shortcuts (all customizable via config file):

| Key | Action | |-----|--------| | ↑ ↓ | Select session | | Enter | Attach to session | | n | New session | | r | Rename session | | x | Detach session | | d | Kill session (with confirm) | | c | Config — window management | | i | Session details (windows & panes) | | / | Search sessions | | s | Toggle favorite | | f | Filter favorites only | | R | Refresh session list | | Tab | Mark / unmark session | | X | Batch detach marked sessions | | D | Batch kill marked sessions | | h | Help | | q | Quit |

When creating a new session, press Tab to switch between the name and path fields.

Configuration

Create ~/.config/tmuxtui/config.json to customize behavior:

{
  "defaultSort": "lastAttached",
  "confirmBeforeKill": true,
  "autoAttachOnCreate": false,
  "refreshInterval": 0,
  "keybindings": {
    "quit": "escape",
    "new": "n",
    "kill": "d"
  },
  "ui": {
    "showPath": true,
    "showSessionId": false,
    "sessionNameWidth": 20
  }
}

Config options

| Option | Default | Description | |--------|---------|-------------| | defaultSort | "lastAttached" | Sort mode: "lastAttached", "name", or "created" | | confirmBeforeKill | true | Show confirmation before killing sessions | | autoAttachOnCreate | false | Auto-attach after creating a new session | | refreshInterval | 0 | Auto-refresh interval in seconds (0 = disabled) | | ui.showPath | true | Show session working directory | | ui.showSessionId | false | Show tmux session ID | | ui.sessionNameWidth | 20 | Session name column width (10-60) | | keybindings.* | see defaults | Remap any keyboard shortcut |

All keybinding names: select-up, select-down, attach, new, rename, kill, detach, search, favorite, favorites-filter, refresh, help, quit, batch-mark, batch-detach, batch-kill, detail, config.

Config mode (window management)

Press c on any session to enter config mode. This lets you manage windows within the selected session.

| Key | Action | |-----|--------| | ↑ ↓ | Select window | | n | New window | | r | Rename window | | d | Delete window (with confirm) | | i | Init pane layout (only for single-pane inactive windows) | | Esc | Back to session list |

Pane layout presets

When you press i, you can choose from 9 built-in pane layouts:

| Layout | Panes | Description | |--------|-------|-------------| | 1. Single | 1 | No splits | | 2. H-Split | 2 | Horizontal 50/50 | | 3. V-Split | 2 | Vertical 50/50 | | 4. IDE | 2 | Left sidebar (25%) + main | | 5. IDE+Term | 3 | IDE + bottom terminal | | 6. Triple | 3 | Three equal columns | | 7. IDE+Side | 3 | IDE with right sidebar | | 8. Quad | 4 | 2x2 grid | | 9. IDE Pro | 4 | IDE + split right panel |

Commands

Init — register current project

tmuxtui init
# or
tmuxtui -i

Creates a new tmux session named after the current directory and opens it with tmuxtui.

Update — self-update

tmuxtui update

Checks for the latest version on npm registry and automatically updates tmuxtui if a newer version is available. Shows the current version, and confirms the updated version after completion.

Version — show version

tmuxtui --version
# or
tmuxtui -v

Displays the installed version of tmuxtui.

Last — attach to most recent session

tmuxtui last
# or
tmuxtui -l

Quickly attach to the most recently used tmux session without opening the session picker.

Favorites only

tmuxtui --favorites
# or
tmuxtui -F

Open tmuxtui showing only favorited sessions.

Development

Prerequisites

• Node.js >= 18
• tmux >= 3.2

Setup

# Clone the repository
git clone https://github.com/yourusername/tmuxtui.git
cd tmuxtui

# Install dependencies
npm install

Development Commands

# Run in development mode (with subcommands)
npm run dev -- init
npm run dev -- --help

# Run with arguments (alternative)
npm run dev:args init

# Build and test the compiled output
npm run dev:build -- init

# Test the packaged distribution (before publish)
npm run dev:pack

Build and Publish

# Build the project
npm run build

# Dry-run publish (creates .tgz for testing)
npm pack

# Publish to npm
npm publish

License

MIT