Create threads with different modes (automatic, semi-auto, interactive, sleeping)
Create threads with isolated git worktrees
Start, stop, pause, and resume threads
Query thread status and view logs
Delete completed threads

Git Worktree Isolation

Each thread can have its own isolated git worktree
Multiple threads can work on different branches simultaneously
Automatic worktree cleanup when threads complete
Push changes from worktree to remote

Event-Driven Coordination

Publish events to the blackboard
Subscribe to events from other threads
Send direct messages between threads
Share artifacts between threads

PR Shepherd Integration

Watch PRs with isolated worktrees
Automatic CI failure detection and fix
Review change request handling
Worktree-per-PR isolation

Essential Commands

Thread Operations

# Initialize claude-threads in project
ct init

# Create a thread
ct thread create <name> --mode <mode> --template <template>

# Create thread with isolated worktree
ct thread create <name> --mode automatic --worktree
ct thread create <name> --worktree --worktree-base develop

# List threads
ct thread list [status]

# Start/stop/resume threads
ct thread start <id>
ct thread stop <id>
ct thread resume <id>

# View thread status and logs
ct thread status <id>
ct thread logs <id>

Worktree Management

# List all active worktrees
ct worktree list

# Show worktree details
ct worktree status <id>

# Cleanup orphaned worktrees
ct worktree cleanup

Orchestrator Control

# Start/stop orchestrator daemon
ct orchestrator start
ct orchestrator stop
ct orchestrator status
ct orchestrator restart

PR Shepherd

# Watch PR with worktree isolation
ct pr watch <pr_number>

# Check status
ct pr status [pr_number]
ct pr list

# Stop watching
ct pr stop <pr_number>

# Run as daemon
ct pr daemon

Event Operations

# List recent events
ct event list

# Publish event
ct event publish <type> '<json>'

Thread Modes

Mode	Use Case
`automatic`	Fully autonomous background tasks
`semi-auto`	Autonomous with user approval for critical steps
`interactive`	Step-by-step user confirmation
`sleeping`	Scheduled or event-triggered tasks

Workflow Patterns

Parallel Epic Development

# Create threads with isolated worktrees
ct thread create epic-7a --mode automatic --template bmad-developer.md --worktree --context '{"epic_id": "7A"}'
ct thread create epic-8a --mode automatic --template bmad-developer.md --worktree --context '{"epic_id": "8A"}'

# Start orchestrator
ct orchestrator start

# Monitor
ct thread list running
ct worktree list

PR Fix Pipeline

# Watch PR - creates isolated worktree
ct pr watch 123

# Shepherd automatically:
# - Creates worktree for PR branch
# - Spawns fix threads when CI fails
# - Pushes fixes from worktree
# - Cleans up when PR merges

ct pr status 123

Coordinated Review

# Create reviewer thread that triggers on development completion
ct thread create reviewer --mode semi-auto --template reviewer.md --trigger DEVELOPMENT_COMPLETED

# Events flow: STORY_COMPLETED -> DEVELOPMENT_COMPLETED -> reviewer wakes

Event Types

Event	Description
`THREAD_STARTED`	Thread began execution
`THREAD_COMPLETED`	Thread finished
`THREAD_BLOCKED`	Thread encountered a blocker
`WORKTREE_CREATED`	Isolated worktree created
`WORKTREE_PUSHED`	Changes pushed from worktree
`WORKTREE_DELETED`	Worktree cleaned up
`STORY_STARTED`	Developer starting story
`STORY_COMPLETED`	Story implementation done
`DEVELOPMENT_COMPLETED`	All stories finished
`REVIEW_COMPLETED`	Code review done
`PR_CREATED`	Pull request opened
`CI_PASSED` / `CI_FAILED`	CI status update
`PR_APPROVED`	PR approved
`PR_MERGED`	PR merged successfully

Configuration

In .claude-threads/config.yaml:

threads:
  max_concurrent: 5
  default_max_turns: 80

orchestrator:
  poll_interval: 1
  idle_poll_interval: 10
  idle_threshold: 30

worktrees:
  enabled: true
  max_age_days: 7
  auto_cleanup: true
  default_base_branch: main
  auto_push: true

pr_shepherd:
  max_fix_attempts: 5
  ci_poll_interval: 30
  auto_merge: false

State Locations

Database: .claude-threads/threads.db
Logs: .claude-threads/logs/
Config: .claude-threads/config.yaml
Templates: .claude-threads/templates/
Worktrees: .claude-threads/worktrees/

Error Handling

If a thread becomes blocked:

# Check status
ct thread status <id>

# View logs
ct thread logs <id>

# Resume manually
ct thread resume <id>

# Or restart
ct thread stop <id> && ct thread start <id>

Base + Fork Pattern (Memory Efficient)

For PR lifecycle management, use the base + fork pattern:

# Create base worktree when watching a PR (once)
ct worktree base-create 123 feature/my-pr main

# Fork from base for each sub-agent (shares git objects, ~1MB vs ~100MB)
ct worktree fork 123 conflict-fix fix/conflict conflict_resolution

# After sub-agent completes, merge fork back
ct worktree merge-back conflict-fix

# Cleanup fork
ct worktree remove-fork conflict-fix

# When PR is done, cleanup base
ct worktree base-remove 123

Benefits

Forks share git objects with base (memory efficient)
Fast creation and removal
Centralized push from base worktree
Easy coordination of parallel fixes

Coordination Patterns

Pattern 1: Sequential Chain

A ─► B ─► C ─► Done

Use: Tasks with dependencies

Pattern 2: Parallel Fan-Out

    Orchestrator
    ┌─┬─┬─┬─┬─┐
    ▼ ▼ ▼ ▼ ▼ ▼
    1 2 3 4 5 6

Use: Independent parallel tasks (max 5)

Pattern 3: Fan-Out/Fan-In (PR Lifecycle)

PR Shepherd
├── Fork → Conflict Resolver → Merge Back
├── Fork → Comment Handler 1 → Merge Back
└── Fork → Comment Handler 2 → Merge Back
Then: Push from base

Cross-Instance Orchestration

Connect external Claude Code instances:

# On orchestrator machine
ct api start --token $TOKEN

# On worker machine
ct remote connect orchestrator:31337 --token $TOKEN
ct spawn epic-7a --template bmad-developer.md

Best Practices

Use worktrees for parallel development to avoid conflicts
Use base + fork pattern for PR sub-agents (memory efficient)
Start orchestrator before creating automatic threads
Monitor events for workflow progress
Use PR Shepherd for automatic CI/review handling
Clean up orphaned worktrees periodically
Publish events for all significant state changes
Use checkpoints for long-running agents

Documentation

ARCHITECTURE.md - System architecture
AGENT-COORDINATION.md - Coordination patterns
WORKTREE-GUIDE.md - Worktree management
EVENT-REFERENCE.md - Event types
MULTI-INSTANCE.md - Distributed deployment