tm — tmux Session Manager

Pure Bash + fzf. Single file. Zero friction. Millisecond startup.

繁體中文

Why tm? Modern development means running multiple AI agents, Claude Code sessions, and background tasks across tmux. tm gives you instant visibility into what's running where — with process trees, AI-powered summaries, and protection locks to keep critical sessions safe. On mobile (iOS / Android), just SSH into your server and run tm — the fzf interface works great with touch, letting you manage sessions on the go.

---

Demo

╭──────────────── tmux session manager v1.0.0 ──────────────────╮
│ Keys: ↵Enter │ Tab Multi-sel │ ^N New │ ^K Kill │ ^P Protect  │
│                                                               │
│      NAME                  DIRECTORY                W  P IDLE │
│  [▸] my-project            ~/project/my-project     3  4 now  │
│ >[●] web-app               ~/project/web-app        2  2 3m   │
│  [●] api-server 🔒         ~/project/api-server     4  5 15m  │
│  [○] dotfiles              ~/dotfiles               1  1 2h   │
│  [○] notes                 ~/documents/notes        1  1 1d   │
│                                                               │
│╭─────────────────────────────────────────────────────────────╮│
││ ── Session Details ──────────────────                       ││
││ 🏷️  web-app                                                 ││
││ 📂 ~/project/web-app                                        ││
││ 🌿 feat/new-dashboard                                       ││
││ 🪟 2 win · 2 pane · 1 client                                ││
││ 🕒 2026-04-06 08:30 · idle 3m                               ││
││ 💡 Next.js dashboard dev with hot reload                    ││
││                                                             ││
││ ── Running Processes ────────────────                       ││
││   ▸ zsh  (1234)  CPU 0.0% · RAM 12.3M                       ││
││     └─ node  (1250)  CPU 2.1% · RAM 156.8M                  ││
││   ▸ zsh  (1300)  CPU 0.0% · RAM 11.8M                       ││
││     └─ claude  (1315)  CPU 0.5% · RAM 89.2M                 ││
││   Total: CPU 2.6% · RAM 270.1M                              ││
││                                                             ││
││ ── Window List ─────────────────────                        ││
││   0: editor (active)                                        ││
││   1: server                                                 ││
│╰─────────────────────────────────────────────────────────────╯│
╰───────────────────────────────────────────────────────────────╯

Status indicators:  [▸] current   [●] attached   [○] idle   🔒 protected

---

Highlights

	Feature	Description
🤖	AI Summaries	Auto-generate session purpose summaries with Claude Haiku
🌳	Process Tree	See every pane's shell and child processes with CPU/RAM
🔒	Protection Lock	Prevent critical sessions from accidental termination
⚡	Smart Sorting	Most recently used sessions always on top
🎨	Group Colors	Sessions in the same directory share indicator colors
🌿	Git Branch	Preview panel shows current branch at a glance
📋	Session Templates	Create multi-window layouts in one command
💀	Batch Kill	Multi-select and kill with three-stage safety confirmation

---

Quick Start

git clone <repo-url> && cd session-manager
./install-fzf.sh
chmod +x tm.sh
./tm.sh

Installation

# Clone or download to any directory
chmod +x tm.sh

# Download fzf (required for interactive mode)
./install-fzf.sh

# (Optional) Create a global shortcut — pick one:
ln -sf "$(pwd)/tm.sh" ~/.local/bin/tm
# or add to ~/.bashrc / ~/.zshrc:
alias tm="~/session-manager/tm.sh"

Dependencies

Tool	Version	Purpose	Install
bash	4.0+	Required	See note below
tmux	—	Required	brew install tmux / apt install tmux
fzf	—	Interactive mode	Run ./install-fzf.sh to auto-download into the project directory

Note

CLI mode (ls, kill, protect, etc.) only requires tmux — no fzf needed.

Warning

macOS users: The default /bin/bash is version 3.2. You need bash 4.0+ for this tool to work. Install a newer version with brew install bash and make sure the new bash is in your $PATH before /bin/bash.

Platform Support

Works on desktop and mobile — manage your tmux sessions from anywhere.

Platform	How to use
macOS (ARM / Intel)	Run directly
Linux (amd64 / arm64)	Run directly
iOS / iPadOS	SSH into your server via Termius
Android	SSH into your server via Termux

Tip

On mobile, tm's fzf-based UI works great with touch and on-screen keyboards — no desktop required. Pair with mosh for a seamless experience over unstable connections.

---

Usage

Interactive Mode (Recommended)

./tm.sh          # Launch fzf interactive menu

Shortcut	Action
Enter	Attach to selected session
Tab	Multi-select (for batch kill with Ctrl-K)
Ctrl-N	Create new session
Ctrl-K	Kill session (supports multi-select batch kill)
Ctrl-E	Rename session
Ctrl-D	Detach other clients
Ctrl-P	Toggle protection lock 🔒
Ctrl-R	Refresh list
Ctrl-Q	Quit
Esc	Quit

CLI Mode

tm                          # Interactive menu
tm <session-name>           # Attach to a specific session
tm new myapp ~/code         # Create a new session
tm new myapp -t dev         # Create session from template (3 windows)
tm kill myapp               # Kill session (with safety checks)
tm attach myapp -d          # Attach and detach other clients
tm rename myapp             # Rename session
tm last                     # Switch to the last session
tm ls                       # List all sessions (plain text)
tm templates                # List available templates
tm protect myapp            # Toggle protection status
tm summarize myapp          # Generate AI summary for a session
tm summarize-all            # Generate AI summaries for all sessions
tm help                     # Show help

---

tmux Keybinding Integration

Add the following to ~/.tmux.conf to launch the manager with Prefix + M:

# Popup mode (recommended, tmux 3.2+)
bind M display-popup -w 90% -h 85% -E "/path/to/tm.sh"

# Or open in a new window
bind M new-window -n "tm" "/path/to/tm.sh"

Zsh Completion

# Option 1: Source directly (add to ~/.zshrc)
source /path/to/session-manager/completions/tm.zsh

# Option 2: Copy to fpath
cp completions/tm.zsh ~/.zsh/completions/_tm

---

Safety Mechanisms

Three layers of protection to prevent accidental session termination:

1. Protection Lock — Sessions marked with Ctrl-P are blocked from deletion entirely
2. Current Session Detection — Cannot kill the session you are currently using
3. Three-stage Confirmation — Shows running critical processes (claude, python, node...) and requires typing the full session name to confirm

Environment Variables

Variable	Default	Description
TM_PROJECT_BASE	Two levels above tm.sh	Directory menu for creating new sessions

---

AI Summaries — Setup & Cron

How it works

Uses Claude Haiku to generate a one-line summary for each tmux session, inferring its purpose from session name, directory, git branch, window list, and running processes.

tm summarize myapp       # Single session
tm summarize-all         # All sessions

Summary history is stored in JSONL format at ~/.tmux-manager/summaries/<session_name>.jsonl and is not auto-cleaned. The latest summary is displayed in the fzf preview panel.

Cron Schedule (Auto-update Hourly)

crontab -e
# Add the following line (replace with your actual path):
0 * * * * /path/to/tm.sh summarize-all >> /tmp/tm-summary.log 2>&1

Requires Claude CLI (claude command) to be installed.

File Structure

session-manager/
├── tm.sh                              # Main script
├── install-fzf.sh                     # fzf download script
├── completions/
│   └── tm.zsh                         # Zsh completion
└── ~/.tmux-manager/                   # Runtime data (auto-created)
    ├── protected.txt                  # Protected session list
    ├── last_session                   # Last session record
    ├── templates/                     # Session template directory
    │   └── dev                        # Default dev template (editor/server/logs)
    └── summaries/                     # AI summary history (JSONL)
        └── <session_name>.jsonl       # One summary record per line

---

License

MIT