wsx

ENG | 한국어

TUI workspace manager for git worktrees and tmux sessions.

The core idea

Keep a live view of every project → worktree → tmux session in a sidebar. Each session shows real-time state so you can see what needs attention without entering it. Simply pressing n to iterate sessions where attention is required.

▼ project
  ▾ main * ↑2
      ◉ wsx_cc_main
  ▸ feature-auth ↓1
      ○ wsx_cc_auth

flowchart LR
  P[Project] --> W1[Worktree main]
  P --> W2[Worktree feature-auth]
  W1 --> S1[Session: nvim]
  W1 --> S2[Session: dev]
  W2 --> S3[Session: dev]

Loading

Install

macOS (Homebrew)

brew tap vlwkaos/tap
brew install wsx

macOS / Linux (cargo)

cargo install wsx

Build from source

cargo install --path .

Must be run inside a tmux session.

Guide

Feature	Screenshot
Project config .gtrconfig at repo root — post-create hook, auto-copy env files into new worktrees. Press e to view.
Add project Press p, enter a path. Tab-completion supported.
New worktree Select a project, press w, enter a branch name.
Sessions Select a worktree, press s. Name by context — shell, claude, build. Sessions are persistent tmux sessions; d deletes, r renames.
Iterate pending n / N to jump between ● sessions. x dismisses; press again to mute ⊘. a cycles active ◉ sessions.
Remote control S sends a command to the selected session without entering it. C sends Ctrl+C — handy for killing a watcher the moment you spot it.
Tabs Press T to open the tab manager — create named tabs and assign projects to them. { / } cycles tabs. Active tab shown full, others abbreviated in the title bar: [default|pe|wo]

Important

Returning to wsx from inside a session: press Ctrl+a d to detach. The session keeps running.

If your tmux prefix is not Ctrl+a, add this to ~/.tmux.conf:

set -g prefix C-a

.gtrconfig

Place .gtrconfig at the root of any project repo to automate worktree setup.

Tip

New worktrees automatically run postCreate and receive copies of listed env files — no manual setup per branch.

[hooks]
  postCreate = npm install

[copy]
  include = .env
  include = .env.local
  exclude = .env.production

Press e on any project or worktree to view its config.

Usage

wsx

Navigation

Key	Action
j/k ↑/↓	Move cursor
h/l ←/→	Collapse / expand
Enter	Expand · attach session
[ / ]	Jump to prev / next project
a	Next active session ◉
n / N	Next / prev pending session ●
x	Dismiss · mute session
/	Incremental search
?	Full key reference

Mouse clicks work: click a row to select, click the preview to attach.

Workspaces

Key	Action
p	Add project
w	New worktree
s	New session
m	Reorder project or session
r	Set alias
d	Delete
g	Git popup (pull / push / rebase / merge)
c	Clean merged worktrees
e	View .gtrconfig
S	Send command to session
C	Send Ctrl+C to session
T	Tab manager (add / rename / delete / reorder)
{ / }	Switch to prev / next tab
m + h/l	Move project to adjacent tab (in Move mode)

tmux status bar

wsx sets status-right to project/worktree on attach. With a custom ~/.tmux.conf:

set -g status-right "#{@wsx_project}/#{@wsx_alias}"

CLI

# Worktrees
wsx worktree create <branch> [-p <project>]
wsx worktree delete <branch> [-p <project>]
wsx worktree list  [-p <project>] [--json]

# Sessions
wsx session send-keys <session> <keys>
wsx session peek <session> [-n <lines>] [-o <offset>] [-a]
wsx session rename <old> <new>
wsx session list   [-p <project>] [--json]

# Status
wsx status [--json]

peek captures pane output. -n sets how many scrollback lines to include (default: visible viewport). -o skips lines from the bottom to scroll further back. -a strips ANSI/decorations for agent/LLM consumption.

Config

Global config

Global config: ~/.config/wsx/config.toml. Per-project config via e key.

Inspired by

• git-worktree-runner
• agent-of-empires