Metadata-Version: 2.4
Name: taskmux
Version: 0.1.0
Summary: Modern tmux development environment manager with real-time health monitoring, auto-restart, and WebSocket API
Project-URL: Homepage, https://github.com/nc9/taskmux
Project-URL: Repository, https://github.com/nc9/taskmux
Project-URL: Issues, https://github.com/nc9/taskmux/issues
Author-email: Nik Cubrilovic <git@nikcub.me>
License: MIT
License-File: LICENSE
Keywords: daemon,development,manager,monitoring,session,terminal,tmux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: libtmux>=0.37.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Taskmux

A modern tmux development environment manager with real-time health monitoring, auto-restart capabilities, and WebSocket API. Built with Python using libtmux for reliable session management.

## Why Taskmux?

Instead of manually managing multiple tmux windows or remembering complex command sequences, Taskmux provides:

- **Dynamic task management**: Define tasks in JSON, manage via modern CLI
- **Health monitoring**: Real-time task health checks with visual indicators  
- **Auto-restart**: Automatically restart failed tasks to keep development flowing
- **WebSocket API**: Real-time status updates and remote task management
- **Rich CLI**: Beautiful terminal output with Typer and Rich integration
- **File watching**: Automatically detects config changes and reloads tasks
- **Zero setup**: Single command installation with uv tool management

## Installation

### Prerequisites

- [tmux](https://github.com/tmux/tmux) - Terminal multiplexer
- [uv](https://docs.astral.sh/uv/) - Modern Python package manager

### Install uv (if you don't have it)

**Quick install** (macOS/Linux):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows**:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Alternative methods**:
```bash
# Via Homebrew (macOS)
brew install uv

# Via pipx
pipx install uv

# Via WinGet (Windows)
winget install --id=astral-sh.uv -e
```

### Install Taskmux

**Recommended** (installs globally):
```bash
uv tool install taskmux
```

**From source**:
```bash
git clone https://github.com/your-repo/taskmux
cd taskmux
uv tool install .
```

After installation, `taskmux` command will be available globally.

## Quick Start

1. **Create config file** in your project root:

```json
{
  "name": "myproject",
  "tasks": {
    "server": "npm run dev",
    "build": "npm run build:watch", 
    "test": "npm run test:watch",
    "db": "docker-compose up postgres"
  }
}
```

2. **Start all tasks**:
```bash
taskmux start
```

3. **Monitor and manage**:
```bash
taskmux list          # See what's running with health status
taskmux health        # Detailed health check table
taskmux restart server # Restart specific task
taskmux logs -f test   # Follow logs
```

## Commands Reference

### Core Commands

```bash
# Session Management
taskmux start                    # Start all tasks in tmux session
taskmux status                   # Show session and task status
taskmux list                     # List all tasks with health indicators
taskmux stop                     # Stop session and all tasks

# Task Management  
taskmux restart <task>           # Restart specific task
taskmux kill <task>              # Kill specific task
taskmux add <task> "<command>"   # Add new task to config
taskmux remove <task>            # Remove task from config

# Monitoring
taskmux health                   # Health check with status table
taskmux logs <task>              # Show recent logs
taskmux logs -f <task>           # Follow logs (live)
taskmux logs -n 100 <task>       # Show last N lines

# Advanced
taskmux watch                    # Watch config for changes
taskmux daemon --port 8765       # Run with WebSocket API
```

### Command Examples

```bash
# Start development environment
taskmux start

# Check what's running with health status
taskmux list
# Output:
# Session: myproject
# ──────────────────────────────────────────────────
# 💚 Healthy  server          npm run dev
# 💚 Healthy  build           npm run build:watch
# 🔴 Unhealthy test           npm run test:watch
# 💚 Healthy  db              docker-compose up postgres

# Detailed health check
taskmux health
# ┏━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┓
# ┃ Status ┃ Task    ┃ Health    ┃
# ┡━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━┩
# │ 💚     │ server  │ Healthy   │
# │ 💚     │ build   │ Healthy   │
# │ 🔴     │ test    │ Unhealthy │
# │ 💚     │ db      │ Healthy   │
# └────────┴─────────┴───────────┘

# Restart a misbehaving service
taskmux restart server

# Add a new background task
taskmux add worker "python background_worker.py"

# Follow logs for debugging
taskmux logs -f test

# Watch config file for changes
taskmux watch
```

## Configuration

### Config File Format

Create `taskmux.json` in your project root:

```json
{
  "name": "session-name",
  "tasks": {
    "task-name": "command to run",
    "another-task": "another command"
  }
}
```

### Config Examples

**Web Development**:
```json
{
  "name": "webapp",
  "tasks": {
    "frontend": "npm run dev",
    "backend": "python manage.py runserver",
    "database": "docker-compose up -d postgres",
    "redis": "redis-server",
    "worker": "celery worker -A myapp",
    "tailwind": "npx tailwindcss -w"
  }
}
```

**Data Science**:
```json
{
  "name": "analysis",
  "tasks": {
    "jupyter": "jupyter lab --port=8888",
    "mlflow": "mlflow ui --port=5000",
    "airflow": "airflow webserver",
    "postgres": "docker run -p 5432:5432 postgres:13",
    "tensorboard": "tensorboard --logdir=./logs"
  }
}
```

**Microservices**:
```json
{
  "name": "microservices", 
  "tasks": {
    "api-gateway": "node gateway/server.js",
    "user-service": "go run services/user/main.go",
    "order-service": "python services/orders/app.py",
    "redis": "redis-server",
    "postgres": "docker-compose up -d db",
    "monitoring": "prometheus --config.file=prometheus.yml"
  }
}
```

## Advanced Features

### Daemon Mode with WebSocket API

Run Taskmux as a background daemon with real-time API:

```bash
# Start daemon on port 8765 (default)
taskmux daemon

# Custom port
taskmux daemon --port 9000
```

**WebSocket API Usage**:
```javascript
// Connect to WebSocket API
const ws = new WebSocket('ws://localhost:8765');

// Get status
ws.send(JSON.stringify({
  command: "status"
}));

// Restart task
ws.send(JSON.stringify({
  command: "restart",
  params: { task: "server" }
}));

// Get logs
ws.send(JSON.stringify({
  command: "logs", 
  params: { task: "server", lines: 50 }
}));
```

### Health Monitoring & Auto-restart

Taskmux continuously monitors task health and can auto-restart failed processes:

- **Health indicators**: 💚 Healthy, 🔴 Unhealthy, ○ Stopped
- **Process monitoring**: Detects when tasks exit or become unresponsive
- **Auto-restart**: Daemon mode automatically restarts failed tasks
- **Health checks**: Run `taskmux health` for detailed status

### File Watching

Monitor config changes in real-time:

```bash
# Terminal 1: Start file watcher
taskmux watch

# Terminal 2: Edit config
echo '{"name": "test", "tasks": {"new": "echo hello"}}' > taskmux.json
# Watcher automatically reloads config and updates running tasks

# New task is immediately available
taskmux restart new
```

## Workflow Integration

### Daily Development

```bash
# Morning: Start everything
taskmux start

# During development: Monitor health
taskmux health

# Restart services as needed
taskmux restart api
taskmux logs -f frontend

# Add new services on the fly
taskmux add monitoring "python monitor.py"

# Run with file watching for config changes
taskmux watch

# Evening: Stop everything
taskmux stop
```

### Tmux Integration

Taskmux creates standard tmux sessions. You can use all tmux commands:

```bash
# Attach to session
tmux attach-session -t myproject

# Switch between task windows
# Ctrl+b 1, Ctrl+b 2, etc.

# Create additional windows
tmux new-window -t myproject -n shell

# Detach and reattach later
# Ctrl+b d
tmux attach-session -t myproject
```

### Multiple Projects

Each project gets its own tmux session based on the `name` field:

```bash
# Project A (session: "webapp")
cd ~/projects/webapp
taskmux start

# Project B (session: "api") 
cd ~/projects/api
taskmux start

# Both run simultaneously with separate sessions
tmux list-sessions
# webapp: 4 windows
# api: 2 windows
```

## Architecture

Taskmux is built with modern Python tooling:

- **libtmux**: Reliable Python API for tmux session management
- **Typer**: Modern CLI framework with rich help and validation
- **Rich**: Beautiful terminal output with tables and progress bars
- **WebSockets**: Real-time API for remote monitoring and control
- **asyncio**: Async health monitoring and daemon capabilities
- **Watchdog**: File system monitoring for config changes

## Troubleshooting

### Common Issues

**Config not found**:
```bash
Error: Config file taskmux.json not found
```
- Ensure `taskmux.json` exists in current directory
- Check JSON syntax with `jq . taskmux.json`

**Session already exists**:
```bash
Session 'myproject' already exists
```
- Kill existing session: `taskmux stop`
- Or attach to it: `tmux attach-session -t myproject`

**Task not restarting**:
- Check if task name exists: `taskmux list`
- Verify session is running: `taskmux status`
- Check task health: `taskmux health`

**libtmux connection issues**:
- Ensure tmux is installed and in PATH
- Try restarting tmux server: `tmux kill-server`

### Debug Mode

View detailed tmux session information:
```bash
# Check if session exists
tmux has-session -t myproject

# List windows in session  
tmux list-windows -t myproject

# View logs manually
tmux capture-pane -t myproject:taskname -p

# Check daemon logs
tail -f ~/.taskmux/daemon.log
```

## Contributing

Taskmux follows modern Python development practices:

1. **Modular architecture**: Separate concerns (CLI, tmux management, daemon, config)
2. **Type hints**: Full type annotation for better IDE support
3. **Rich CLI**: Beautiful, user-friendly command-line interface
4. **Async support**: Background monitoring and WebSocket API
5. **Comprehensive testing**: Test across different tmux versions and platforms

## License

MIT License - feel free to modify and distribute.