tmux-agents

# Tmux Agents

Run coding agents in persistent tmux sessions. They work in the background while you do other things.

## Available Agents

### ☁️ Cloud Agents (API credits)

| Agent | Command | Best For |
|-------|---------|----------|
| **claude** | Claude Code | Complex coding, refactoring, full projects |
| **codex** | OpenAI Codex | Quick edits, auto-approve mode |
| **gemini** | Google Gemini | Research, analysis, documentation |

### 🦙 Local Agents (FREE via Ollama)

| Agent | Command | Best For |
|-------|---------|----------|
| **ollama-claude** | Claude Code + Ollama | Long experiments, heavy refactoring |
| **ollama-codex** | Codex + Ollama | Extended coding sessions |

Local agents use your Mac's GPU — no API costs, great for experimentation!

## Quick Commands

### Spawn a new agent session
```bash
./skills/tmux-agents/scripts/spawn.sh <name> <task> [agent]

# Cloud (uses API credits)
./skills/tmux-agents/scripts/spawn.sh fix-bug "Fix login validation" claude
./skills/tmux-agents/scripts/spawn.sh refactor "Refactor the auth module" codex
./skills/tmux-agents/scripts/spawn.sh research "Research caching strategies" gemini

# Local (FREE - uses Ollama)
./skills/tmux-agents/scripts/spawn.sh experiment "Rewrite entire test suite" ollama-claude
./skills/tmux-agents/scripts/spawn.sh big-refactor "Refactor all services" ollama-codex
```

### List running sessions
```bash
tmux list-sessions
# or
./skills/tmux-agents/scripts/status.sh
```

### Check on a session
```bash
./skills/tmux-agents/scripts/check.sh session-name
```

### Attach to watch live
```bash
tmux attach -t session-name
# Detach with: Ctrl+B, then D
```

### Send additional instructions
```bash
tmux send-keys -t session-name "additional instruction here" Enter
```

### Kill a session when done
```bash
tmux kill-session -t session-name
```

## When to Use Local vs Cloud

| Scenario | Recommendation |
|----------|----------------|
| Quick fix, time-sensitive | ☁️ Cloud (faster) |
| Expensive task, bu...

# tmux-agents 🖥️

Run coding agents in persistent tmux sessions. They work in the background while you do other things.

## Features

- **5 agents**: Claude Code, Codex, Gemini + local Ollama variants
- **Cloud or Local**: Use API credits for speed, or run free on local Ollama
- **Parallel sessions**: Run multiple agents on different tasks
- **Persistent**: Sessions survive restarts
- **Simple workflow**: spawn → check → collect

## Installation

```bash
clawdhub install tmux-agents
```

Requires: `tmux` (auto-installs via brew if missing)

## Quick Start

```bash
# Spawn an agent with a task
./skills/tmux-agents/scripts/spawn.sh fix-bug "Fix the login validation" claude

# Check progress
./skills/tmux-agents/scripts/check.sh fix-bug

# Watch live
tmux attach -t fix-bug

# Kill when done
tmux kill-session -t fix-bug
```

## Available Agents

### ☁️ Cloud (API credits)
| Agent | Description |
|-------|-------------|
| `claude` | Claude Code (default) |
| `codex` | OpenAI Codex CLI |
| `gemini` | Google Gemini CLI |

### 🦙 Local (FREE via Ollama)
| Agent | Description |
|-------|-------------|
| `ollama-claude` | Claude Code + local model |
| `ollama-codex` | Codex + local model |

## Examples

```bash
# Quick cloud task
spawn.sh api-fix "Fix REST endpoint" claude

# Long experiment (free)
spawn.sh big-refactor "Refactor all services" ollama-claude

# Parallel agents
spawn.sh backend "Build user API" claude
spawn.sh frontend "Create dashboard" codex
spawn.sh tests "Write unit tests" ollama-claude
```

## Commands

| Script | Purpose |
|--------|---------|
| `spawn.sh <name> <task> [agent]` | Start a new agent session |
| `check.sh [name]` | Check session output |
| `status.sh` | Overview of all sessions |

## Local Setup (Optional)

For free local agents:

```bash
ollama pull glm-4.7-flash
ollama launch claude --model glm-4.7-flash --config
ollama launch codex --model glm-4.7-flash --config
```

## License

MIT