Tmux Workbench

English | 简体中文

Tmux Workbench is a workspace memory manager for developers running SSH, tmux,
and AI coding agents across multiple machines.

It indexes local and remote tmux sessions, remembers the project context around
them, and gives you one fast CLI/TUI entry point to get back to work.

ws

Why

SSH plus tmux is resilient, but it does not remember enough when your work is
spread across many machines, many projects, and long-running coding-agent
sessions. Tmux Workbench adds a local memory layer above tmux:

• server and connection information
• tmux session and pane snapshot
• project path and active command
• git branch, commit, dirty state, ahead/behind counts, and remote URL
• AI agent instruction files such as AGENTS.md and CLAUDE.md
• notes, aliases, tags, archive status, and attach history

It does not replace tmux. It makes tmux workspaces easier to find, inspect, and
resume.

AI Agent Workflows

Many workspaces now have a long-running coding agent pane such as Claude Code,
Codex, Gemini, or Aider. Tmux Workbench treats those panes as first-class
workspace context:

• prefer agent panes when choosing the workspace root
• index agent instruction files like CLAUDE.md, AGENTS.md, and
  .cursorrules
• show agent docs in the TUI detail view
• expose indexed context with ws agent <workspace>
• keep attach loading visible while remote tmux checks run

Features

• Index local tmux sessions and remote tmux sessions over SSH.
• Attach back to a workspace by stable ID: <server>/<tmux-session>.
• Manage servers from the CLI.
• Browse workspaces in a TUI with search, server filtering, and view modes.
• Preserve notes, aliases, tags, status, and attach history across scans.
• Detect missing tmux sessions without overwriting archive state.
• Capture git repository state for each workspace.
• Detect AI agent context files in each workspace root.
• Refresh in the background without blocking the TUI.
• Store state locally in SQLite.

Installation

Requirements:

• tmux
• git
• ssh for remote servers

Install Script

curl -fsSL https://raw.githubusercontent.com/LeON-Nie-code/tmux-workbench/master/install.sh | bash

The script installs ws into ~/.local/bin by default. Set
TMUX_WORKBENCH_INSTALL_DIR to override the install directory.

Homebrew

Homebrew support is available from this repository tap. Homebrew 6 requires
trusting custom taps before loading their formulae:

brew tap LeON-Nie-code/tmux-workbench https://github.com/LeON-Nie-code/tmux-workbench
brew trust LeON-Nie-code/tmux-workbench
brew install LeON-Nie-code/tmux-workbench/ws

The install script above is the recommended path if you only want the binary.

Cargo

cargo install --git https://github.com/LeON-Nie-code/tmux-workbench ws

From a local checkout:

cargo install --path .

Manual Download

Download a binary from the
Releases page and
place it somewhere in your PATH.

Example for macOS Apple Silicon:

curl -L -o ws https://github.com/LeON-Nie-code/tmux-workbench/releases/download/v0.1.1/ws-macos-aarch64
chmod +x ws
mkdir -p ~/.local/bin
mv ws ~/.local/bin/ws

Quick Start

ws init
ws servers
ws add-server prod --ssh "ssh prod"
ws scan
ws

Attach directly:

ws attach prod/api

CLI

ws servers
ws add-server prod --ssh "ssh prod"
ws add-server local-dev --local
ws remove-server prod

ws scan
ws list
ws list --server prod
ws list --status active
ws list --all
ws list --json

ws attach prod/api
ws agent prod/api
ws recreate prod/api

ws note prod/api "Backend uses uv. Frontend is in ./web."
ws alias prod/api api
ws tags prod/api work backend
ws status prod/api archived

ws doctor
ws open-config

Remote server commands use your system ssh, so existing ~/.ssh/config,
keys, ProxyCommand, and generated cloud SSH hosts continue to work.

TUI

ws

Shortcuts:

Enter  attach
/      search
n      edit note in $EDITOR
a      archive or unarchive
v      cycle all / active / archived
s      cycle server filter
z      jump between archived and all
r      rescan
j/k    move
q      quit

Search supports plain text and filters:

server:prod status:active tag:backend git:dirty

Git filters include dirty, clean, remote, ahead, behind, branch text,
commit text, and remote URL text.

The demo GIF is recorded with VHS from
the real ws binary against a local fixture database. See
docs/demo/workbench.tape.

Configuration

Config file:

~/.config/ws/config.yaml

Example:

servers:
  - name: local
    ssh: ""
    term: xterm-256color
    local: true
  - name: prod
    ssh: ssh prod
    term: xterm-256color
    local: false

Local index:

~/.local/share/ws/workspaces.db

Architecture

Tmux Workbench reads tmux state, stores a local index, and uses tmux/ssh for
attach and discovery.

tmux list-panes  ->  ws scan  ->  SQLite index  ->  CLI/TUI
       git status  ->  git snapshot /

Stack:

• Rust
• clap for CLI parsing
• ratatui + crossterm for TUI
• rusqlite for the local index
• system ssh, tmux, and git

Status

Tmux Workbench is pre-1.0 and currently optimized for a real SSH + tmux daily
workflow. The CLI and database format may still change.

Implemented:

• local and remote tmux indexing
• concurrent scan with command timeouts
• TUI auto-refresh with visible scan status
• server management CLI
• workspace notes, aliases, tags, archive status
• presence tracking for missing tmux sessions
• attach history
• git snapshots
• explicit SQLite user_version
• structured list and JSON output

Planned:

• pane layout restore
• asciinema or GIF demo
• more release targets
• dedicated Homebrew tap repository when the project is public

See ROADMAP.md for the current project direction.

Contributing

Issues and pull requests are welcome after the project becomes public. See
CONTRIBUTING.md, CODE_OF_CONDUCT.md,
and SECURITY.md.

License

MIT. See LICENSE.