wsx
TUI workspace manager for git worktrees and tmux sessions.
The core idea
Keep a live view of every project → worktree → session in a sidebar. Each session shows real-time state so you can see what needs attention without entering it.
Session icons
| Icon | Meaning |
|---|---|
◉ green |
Actively producing output |
● yellow |
Needs attention — bell fired, or a non-passive process went quiet |
○ gray |
Idle |
⊘ |
Muted |
The yellow ● fires on tmux bell activity or when a foreground process that isn't a shell or known passive watcher (dev server, file watcher) goes quiet. Press n to step through pending sessions, x to dismiss or mute.
Worktree git state
| Icon | Meaning |
|---|---|
~ prefix |
Main (original) worktree |
* yellow |
Uncommitted local changes |
↑N cyan |
N commits ahead — ready to push |
↓N red |
N commits behind — pull before working |
↓N↑M magenta |
Diverged |
Remote state is fetched in the background and updates silently. The preview pane shows full detail: remote branch name, sync status, modified files, recent commits.
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. |
|
Detach to return Ctrl+a d inside a session detaches back to wsx. The session keeps running. |
Install
macOS (Homebrew)
macOS / Linux (cargo)
Build from source
Must be run inside a tmux session.
Usage
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 |
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}"
Config
Global config: ~/.config/wsx/config.toml. Per-project config via e key.
.gtrconfig
[hooks]
postCreate = npm install
[copy]
include = .env
include = .env.local
exclude = .env.production