ws

A single-file bash CLI for managing tmux workspaces from a YAML config.

Define your workspaces once, launch them with one command. If a session already exists, ws reattaches to it.

$ ws ls
  myapp        ● running
  dotfiles     ○ stopped
  blog         ○ stopped

Quick Start

curl -fsSL https://raw.githubusercontent.com/jakescript/tmux-workspaces/main/install.sh | bash

Or clone and run directly:

git clone https://github.com/jakescript/tmux-workspaces.git
./tmux-workspaces/bin/ws help

Requires tmux and yq (brew install yq). Optional: fzf for the interactive picker.

Usage

ws                  Interactive picker (fzf or numbered menu)
ws <alias>          Launch or attach to a workspace
ws ls               List workspaces and their status
ws kill <alias>     Kill a running session
ws edit             Open config in $EDITOR
ws help             Show help
ws version          Print version

Shell Completions

Tab completions for subcommands and workspace aliases are installed automatically by install.sh.

Manual setup (cloned repo)

Zsh — add to ~/.zshrc:

fpath=(path/to/tmux-workspaces/completions $fpath)
autoload -Uz compinit && compinit

Bash — add to ~/.bashrc:

source path/to/tmux-workspaces/completions/ws.bash

Config

Create ~/.config/tmux-workspace.yml (or set WS_CONFIG to use a custom path):

workspaces:
  myapp:
    name: my-app              # optional — defaults to alias
    root: ~/projects/my-app   # required
    startup_window: editor    # optional — defaults to first window
    windows:
      - name: editor
        cmd: nvim
      - name: dev
        cmd: npm run dev
      - name: terminal        # no cmd = plain shell

An example config with more workspaces is included at examples/workspaces.yml.

License

MIT