TSM

The tiny SSH-first tmux dashboard for AI coding agents.

SSH into a VPS, see which Codex, Claude, Gemini, Qwen, Hermes, or custom agent sessions are waiting, errored, done, or still running, then attach to the one that needs you. TSM is Bash + tmux only: no daemon, no browser UI, no cloud dependency, and no dotfile overwrite.

Quick Start

curl -sL https://raw.githubusercontent.com/ahmedsaid47/tsm/main/install.sh | bash
tsm init --dry-run
tsm

30-Second Local Demo

tmux new-session -d -s codex-demo "printf 'Approval required\nProceed? [y/n]\n'; sleep 600"
tmux new-session -d -s claude-demo "printf 'Error: quota exceeded\n'; sleep 600"
tmux new-session -d -s gemini-demo "printf 'All tests passed successfully\n'; sleep 600"
tmux new-session -d -s qwen-demo "sleep 600"
tsm mark codex-demo waiting "approve file edit"
tsm status

[WAIT]  CODEX   codex-demo    bash   ~/app   2m   approve file edit
[ERR]   CLAUDE  claude-demo   bash   ~/app   1m   problem detected in pane output
[DONE]  GEMINI  gemini-demo   bash   ~/app   1m   completion signal in pane output
[RUN]   QWEN    qwen-demo     bash   ~/app   35s  agent session active

Clean up the demo sessions when finished:

tmux kill-session -t codex-demo
tmux kill-session -t claude-demo
tmux kill-session -t gemini-demo
tmux kill-session -t qwen-demo

Why This Exists

• Open an SSH shell and land in a session dashboard instead of a blank terminal.
• Stop guessing which remote agent needs attention.
• Reattach to long-running sessions such as Codex, Qwen, Claude, Gemini, Hermes, or custom tmux processes.
• Keep the core portable: Bash 4+ and tmux are the only required runtime tools.
• Avoid risky installer behavior: TSM uses marker blocks and backups instead of overwriting ~/.tmux.conf.

It is intentionally not a tmuxinator fork. TSM stays small and can optionally discover tmuxinator, tmuxp, zoxide, and project directories when those tools are already installed.

Features

• Attention-first tmux dashboard: waiting, errored, and done sessions float up.
• Session metadata: attached state, windows, panes, active command, cwd, and age.
• AI-agent labels and status from configurable patterns, tmux activity, pane tail heuristics, and hook/manual status files.
• Agent commands: tsm status, tsm watch, tsm mark, tsm hook, tsm run.
• Compact tmux status-right counts with tsm status-bar --tmux.
• First-run setup preview/apply with tsm init --dry-run and tsm init --yes.
• Generic hook recipes and local notification tests.
• Safe SSH auto-start hook: install/remove with tsm install-hook and tsm remove-hook.
• Optional tmux snippet preview/apply with marker blocks and backups.
• Optional adapters for project directories, tmuxinator, tmuxp, and zoxide.
• Minimal ASCII theme plus explicit emoji/color theme for terminals that render it well.
• JSON output for scripts.

Install

Manual install:

git clone https://github.com/ahmedsaid47/tsm.git
cd tsm
./install.sh

Uninstall:

curl -sL https://raw.githubusercontent.com/ahmedsaid47/tsm/main/install.sh | bash -s -- --uninstall

Usage

tsm                         # Interactive dashboard
tsm -l                      # List tmux sessions
tsm -a                      # Attach last or first session
tsm attach medrese          # Attach a named session
tsm -n codex                # Create and attach a session
tsm projects                # List optional adapter projects
tsm doctor                  # Check tmux, hooks, config, adapters
tsm install-hook            # Add SSH auto-start hook
tsm remove-hook             # Remove SSH auto-start hook
tsm apply-snippet --dry-run # Preview optional tmux settings
tsm status                  # Attention-sorted agent status table
tsm status codex            # Agent details and pane tail
tsm status-bar              # Compact counts for scripts/status bars
tsm mark codex waiting      # Manual status override
tsm hook codex done         # Agent/script hook endpoint
tsm clear-status codex      # Remove manual status
tsm watch --notify 3        # Live-refresh status view with local alerts
tsm run codex -- codex      # Start a detached agent session
tsm init --dry-run          # Preview first-run shell/tmux setup
tsm hooks recipes           # Print generic lifecycle hook examples
tsm notify test --dry-run   # Verify notification formatting
tsm --json                  # JSON sessions/projects output

Interactive shortcuts:

Key	Action
Up/Down, j/k	Navigate
Enter	Select
n	New session
d	Delete session
r	Rename session
/	Search sessions/projects
?	Help
q, Esc	Quit
Ctrl+b, then d	Detach from a tmux session and return to TSM
Ctrl+b, then T	Alternate detach shortcut configured by TSM

Configuration

Config file: ~/.config/tmux-session-manager/config.conf

language=auto
theme=auto
ssh_auto_start=true
return_to_menu_on_detach=true
show_preview=true
adapters=auto
agent_patterns=codex,qwen,claude,gemini,hermes,agy
status_capture_lines=80
status_idle_after_seconds=900
status_bar_enabled=true
detector_mode=balanced
notify_enabled=false
notify_on=waiting,error,done
notify_bell=true
project_dirs=~/projects,~/work,~/src,~/code

Adapter policy:

• adapters=auto loads every available adapter.
• adapters=none disables project adapters.
• adapters=dirs,tmuxinator loads only selected adapters.

Safety Model

TSM does not overwrite your tmux config. The optional tmux snippet is managed between marker comments:

tsm apply-snippet --dry-run
tsm apply-snippet

Shell auto-start is also marker-based and can be removed cleanly:

tsm install-hook
tsm remove-hook

Set NO_TSM=1 before opening a shell to bypass auto-start for debugging.

Agent Status

TSM uses three status sources, in this order:

1. Manual or hook state written by tsm mark / tsm hook.
2. Pane-tail heuristics for words such as approval, continue, done, failed, quota, traceback, or rate limit.
3. tmux activity fallback using agent name patterns and idle threshold.

Supported status values:

• waiting: needs input or approval
• error: failed, quota/rate-limit, exception, or similar issue
• done: finished or completed
• working: active agent process
• idle: no recent activity
• unknown: no useful signal

Examples:

tsm mark codex waiting "needs approval"
tsm hook claude done "tests passed"
tsm run gemini -c ~/app -- gemini
tsm status-bar
tsm watch --notify 2

Privacy note: TSM only reads local tmux pane text on the same machine. It does not send pane contents anywhere. Set status_capture_lines=0 to disable tail-based detection and rely only on hooks/activity.

Requirements

• tmux 2.0+
• Bash 4.0+
• curl or wget for installer

Optional integrations:

• tmuxinator
• tmuxp
• zoxide

Why Not Existing Tools?

Tool	Best at	TSM difference
tmuxinator / tmuxp	Project layouts	TSM is an SSH-first status dashboard, not a layout DSL
tmux-resurrect / continuum	Restore tmux state	TSM shows which live agent needs attention
sesh / tmux-sessionx	Fast session switching	TSM stays Bash+tmux and adds agent status
agent-deck / gmux / ccmux / agtx	Rich agent control suites	TSM is tiny, auditable, and daemon-free

See docs/PRODUCT_RESEARCH.md for the positioning and launch research behind this direction.

See docs/LAUNCH_PLAYBOOK.md for the GitHub/X launch checklist and demo script.

Demo assets:

• Animated terminal demo
• Static dashboard screenshot
• Asciinema-style demo cast
• Social preview image

Development

bash -n tsm tmux-menu.sh install.sh lib/*.sh backends/*.sh themes/*.sh lang/*.sh tests/*.sh
tests/status-fixtures.sh
tests/smoke.sh

See CONTRIBUTING.md for contribution notes.