Coders - Multi-Agent Development Assistant

Spawn and manage AI coding assistants in isolated tmux sessions with optional git worktrees, Redis-based coordination, and automatic session recovery.

Quick Start

Spawn a new session

${CLAUDE_PLUGIN_ROOT}/bin/coders spawn claude --task "Implement OAuth authentication"

CLI alternative (outside Claude Code):

./bin/coders spawn claude --task "Implement OAuth authentication"

With a git worktree

${CLAUDE_PLUGIN_ROOT}/bin/coders spawn claude --task "Fix login bug" --worktree fix/login-bug

List active sessions

${CLAUDE_PLUGIN_ROOT}/bin/coders list

Attach to a session

tmux attach -t coder-SESSION_ID

Press Ctrl+B then D to detach.

Features

✨ Multi-Agent Support: Spawn Claude, Gemini, Codex, or OpenCode in parallel 🌲 Git Worktrees: Isolate work in separate branches without switching 🔄 Session Persistence: Save and restore sessions across reboots 📡 Redis Coordination: Inter-agent messaging and heartbeat monitoring 📊 Web Dashboard: Monitor all sessions in real-time 🎯 Smart Naming: Auto-generate session names from task descriptions 🔁 Recursive Loop: Automatically execute tasks from todolist with promise-based coordination

Available Commands

All commands use the skill syntax:

• /coders:spawn - Spawn a new AI session
• /coders:list - List active sessions
• /coders:loop - Start recursive task loop from todolist
• /coders:promises - Check completion status of all sessions
• /coders:attach - Attach to a session
• /coders:kill - Kill a session
• /coders:promise - Publish completion summary (use when task is done)
• /coders:snapshot - Save all sessions
• /coders:restore - Restore saved sessions
• /coders:orchestrator - Start orchestrator session
• /coders:dashboard - Open web dashboard

Common Workflows

Basic Usage

# Spawn Claude for a simple task
/coders:spawn claude --task "Review the authentication code"

# Spawn Gemini for research
/coders:spawn gemini --task "Research WebSocket best practices"

# Check what's running
/coders:list

Multi-Agent Development

# Start orchestrator to coordinate agents
/coders:orchestrator

# Inside orchestrator, spawn specialized agents
/coders:spawn claude --task "Implement API endpoints" --worktree backend/api
/coders:spawn gemini --task "Research API security"
/coders:spawn claude --task "Write tests" --worktree backend/tests

# Monitor everything
/coders:dashboard

Spawning in Different Directories

IMPORTANT: By default, sessions run in your current directory. Use --cwd to spawn in a different project:

# Spawn in a specific project directory
/coders:spawn claude --cwd ~/Dev/flp/vega --task "Fix the API bug"

# Spawn in another project while staying in your current directory
/coders:spawn gemini --cwd ~/projects/frontend --task "Review React components"

Git Worktree Isolation

# Work on multiple features in parallel
/coders:spawn claude --task "Add OAuth" --worktree feature/oauth
/coders:spawn claude --task "Build dashboard" --worktree feature/dashboard

# Each session has its own isolated git worktree

Recursive Task Loop

# Automatically execute all tasks from a todolist
/coders:loop --todolist ~/project/todolist.txt --cwd ~/project

# Use opus for complex tasks
/coders:loop --todolist tasks.txt --cwd ~/project --model claude-opus-4

# Run 2 tasks in parallel
/coders:loop --todolist tasks.txt --cwd ~/project --max-concurrent 2

# Stop if any task is blocked
/coders:loop --todolist tasks.txt --cwd ~/project --stop-on-blocked

# Preview what would be executed
/coders:loop --todolist tasks.txt --cwd ~/project --dry-run

The loop feature:

• Parses your todolist and executes uncompleted tasks sequentially
• Monitors completion promises to know when to spawn the next task
• Automatically switches from Claude to Codex when approaching usage limits
• Marks tasks as complete in the todolist file after each success
• Runs in background while orchestrator remains interactive

Session Persistence

# Before shutting down
/coders:snapshot

# After reboot
/coders:restore

Redis Coordination

Enable Redis for inter-agent messaging and monitoring:

/coders:spawn claude --task "Build frontend" --redis redis://localhost:6379 --enable-heartbeat

Agents can:

• Send messages to each other via pub/sub
• Publish heartbeats for dashboard monitoring
• Resources are automatically cleaned up when sessions end

Task Completion & Promises

IMPORTANT: When spawned sessions complete their tasks, they MUST publish a completion promise to notify the orchestrator and dashboard:

# When task is complete
/coders:promise "Implemented user authentication with JWT tokens"

# If blocked and can't proceed
/coders:promise "Blocked waiting for API credentials" --status blocked

# If work is done but needs review
/coders:promise "PR ready for review" --status needs-review

Why this matters:

• The orchestrator can track which sessions are done
• The dashboard shows completion status clearly
• Follow-up tasks can be spawned automatically
• Blocked tasks are visible for manual intervention

Best practices:

• Publish promise immediately when task is done (don't wait)
• Include specific details about what was accomplished
• If partially done, list what's complete and what's remaining
• For blocked tasks, clearly state what's needed to unblock

Documentation

• API Reference - Complete API documentation for programmatic usage
• Examples - Real-world scenarios and code examples
• Command docs - Each command has its own detailed documentation

Session Management

Auto-Generated Names

Session names are automatically generated from task descriptions:

/coders:spawn claude --task "Review the Linear project"
# Creates: coder-claude-linear-project

Manual Naming

/coders:spawn claude --task "Fix bug" --name my-custom-name
# Creates: coder-my-custom-name

Communicating with Sessions

Attach (recommended):

tmux attach -t coder-SESSION_ID
# Work inside the session
# Ctrl+B then D to detach

Send messages remotely:

tmux send-keys -t coder-SESSION_ID "your message"
sleep 0.5
tmux send-keys -t coder-SESSION_ID C-m

Check output:

tmux capture-pane -t coder-SESSION_ID -p | tail -20

Options Reference

spawn command options:

• tool - AI tool: claude, gemini, codex, opencode (default: claude)
  • Note: Use claude for Claude Code (not sonnet, opus, or haiku)
  • Model selection is done via --model flag, not the tool name
• --task - Task description (required)
• --name - Custom session name (optional, auto-generated if omitted)
• --model - Model identifier passed to the tool CLI (optional)
• --cwd - Working directory for the session (default: current directory)
• --worktree - Git branch for worktree (optional)
• --base-branch - Base branch for worktree (default: main)
• --prd - PRD/spec file path to include as context (optional)
• --redis - Redis URL for coordination (optional)
• --enable-heartbeat - Enable heartbeat publishing (optional)

Requirements

• tmux - Required for session management
• Redis - Required for coordination and heartbeat monitoring
• git - For worktree support (optional)
• Node.js 18+ - Runtime

Tips

1. Use --cwd to spawn in different projects - Sessions default to your current directory. Always specify --cwd ~/path/to/project when you want a session to work in a different codebase.
2. Use the orchestrator for complex multi-agent workflows
3. Save snapshots regularly to preserve session state
4. Use worktrees to avoid branch switching conflicts
5. Enable Redis heartbeat for production-like agent monitoring
6. Use the dashboard to monitor multiple sessions visually

Troubleshooting

Session not found

/coders:list  # Verify session exists
tmux list-sessions | grep coder-  # Check tmux directly

Worktree already exists

git worktree list  # List worktrees
git worktree remove ../worktrees/BRANCH  # Remove stale worktree

Redis connection failed

redis-server  # Start Redis
# or
docker run -d -p 6379:6379 redis:latest

See Also

• Reference - Full API documentation
• Examples - Usage examples and patterns