Metadata-Version: 2.4
Name: claude-tmux-workspace
Version: 0.6.0
Summary: Workspace root for claude-tmux CLI and plugin
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: claude-tmux


## Features

- **Worktree Isolation**: Each agent gets its own git worktree, preventing branch conflicts
- **TUI Dashboard**: Real-time status monitoring with vim-style navigation
- **Attention System**: Jump between panes needing user input (permission requests, notifications, questions)
- **Plugin Integration**: Claude Code hooks track agent state in a shared SQLite database
- **tmux Bindings**: Quick navigation with customizable keybindings

## Requirements

- Python 3.12+
- tmux
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- git

## Installation

```bash
# With uv (recommended)
uv tool install claude-tmux

# Or with pip
pip install claude-tmux

# Run guided setup to install the Claude Code plugin
claude-tmux setup
```

## Quick Start

```bash
# Create a new agent with a worktree
claude-tmux new feature-auth

# List all agents
claude-tmux ls

# Attach to an agent's tmux window
claude-tmux attach feature-auth

# Launch the TUI dashboard
claude-tmux ui

# Jump to next pane needing attention
claude-tmux next-attention

# Merge and cleanup when done
claude-tmux merge feature-auth
```

## TUI Dashboard

Launch with `claude-tmux ui` for an interactive dashboard.

**Navigation:**
| Key | Action |
|-----|--------|
| `j`/`k` | Move cursor down/up |
| `g`/`G` | Jump to top/bottom |
| `Enter` | Switch to agent pane |
| `/` | Search agents |
| `A` | Toggle attention-only filter |
| `p` | Toggle preview pane |
| `n` | Create new agent |
| `x` | Kill selected agent |
| `?` | Show all keybindings |
| `q` | Quit |

**Environment Variables:**
| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_TMUX_TUI_PREVIEW` | `true` | Show preview pane on startup |
| `CLAUDE_TMUX_TUI_PERSIST` | `true` | Keep TUI open after jumping to agent |

## tmux Integration

Add to your `.tmux.conf`:

```bash
# Popup TUI dashboard
bind-key M-u display-popup -E -w 90% -h 85% "ctmux ui"

# Generate all recommended bindings
claude-tmux bindings >> ~/.tmux.conf
```

## Plugin Setup

The Claude Code plugin tracks agent state automatically via lifecycle hooks.

### Guided Setup (Recommended)

```bash
claude-tmux setup
```

This command:
1. Checks prerequisites (tmux, claude, git, Python 3.12+)
2. Installs the plugin to Claude Code
3. Configures tmux key bindings (optional)
4. Installs MCP server globally (optional)
5. Builds macOS desktop notifier (optional, macOS only)
6. Verifies the installation

**Options:**
| Flag | Description |
|------|-------------|
| `--yes, -y` | Skip confirmation prompts |
| `--skip-bindings` | Don't install tmux key bindings |
| `--skip-mcp` | Don't install MCP server |
| `--skip-notifier` | Don't build macOS notifier |
| `--reinstall` | Reinstall even if already installed |

### Uninstall

```bash
claude-tmux uninstall
```

Removes the plugin from Claude Code and optionally removes tmux bindings.

| Flag | Description |
|------|-------------|
| `--yes, -y` | Skip confirmation prompts |
| `--keep-bindings` | Don't remove tmux key bindings |

## CLI Reference

```bash
# Setup
claude-tmux setup            # Install plugin and configure
claude-tmux uninstall        # Remove plugin
claude-tmux doctor           # Validate environment

# Agent Management
claude-tmux new <name>       # Create agent with optional worktree
claude-tmux kill <name>      # Stop agent
claude-tmux attach <name>    # Switch to agent window
claude-tmux ls               # List agents with status
claude-tmux merge <name>     # Squash-merge worktree and cleanup

# Navigation
claude-tmux next-attention   # Jump to next attention pane
claude-tmux prev-attention   # Jump to previous attention pane
claude-tmux next-done        # Jump to next completed pane

# Utilities
claude-tmux reconcile        # Clean up stale agents
claude-tmux events           # View event log
claude-tmux bindings         # Generate tmux keybindings
```

## Development

See [CLAUDE.md](CLAUDE.md) for architecture details, coding standards, and contributor guidelines.

```bash
make install      # Install dependencies
make test         # Run tests
make typecheck    # Run mypy
make pre-commit   # Run all checks
```

## License

MIT
