Metadata-Version: 2.4
Name: worktree-mux
Version: 0.4.0
Summary: A tmux-based viewer for git worktrees
Project-URL: Homepage, https://github.com/tt6746690/worktree-mux
Project-URL: Repository, https://github.com/tt6746690/worktree-mux
Project-URL: Issues, https://github.com/tt6746690/worktree-mux/issues
Author: Peiqi Wang
License-Expression: MIT
License-File: LICENSE
Keywords: cli,git,tmux,worktree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Provides-Extra: lint
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Provides-Extra: types
Requires-Dist: mypy; extra == 'types'
Description-Content-Type: text/markdown

# worktree-mux

A tmux control panel for git worktrees.

When you run multiple AI agents or parallel feature branches, each git worktree becomes its own dev environment. worktree-mux maps **1 worktree → 1 tmux window**, so you can instantly jump between contexts to run commands, inspect logs, or debug — without losing your place.
- **What it does**: fast terminal access to every worktree
- **What it doesn't do**: create or manage worktrees — git still does that

_Think_: a dashboard for parallel coding environments.

See [PLAN.md](PLAN.md) for assumptions and design considerations.

## Install

```bash
# Install from PyPI
uv tool install worktree-mux

# Or install from source
git clone https://github.com/tt6746690/worktree-mux.git
uv tool install worktree-mux/

# (Optional) Short alias — add to ~/.zshrc
alias wm='worktree-mux'
```

## Usage


1. **Create worktrees with git**: worktree-mux just views them

```bash
git worktree add .worktrees/feature/auth -b feature/auth
git worktree add .worktrees/fix/parser-bug -b fix/parser-bug
git worktree add .worktrees/refactor-models -b refactor-models
```

2. **See all worktrees** and their status with `worktree-mux` (or `worktree-mux ls`)

```
worktree-mux — my-repo
────────────────────────────────────────────────────────────────

    Branch              tmux  Modified   vs main   Last Commit
    ──────────────────  ────  ────────   ───────   ─────────────────
  ▸ feature/auth        ●     2 files    ↑3        12 minutes ago
    fix/parser-bug      ○     clean      ↑1        2 hours ago
    refactor-models     ○     3 files    ↑5 ↓2     35 minutes ago

  ● = tmux window open    ○ = no tmux window    ▸ = current
  Session: my-repo (3 worktrees, 1 open)
```

3. **Jump into a worktree**: creates a tmux window and switches to it with `worktree-mux cd`

```bash
worktree-mux cd auth             # (fuzzy) leaf name match
worktree-mux cd parser           # (fuzzy) substring match
worktree-mux cd feature/auth     # exact path match
worktree-mux cd                  # go to the main window (repo root)
```

Return to your previous session: `prefix + s` and toggle

4. **Live dashboard** of worktrees — auto-refreshing version of the status table with `worktree-mux dash`

```
worktree-mux — my-repo (refreshes every 5s)
──────────────────────────────────────────────────────────────────────

    Branch              tmux  Modified   vs main   Last Commit
    ──────────────────  ────  ────────   ───────   ─────────────────
  ▸ feature/auth        ●     2 files    ↑3        12 minutes ago
    fix/parser-bug      ○     clean      ↑1        2 hours ago
    refactor-models     ○     3 files    ↑5 ↓2     35 minutes ago

  ● = tmux window open    ○ = no tmux window    ▸ = current
```

5. **Cleanup**: worktree-mux automatically cleans up orphaned tmux windows (from removed worktrees) on every command. No manual close needed — just delete the worktree with `git worktree remove` and the window goes away.
