# claude-threads [![Version](https://img.shields.io/badge/version-1.5.0-blue.svg)](VERSION) **Multi-Agent Thread Orchestration Framework for Claude Code** claude-threads is a bash-based orchestration framework that enables parallel execution of Claude Code agents with shared state. It provides a state machine for thread lifecycle management, a blackboard pattern for inter-thread communication, and integrations with GitHub webhooks and n8n workflows. ## Features - **Multi-Thread Orchestration** - Run multiple Claude agents in parallel with coordinated state - **Git Worktree Isolation** - Each thread gets its own isolated git worktree for parallel development - **PR Shepherd** - Automatic CI/review feedback loop with worktree-per-PR isolation - **Thread Modes** - Automatic, semi-automatic, interactive, and sleeping modes - **Blackboard Pattern** - Shared event bus for inter-thread communication - **Session Management** - Persistent Claude sessions with resume capability - **SQLite Persistence** - Thread-safe state storage with WAL mode - **Template System** - Mustache-like templates for prompts and workflows - **GitHub Integration** - Webhook receiver for PR events, CI status - **n8n Integration** - HTTP API for workflow automation - **Multi-Instance** - Connect external Claude Code instances to spawn parallel threads ## Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ ORCHESTRATOR │ │ (main process - manages thread lifecycle) │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Thread 1 │ │ Thread 2 │ │ Thread N │ │ │ │ (foreground)│ │ (background) │ │ (sleeping) │ │ │ │ interactive │ │ automatic │ │ scheduled │ │ │ │ [worktree] │ │ [worktree] │ │ [worktree] │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └────────────┬────┴─────────────────┘ │ │ │ │ │ ┌───────▼───────┐ │ │ │ BLACKBOARD │ (shared state bus) │ │ │ - events │ │ │ │ - messages │ │ │ │ - artifacts │ │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ SQLite DB │ (persistent, thread-safe) │ │ │ - threads │ │ │ │ - worktrees │ │ │ │ - events │ │ │ │ - sessions │ │ │ └───────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Thread Modes | Mode | Description | Execution | |------|-------------|-----------| | **automatic** | Fully autonomous, no interaction | Background with `claude -p` | | **semi-auto** | Automatic with critical decision prompts | Foreground | | **interactive** | Full interactive, every step confirmed | Foreground | | **sleeping** | Waiting for trigger (time, event) | Periodic wake | ## Thread Lifecycle ``` CREATED → READY → RUNNING → [WAITING|SLEEPING|BLOCKED] → COMPLETED ↑ ↓ └──────────────┘ ``` ## Prerequisites Required tools: - `sqlite3` - SQLite database engine - `jq` - JSON processor - `claude` - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) - `git` - Git version control Optional: - `gh` - [GitHub CLI](https://cli.github.com/) for GitHub integration - `yq` - YAML processor for config parsing (falls back to Python/awk) - `python3` - Required for webhook and API servers ## Installation ```bash # Clone the repository git clone https://github.com/hanibalsk/claude-threads.git cd claude-threads # Run the install script ./install.sh # Or install globally ./install.sh --global # Or target a specific project directory ./install.sh --target /path/to/your/project ``` After installation, add `~/.claude-threads/bin` to your PATH (for global install) or use the local `ct` command. ## Quick Start ```bash # Initialize in your project cd /path/to/your/project ct init # Create a new thread ct thread create "developer" --mode automatic --template prompts/developer.md # Create a thread with isolated worktree ct thread create "epic-dev" --mode automatic --template prompts/developer.md --worktree # Start the thread ct thread start # List threads ct thread list # View thread status ct thread status # List active worktrees ct worktree list ``` ## Project Structure ``` claude-threads/ ├── VERSION # Version file (1.0.0) ├── config.example.yaml # Example configuration ├── install.sh # Installer script ├── bin/ │ └── ct # CLI entry point ├── lib/ │ ├── utils.sh # Common utilities (incl. portable query parsing) │ ├── log.sh # Logging utilities │ ├── db.sh # SQLite operations │ ├── state.sh # Thread state management │ ├── blackboard.sh # Event bus + PR events │ ├── template.sh # Template rendering (multiline conditionals) │ ├── claude.sh # Claude CLI wrapper │ ├── config.sh # Configuration management │ ├── git.sh # Git worktree management │ └── remote.sh # Remote API client for multi-instance ├── scripts/ │ ├── orchestrator.sh # Main orchestrator daemon (adaptive polling) │ ├── thread-runner.sh # Individual thread executor │ ├── pr-shepherd.sh # PR feedback loop manager │ ├── migrate.sh # Database migration script │ ├── webhook-server.sh # GitHub webhook HTTP server │ ├── webhook-handler.sh # Webhook event processor │ ├── api-server.sh # REST API HTTP server │ └── api-handler.sh # API request handler ├── sql/ │ ├── schema.sql # Full database schema │ └── migrations/ # Incremental migrations │ ├── 000_schema_version.sql │ ├── 001_initial.sql │ ├── 002_worktrees.sql │ └── 003_pr_watches.sql ├── templates/ │ ├── prompts/ # Prompt templates │ │ ├── developer.md # Epic/story implementation │ │ ├── reviewer.md # Code review │ │ ├── planner.md # Feature planning │ │ ├── pr-monitor.md # PR monitoring │ │ ├── pr-fix.md # PR fix agent (CI/review fixes) │ │ ├── fixer.md # Issue/feedback fixing │ │ ├── tester.md # Test writing │ │ └── bmad-*.md # BMAD-specific templates │ └── workflows/ # Workflow templates ├── commands/ │ ├── threads.md # /threads slash command │ ├── bmad.md # /bmad slash command │ ├── ct-connect.md # /ct-connect slash command │ └── ct-spawn.md # /ct-spawn slash command ├── skills/ │ ├── threads/ # Thread orchestration skill │ │ └── SKILL.md │ ├── bmad-autopilot/ # BMAD autonomous development skill │ │ └── SKILL.md │ └── thread-spawner/ # Multi-instance thread spawning skill │ └── SKILL.md ├── .claude/ │ └── agents/ # Claude Code agent definitions │ ├── thread-orchestrator.md │ ├── story-developer.md │ ├── code-reviewer.md │ ├── security-reviewer.md │ ├── test-writer.md │ ├── issue-fixer.md │ ├── pr-manager.md │ └── explorer.md └── docs/ ├── AGENTS.md # Agent documentation ├── MIGRATION.md # BMAD migration guide ├── MIGRATIONS.md # Database migrations guide ├── MULTI-INSTANCE.md # Multi-instance coordination guide └── PR-SHEPHERD.md # PR shepherd guide ``` ## Configuration Copy `config.example.yaml` to `.claude-threads/config.yaml` and customize: ```yaml threads: max_concurrent: 5 default_max_turns: 80 orchestrator: poll_interval: 1 log_level: info 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 claude: command: claude permission_mode: acceptEdits github: enabled: true webhook_port: 31338 ``` Settings can be overridden via environment variables: ```bash CT_THREADS_MAX_CONCURRENT=10 ct orchestrator start ``` ## SQLite Schema The framework uses SQLite with WAL mode for concurrent access: - `threads` - Thread state and configuration - `worktrees` - Git worktree tracking per thread - `events` - Blackboard event stream - `messages` - Inter-thread messages - `sessions` - Claude session tracking - `artifacts` - Shared artifacts - `webhooks` - Incoming webhook events - `pr_watches` - PR Shepherd tracking - `schema_migrations` - Applied database migrations ### Database Migrations When upgrading claude-threads, migrations are applied automatically: ```bash # Check migration status ct migrate --status # Apply pending migrations manually ct migrate # Preview changes (dry run) ct migrate --dry-run ``` See [docs/MIGRATIONS.md](docs/MIGRATIONS.md) for details. ## Template System Templates use a simple Mustache-like syntax: ```markdown --- name: developer variables: - epic_id - stories --- # Developer Agent You are developing Epic {{epic_id}}. {{#if stories}} Stories to implement: {{stories}} {{/if}} When complete, output: ```json {"event": "STORY_COMPLETED", "story_id": "{{story_id}}"} ``` ``` ## API Reference ### Thread Management ```bash # Create thread thread_id=$(thread_create "my-thread" "automatic" "prompts/dev.md") # Lifecycle thread_ready "$thread_id" thread_run "$thread_id" thread_wait "$thread_id" "reason" thread_complete "$thread_id" # Query thread_get "$thread_id" thread_list "running" ``` ### Blackboard ```bash # Publish event bb_publish "STORY_COMPLETED" '{"story_id": "41.1"}' "$thread_id" # Poll events events=$(bb_poll "$thread_id") # Send direct message bb_send "$target_thread" "REQUEST" '{"action": "review"}' ``` ### Claude Execution ```bash # Execute prompt session_id=$(claude_start_session "$thread_id") claude_execute "Implement the feature" "automatic" "$session_id" # Resume session claude_resume "$session_id" "Continue from here" ``` ## CLI Reference ### ct thread ```bash ct thread create [options] # Create a new thread --mode # automatic, semi-auto, interactive, sleeping --template # Prompt template file --context # Thread context as JSON --worktree # Create isolated git worktree --worktree-base # Base branch for worktree (default: main) ct thread list [status] # List threads (optionally by status) ct thread start # Start a thread ct thread stop # Stop a thread ct thread status # Show thread status ct thread logs # View thread logs ct thread resume # Resume interactively ct thread delete # Delete a thread ``` ### ct worktree ```bash ct worktree list # List all active worktrees ct worktree status # Show worktree status ct worktree cleanup # Cleanup orphaned worktrees ``` ### ct orchestrator ```bash ct orchestrator start # Start daemon ct orchestrator stop # Stop daemon ct orchestrator status # Show status ct orchestrator restart # Restart daemon ct orchestrator tick # Run single iteration ``` ### ct event ```bash ct event list # List recent events ct event publish [data] # Publish an event ``` ### ct webhook ```bash ct webhook start # Start GitHub webhook server ct webhook stop # Stop webhook server ct webhook status # Show status ``` ### ct api ```bash ct api start # Start REST API server ct api stop # Stop API server ct api status # Show status and endpoints ``` ### ct pr (PR Shepherd) ```bash ct pr watch # Start watching a PR (creates worktree) ct pr status [pr_number] # Show PR status (or list all) ct pr list # List all watched PRs ct pr stop # Stop watching a PR ct pr daemon # Run shepherd as daemon ``` Each watched PR gets its own isolated git worktree for fix operations. ## Git Worktree Isolation Threads can run in isolated git worktrees for true parallel development: ```bash # Create thread with dedicated worktree ct thread create epic-42 --mode automatic --template developer.md --worktree # Thread runs in isolated directory: .claude-threads/worktrees/epic-42- # Changes don't affect main working directory # Multiple threads can work on different branches simultaneously ``` ### Benefits - **No conflicts** - Each thread has its own working directory - **Parallel branches** - Multiple epics/features developed simultaneously - **Automatic cleanup** - Worktrees removed when threads complete - **Event coordination** - Threads communicate via blackboard ### Worktree Lifecycle ``` Thread Created → Worktree Created → Thread Runs → Push Changes → Thread Completes → Worktree Cleaned ↓ ↓ ↓ ↓ THREAD_CREATED WORKTREE_CREATED (events) WORKTREE_PUSHED ``` ### Configuration ```yaml worktrees: enabled: true # Enable worktree isolation max_age_days: 7 # Auto-cleanup after N days auto_cleanup: true # Cleanup when thread completes default_base_branch: main # Default base for new worktrees auto_push: true # Push changes on completion ``` ## PR Shepherd (Automatic PR Feedback Loop) The PR Shepherd monitors your pull requests and automatically: 1. Detects CI failures and spawns fix threads 2. Detects review change requests and addresses them 3. Waits for approval and optionally auto-merges ### How It Works ``` ┌─────────────────────────────────────────────────────────────┐ │ PR SHEPHERD LOOP │ ├─────────────────────────────────────────────────────────────┤ │ │ │ WATCHING ───► CI_PENDING ───► CI_PASSED ───► APPROVED │ │ │ │ │ │ │ │ │ ▼ │ ▼ │ │ │ CI_FAILED │ MERGED │ │ │ │ │ │ │ │ ▼ │ │ │ │ FIXING ────────────┘ │ │ │ (spawn fix │ │ │ thread) │ │ │ │ │ │ │ ▼ │ │ └──────── REVIEW_PENDING ──► CHANGES_REQUESTED │ │ │ │ │ ▼ │ │ FIXING ────────────► │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Usage ```bash # Start watching a PR ct pr watch 123 # The shepherd will: # 1. Poll CI status every 30 seconds # 2. If CI fails, spawn a fix thread using prompts/pr-fix.md # 3. Wait for the fix thread to complete # 4. Check CI again # 5. If CI passes, wait for review # 6. If changes requested, spawn another fix thread # 7. Repeat until approved and merged (or max attempts reached) # Check status ct pr status 123 # Run shepherd as background daemon ct pr daemon ``` ### Configuration ```yaml # config.yaml pr_shepherd: max_fix_attempts: 5 # Max auto-fix attempts before giving up ci_poll_interval: 30 # Seconds between CI checks idle_poll_interval: 300 # Seconds when no active PRs push_cooldown: 120 # Seconds to wait after push auto_merge: false # Auto-merge when ready ``` ### Adaptive Polling The orchestrator uses adaptive polling to reduce resource usage: - **Active**: 1-second polling when threads are running or PRs are active - **Idle**: 10-second polling when system is idle for 30+ ticks ```yaml orchestrator: poll_interval: 1 # Active polling interval idle_poll_interval: 10 # Idle polling interval idle_threshold: 30 # Ticks before switching to idle ``` ## GitHub Webhook Integration The webhook server receives GitHub events and publishes them to the blackboard: ```bash # Start webhook server ct webhook start --port 31338 # Configure in GitHub repository settings: # Webhook URL: http://your-server:31338/webhook # Content type: application/json # Events: Pull requests, Check runs, Issue comments ``` Supported events: - `pull_request` → `PR_OPENED`, `PR_CLOSED`, `PR_MERGED` - `pull_request_review` → `PR_APPROVED`, `PR_CHANGES_REQUESTED` - `check_run` → `CI_PASSED`, `CI_FAILED` - `issue_comment` → `PR_COMMENT` - `push` → `PUSH` ## n8n REST API The API server provides a REST interface for automation tools: ```bash # Start API server ct api start --port 31337 # Example: Create thread via API curl -X POST http://localhost:31337/api/threads \ -H "Content-Type: application/json" \ -d '{"name": "developer", "mode": "automatic"}' # Example: Publish event curl -X POST http://localhost:31337/api/events \ -H "Content-Type: application/json" \ -d '{"type": "TASK_STARTED", "data": {"task_id": "123"}}' ``` API Endpoints: - `GET /api/health` - Health check - `GET /api/status` - System status - `GET /api/threads` - List threads - `POST /api/threads` - Create thread - `GET /api/threads/:id` - Get thread - `POST /api/threads/:id/start` - Start thread - `POST /api/threads/:id/stop` - Stop thread - `DELETE /api/threads/:id` - Delete thread - `GET /api/events` - List events - `POST /api/events` - Publish event - `GET /api/messages/:id` - Get messages - `POST /api/messages` - Send message ## Multi-Instance Coordination Connect multiple Claude Code instances to a single orchestrator for parallel thread execution: ```bash # Terminal 1: Start orchestrator and API ct orchestrator start export N8N_API_TOKEN=my-secret-token ct api start # Terminal 2: Connect external Claude Code instance export CT_API_TOKEN=my-secret-token ct remote connect localhost:31337 # Spawn parallel threads from external instance ct spawn epic-7a --template bmad-developer.md --worktree ct spawn epic-8a --template bmad-developer.md --worktree ct spawn epic-9a --template bmad-developer.md --worktree ``` ### Remote Commands ```bash ct remote connect [--token TOKEN] # Connect to orchestrator ct remote disconnect # Disconnect ct remote status # Show connection status ct remote discover # Auto-discover orchestrator ``` ### Spawn Command ```bash ct spawn [options] ``` | Option | Description | |--------|-------------| | `--template, -t ` | Prompt template file | | `--mode, -m ` | Thread mode | | `--context, -c ` | Thread context as JSON | | `--worktree, -w` | Create with isolated git worktree | | `--worktree-base ` | Base branch for worktree | | `--wait` | Wait for thread completion | | `--remote` | Force use of remote API | | `--local` | Force use of local database | The spawn command automatically uses the remote API if connected, otherwise falls back to local database. See [docs/MULTI-INSTANCE.md](docs/MULTI-INSTANCE.md) for full documentation. ## Prompt Templates Included templates in `templates/prompts/`: | Template | Description | |----------|-------------| | `developer.md` | Epic/story implementation agent | | `reviewer.md` | Code review agent | | `planner.md` | Feature planning and breakdown | | `pr-monitor.md` | Pull request monitoring | | `pr-fix.md` | **PR fix agent** - auto-fixes CI failures and review comments | | `fixer.md` | Issue/feedback fixing | | `tester.md` | Test writing and execution | | `bmad-developer.md` | BMAD epic/story developer | | `bmad-reviewer.md` | BMAD code review agent | | `bmad-pr-manager.md` | BMAD PR lifecycle manager | | `bmad-fixer.md` | BMAD issue fixer | ## Workflow Templates Included workflows in `templates/workflows/`: | Workflow | Description | |----------|-------------| | `epic-development.yaml` | Full epic development lifecycle | | `pr-review.yaml` | Automated PR review process | | `feature-planning.yaml` | Feature breakdown workflow | | `bmad-autopilot.yaml` | Full autonomous BMAD development | ## Slash Commands Claude Code slash commands in `commands/`: | Command | Description | |---------|-------------| | `/threads` | Manage thread orchestration - create, start, stop, monitor threads | | `/bmad` | Run BMAD Autopilot autonomous development | | `/ct-connect` | Connect to a running claude-threads orchestrator | | `/ct-spawn` | Spawn threads on orchestrator (local or remote) | ### Usage ```bash # In Claude Code, use: /threads list /threads create my-agent --mode automatic --template developer.md /threads start # BMAD autopilot: /bmad 7A # Process specific epic /bmad "7A 8A 10B" # Multiple epics /bmad # All epics # Connect to orchestrator (auto-executes): /ct-connect # Automatically discovers and connects # Spawn threads (auto-executes): /ct-spawn # Connects if needed, then spawns ``` The `/ct-connect` and `/ct-spawn` commands execute automatically - Claude will run the necessary shell commands for you. ## Skills Skills in `skills/` provide specialized agent capabilities: | Skill | Description | |-------|-------------| | `threads` | Thread orchestration - parallel agents, events, scheduling | | `bmad-autopilot` | BMAD autonomous development - epics, PRs, CI | | `thread-spawner` | Spawn threads on remote orchestrator | Skills are activated automatically when Claude Code detects relevant user requests. ## Claude Code Agents Built-in agents in `.claude/agents/` for multi-agent orchestration: | Agent | Model | Purpose | |-------|-------|---------| | `thread-orchestrator` | Sonnet | Coordinate multi-agent workflows | | `story-developer` | Sonnet | Implement features with TDD | | `code-reviewer` | Sonnet | Quality and best practices review | | `security-reviewer` | Sonnet | Security audit and vulnerability detection | | `test-writer` | Sonnet | Write comprehensive tests | | `issue-fixer` | Sonnet | Fix CI and review issues | | `pr-manager` | Sonnet | PR lifecycle management | | `explorer` | Haiku | Fast codebase exploration | Agents are invoked via Claude Code's Task tool: ``` User: "Review this code for security issues" → Claude automatically delegates to security-reviewer agent ``` See [docs/AGENTS.md](docs/AGENTS.md) for detailed documentation on creating and using agents. ## Roadmap - [x] Core infrastructure (v0.1.0) - SQLite schema and database operations - Thread state management - Blackboard pattern implementation - Template rendering - Configuration system - [x] Orchestrator (v0.2.0) - Main orchestrator daemon - Thread runner script - Scheduling system - CLI tool (`ct`) - Claude Code slash command - [x] Integrations (v0.3.0) - GitHub webhook receiver - n8n REST API server - Additional prompt templates (planner, pr-monitor, fixer, tester) - Workflow templates (epic-development, pr-review, feature-planning) - [x] BMAD Migration (v1.0.0) - BMAD-specific templates (bmad-developer, bmad-reviewer, bmad-pr-manager, bmad-fixer) - Workflow migration from autopilot (bmad-autopilot.yaml) - Migration guide (docs/MIGRATION.md) - Full documentation - [x] PR Shepherd (v1.1.0) - Automatic CI failure detection and fix - Review change request handling - Adaptive polling - Auto-merge support - [x] Git Worktree Isolation (v1.2.0) - Per-thread git worktrees - Parallel branch development - Worktree-per-PR for fixes - Automatic cleanup - [x] Multi-Instance Coordination (v1.3.0) - Connect external Claude Code instances to running orchestrator - Remote thread spawning with automatic worktree isolation - Auto-discovery of running orchestrators - `/ct-connect` and `/ct-spawn` slash commands - Token-based API authentication - [x] UX Improvements (v1.4.0) - Comprehensive `--help` support for all commands and subcommands - `ct help` command with topics (getting-started, templates, etc.) - Smart error messages with recovery hints and command suggestions - `--format json|text` flag for machine-readable output - `--verbose` flag for detailed progress output - `ct templates` command for template discovery - Enhanced `ct init` output with quick start guide - New documentation: GETTING-STARTED.md, TROUBLESHOOTING.md ## BMAD Autopilot Integration claude-threads provides a complete replacement for the original `bmad-autopilot.sh` script with enhanced capabilities: ```bash # Quick start with BMAD ct init ct thread create bmad-autopilot --mode automatic --template prompts/bmad-developer.md # Or run the full workflow ct workflow start bmad-autopilot --context '{"epic_pattern": "7A"}' ``` Key advantages over the original script: - **Parallel epic processing** - Multiple epics can be developed concurrently - **Resilient state** - SQLite persistence survives crashes - **Real-time events** - GitHub webhooks instead of polling - **Modular agents** - Separate threads for development, review, PR management, fixing See [docs/MIGRATION.md](docs/MIGRATION.md) for a complete migration guide. ## License MIT License - see [LICENSE](LICENSE) ## Contributing Contributions welcome! Please read the contributing guidelines first. ## Related Projects - [BMAD Autopilot](https://github.com/hanibalsk/autopilot) - Original autonomous development orchestrator - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - Anthropic's CLI for Claude - [BMAD Method](https://github.com/bmad-method) - Agile development methodology