# wsx
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
```
```mermaid
flowchart LR
P[Project] --> W1[Worktree main]
P --> W2[Worktree feature-auth]
W1 --> S1[Session: nvim]
W1 --> S2[Session: dev]
W2 --> S3[Session: dev]
```
## Guide
| **Project config** `.gtrconfig` at repo root — post-create hook, auto-copy env files into new worktrees. Press `e` to view. | <img width="473" height="245" alt="image" src="https://github.com/user-attachments/assets/41a1ef82-9ebb-49aa-993e-4ae9f1ea0a83" /> |
| **Add project** Press `p`, enter a path. Tab-completion supported. | <img width="457" height="221" alt="image" src="https://github.com/user-attachments/assets/b6c0c7bf-7252-4281-bee4-8dfa4c8d4529" /> |
| **New worktree** Select a project, press `w`, enter a branch name. | <img width="459" height="52" alt="image" src="https://github.com/user-attachments/assets/8280c712-29a1-43d6-8504-0c7161ab9b86" /> <img width="264" height="90" alt="image" src="https://github.com/user-attachments/assets/c8183cf6-4de8-414a-88e2-1ceac1722080" /> |
| **Sessions** Select a worktree, press `s`. Name by context — `shell`, `claude`, `build`. Sessions are persistent tmux sessions; `d` deletes, `r` renames. | <img width="270" height="68" alt="image" src="https://github.com/user-attachments/assets/41569337-057f-44b8-bd39-8f1d2ffa6a1f" /> |
| **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. | <img width="464" height="57" alt="image" src="https://github.com/user-attachments/assets/6d466d85-4d92-44c7-abe8-93ec4337f480" /> |
| **Detach to return** `Ctrl+a d` inside a session detaches back to wsx. The session keeps running. | |
## Install
**macOS (Homebrew)**
```sh
brew tap vlwkaos/tap
brew install wsx
```
**macOS / Linux (cargo)**
```sh
cargo install wsx
```
**Build from source**
```sh
cargo install --path .
```
> Must be run inside a tmux session.
## Usage
```sh
wsx
```
### Navigation
| `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
| `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
```ini
[hooks]
postCreate = npm install
[copy]
include = .env
include = .env.local
exclude = .env.production
```
## Inspired by
- [git-worktree-runner](https://github.com/coderabbitai/git-worktree-runner)
- [agent-of-empires](https://github.com/njbrake/agent-of-empires)