{"id":41662587,"url":"https://github.com/developerz-ai/claude-task-master","last_synced_at":"2026-04-05T17:03:15.211Z","repository":{"id":332852100,"uuid":"1135141098","full_name":"developerz-ai/claude-task-master","owner":"developerz-ai","description":"Autonomous task orchestration system that keeps Claude working until a goal is achieved","archived":false,"fork":false,"pushed_at":"2026-03-26T15:53:00.000Z","size":2667,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T06:27:24.484Z","etag":null,"topics":["agent","ai","anthropic","automation","claude","cli","python","task-orchestration"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/claude-task-master/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developerz-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T17:38:44.000Z","updated_at":"2026-03-26T15:53:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/developerz-ai/claude-task-master","commit_stats":null,"previous_names":["sebyx07/claude-task-master-py","developerz-ai/claude-task-master"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/developerz-ai/claude-task-master","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developerz-ai%2Fclaude-task-master","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developerz-ai%2Fclaude-task-master/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developerz-ai%2Fclaude-task-master/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developerz-ai%2Fclaude-task-master/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developerz-ai","download_url":"https://codeload.github.com/developerz-ai/claude-task-master/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developerz-ai%2Fclaude-task-master/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31442926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","anthropic","automation","claude","cli","python","task-orchestration"],"created_at":"2026-01-24T17:11:55.398Z","updated_at":"2026-04-05T17:03:15.196Z","avatar_url":"https://github.com/developerz-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Task Master\n\n[![CI](https://github.com/developerz-ai/claude-task-master/actions/workflows/ci.yml/badge.svg)](https://github.com/developerz-ai/claude-task-master/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/developerz-ai/claude-task-master/graph/badge.svg)](https://codecov.io/gh/developerz-ai/claude-task-master)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/claude-task-master.svg)](https://badge.fury.io/py/claude-task-master)\n\nAutonomous task orchestration system that keeps Claude working until a goal is achieved.\n\n## Quick Start\n\n### Installation\n\n**Option 1: Using uv (recommended)**\n\n```bash\n# Install with uv\nuv tool install claude-task-master\n```\n\n**Option 2: Using pip**\n\n```bash\n# Install from PyPI\npip install claude-task-master\n```\n\n**Option 3: Using Docker**\n\n```bash\n# Pull the official Docker image from GitHub Container Registry\ndocker pull ghcr.io/developerz-ai/claude-task-master:latest\n\n# Run with Docker (requires Claude credentials mounted)\ndocker run -d \\\n  --name claudetm \\\n  -p 8000:8000 \\\n  -v ~/.claude:/home/claudetm/.claude:ro \\\n  -v $(pwd):/app/project \\\n  -v ~/.gitconfig:/home/claudetm/.gitconfig:ro \\\n  -v ~/.config/gh:/home/claudetm/.config/gh:ro \\\n  ghcr.io/developerz-ai/claude-task-master:latest\n```\n\nSee [Docker Deployment Guide](./docs/docker.md) for detailed Docker setup, volume mounts, and configuration options.\n\n### Authentication\n\nBefore using claudetm, you need to authenticate with Claude:\n\n```bash\n# Run Claude CLI and login (this saves credentials that claudetm will use)\nclaude\n/login\n\n# Verify claudetm can access credentials\nclaudetm doctor\n```\n\n**For Docker users:** Ensure your `~/.claude/.credentials.json` exists before running the container, as Claude Task Master needs OAuth credentials to function.\n\n### Upgrading\n\n**With uv:**\n```bash\nuv tool install claude-task-master --force --reinstall\n```\n\n**With pip:**\n```bash\npip install --upgrade claude-task-master\n```\n\n**With Docker:**\n```bash\n# Pull the latest image\ndocker pull ghcr.io/developerz-ai/claude-task-master:latest\n\n# Restart your container with the new image\ndocker-compose up -d\n```\n\n**Check version:**\n```bash\nclaudetm --version\n```\n\n### Run a Task\n\n**Using the CLI:**\n```bash\ncd your-project\nclaudetm start \"Add user authentication with tests\"\n```\n\n**Using Docker:**\n```bash\n# Task execution is handled through the unified server\n# Create tasks via the REST API or MCP interface\ncurl -H \"Authorization: Bearer password\" \\\n     http://localhost:8000/tasks -X POST \\\n     -d '{\"goal\": \"Add user authentication\"}'\n```\n\n## Overview\n\nClaude Task Master uses the Claude Agent SDK to autonomously work on complex tasks. Give it a goal, and it will:\n\n1. **Plan** - Analyze codebase and create a task list organized by PRs\n2. **Execute** - Work through each task, committing and pushing changes\n3. **Create PRs** - All work is pushed and submitted as pull requests\n4. **Handle CI** - Wait for checks, fix failures, address review comments\n5. **Merge** - Auto-merge when approved (configurable)\n6. **Verify** - Confirm all success criteria are met\n7. **Adapt** - Accept dynamic plan updates via mailbox while working\n\n**Core Philosophy**: Claude is smart enough to do the work AND verify it. Task Master keeps the loop going and persists state between sessions.\n\n### Key Features\n\n- **Autonomous Execution** - Runs until goal is achieved or needs human input\n- **PR-Based Workflow** - All work flows through pull requests for review\n- **CI Integration** - Handles CI failures and review comments together\n- **Mailbox System** - Receive dynamic plan updates while working (via REST API, MCP, or CLI)\n- **Multi-Instance Coordination** - Multiple instances can communicate via mailbox\n- **State Persistence** - Survives interruptions, resumes where it left off\n\n## Workflow\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                         PLANNING                                 │\n│  Read codebase → Create task list → Define success criteria     │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                      WORKING (per task)                          │\n│  Make changes → Run tests → Commit → Push → Create PR           │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                       PR LIFECYCLE                               │\n│  Wait for CI → Fix failures → Address reviews → Merge           │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                       VERIFICATION                               │\n│  Run tests → Check lint → Verify criteria → Done                │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Work Completion Requirements\n\nEvery task must be:\n- **Committed** with a descriptive message\n- **Pushed** to remote (`git push -u origin HEAD`)\n- **In a PR** (`gh pr create ...`)\n\nWork is NOT complete until it's pushed and in a pull request.\n\n## Installation\n\n### Prerequisites\n\n1. **Python 3.10+** - [Install Python](https://www.python.org/downloads/)\n2. **Claude CLI** - [Install Claude](https://github.com/anthropics/anthropic-sdk-python) and run `claude` to authenticate\n3. **GitHub CLI** - [Install gh](https://cli.github.com/) and run `gh auth login`\n\n### Install Claude Task Master\n\n**Option 1: Using uv (recommended)**\n\n```bash\n# Install uv if you haven't already\ncurl https://astral.sh/uv/install.sh | sh\n\n# Install Claude Task Master\nuv sync\n\n# Verify installation\nuv run claudetm doctor\n```\n\n**Option 2: Using pip**\n\n```bash\n# Install from PyPI\npip install claude-task-master\n\n# Verify installation\nclaudetm doctor\n```\n\n**Option 3: Development installation**\n\n```bash\n# Clone the repository\ngit clone https://github.com/developerz-ai/claude-task-master\ncd claude-task-master\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n### Initial Setup\n\nRun the doctor command to verify everything is configured:\n\n```bash\nclaudetm doctor\n```\n\nThis checks for:\n- ✓ Claude CLI credentials at `~/.claude/.credentials.json`\n- ✓ GitHub CLI authentication\n- ✓ Git configuration\n- ✓ Python version compatibility\n\n## Configuration\n\nClaude Task Master uses a config file to override environment variables. This is useful for:\n- Using alternative API providers (OpenRouter, etc.)\n- Customizing model names\n- Setting project-specific settings\n\n### Create Config File\n\n```bash\n# Initialize default config\nclaudetm --init-config\n\n# View current config\nclaudetm --show-config\n```\n\nThis creates `.claude-task-master/config.json`:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"api\": {\n    \"anthropic_api_key\": null,\n    \"anthropic_base_url\": \"https://api.anthropic.com\",\n    \"openrouter_api_key\": null,\n    \"openrouter_base_url\": \"https://openrouter.ai/api/v1\"\n  },\n  \"models\": {\n    \"sonnet\": \"claude-sonnet-4-6\",\n    \"opus\": \"claude-opus-4-6\",\n    \"haiku\": \"claude-haiku-4-5-20251001\"\n  },\n  \"context_windows\": {\n    \"opus\": 200000,\n    \"sonnet\": 200000,\n    \"haiku\": 200000\n  },\n  \"git\": {\n    \"target_branch\": \"main\",\n    \"auto_push\": true\n  }\n}\n```\n\n\u003e **Note:** Opus 4.6 and Sonnet 4.5 support a 1M token context window in beta (**tier 4+** API access required). If you have tier 4+ access, you can increase the context windows:\n\u003e ```json\n\u003e \"context_windows\": {\n\u003e   \"opus\": 1000000,\n\u003e   \"sonnet\": 1000000,\n\u003e   \"haiku\": 200000\n\u003e }\n\u003e ```\n\n### Environment Variables\n\nThe config file sets these environment variables before Python starts:\n\n| Config Key | Environment Variable | Description |\n|------------|---------------------|-------------|\n| `api.anthropic_api_key` | `ANTHROPIC_API_KEY` | Anthropic API key |\n| `api.anthropic_base_url` | `ANTHROPIC_BASE_URL` | API base URL |\n| `api.openrouter_api_key` | `OPENROUTER_API_KEY` | OpenRouter API key |\n| `api.openrouter_base_url` | `OPENROUTER_BASE_URL` | OpenRouter base URL |\n| `models.sonnet` | `CLAUDETM_MODEL_SONNET` | Model for sonnet tier |\n| `models.opus` | `CLAUDETM_MODEL_OPUS` | Model for opus tier |\n| `models.haiku` | `CLAUDETM_MODEL_HAIKU` | Model for haiku tier |\n| `git.target_branch` | `CLAUDETM_TARGET_BRANCH` | Target branch for PRs |\n\n### Using OpenRouter\n\nTo use OpenRouter instead of direct Anthropic API:\n\n```json\n{\n  \"api\": {\n    \"openrouter_api_key\": \"sk-or-v1-xxx\",\n    \"openrouter_base_url\": \"https://openrouter.ai/api/v1\"\n  },\n  \"models\": {\n    \"sonnet\": \"anthropic/claude-sonnet-4\",\n    \"opus\": \"anthropic/claude-opus-4\",\n    \"haiku\": \"anthropic/claude-haiku\"\n  }\n}\n```\n\n### Debug Config Loading\n\n```bash\n# Enable debug mode to see config loading\nCLAUDETM_DEBUG=1 claudetm status\n```\n\n## Documentation\n\nComplete documentation for all features and deployment options:\n\n| Guide | Description |\n|-------|-------------|\n| **[Docker Deployment](./docs/docker.md)** | Docker installation, configuration, volume mounts, and production deployment |\n| **[Authentication](./docs/authentication.md)** | Password-based authentication for REST API, MCP server, and webhooks |\n| **[REST API Reference](./docs/api-reference.md)** | Complete REST API endpoint documentation with examples |\n| **[Webhooks](./docs/webhooks.md)** | Webhook events, payload formats, HMAC signature verification, and integration examples |\n| **[Mailbox System](./docs/mailbox.md)** | Inter-instance communication, dynamic plan updates, and multi-instance coordination |\n\n## Usage\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `claudetm start \"goal\"` | Start a new task |\n| `claudetm resume` | Resume a paused task |\n| `claudetm resume \"message\"` | Update plan with message, then resume |\n| `claudetm status` | Show current status |\n| `claudetm plan` | View task list |\n| `claudetm progress` | View progress summary |\n| `claudetm context` | View accumulated learnings |\n| `claudetm logs` | View session logs |\n| `claudetm pr` | Show PR status and CI checks |\n| `claudetm comments` | Show review comments |\n| `claudetm clean` | Clean up task state |\n| `claudetm doctor` | Verify system setup |\n| `claudetm mailbox` | Show mailbox status |\n| `claudetm mailbox send \"msg\"` | Send message to mailbox |\n| `claudetm mailbox clear` | Clear pending messages |\n\n### Start Options\n\n```bash\nclaudetm start \"Your goal here\" [OPTIONS]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--model` | Model to use (sonnet, opus, haiku) | sonnet |\n| `--auto-merge/--no-auto-merge` | Auto-merge PRs when ready | True |\n| `--max-sessions` | Limit number of sessions | unlimited |\n| `--prs` | Limit number of PRs to create | unlimited |\n| `--pause-on-pr` | Pause after creating PR | False |\n| `--budget` | Max spending per session in USD | unlimited |\n\n### Common Workflows\n\n```bash\n# Simple task with auto-merge\nclaudetm start \"Add factorial function to utils.py with tests\"\n\n# Complex task with manual review\nclaudetm start \"Refactor auth system\" --model opus --no-auto-merge\n\n# Limited sessions to prevent runaway\nclaudetm start \"Fix bug in parser\" --max-sessions 5\n\n# Limit number of PRs (forces everything into fewer PRs)\nclaudetm start \"Add user dashboard\" --prs 1\nclaudetm start \"Implement notifications\" --prs 3 --max-sessions 10\n\n# Cap spending per session\nclaudetm start \"Fix bug in login\" --budget 5.00\n\n# Monitor progress\nwatch -n 5 'claudetm status'\n\n# Resume with a change request (updates plan first)\nclaudetm resume \"Also add input validation to the forms\"\n\n# Send message to mailbox via REST API\ncurl -X POST http://localhost:8000/mailbox/send \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"Prioritize security fixes\", \"priority\": 2}'\n```\n\n## Examples \u0026 Use Cases\n\nCheck the [examples/](./examples/) directory for detailed walkthroughs:\n\n### Quick Examples\n\n```bash\n# Add a simple function\nclaudetm start \"Add a factorial function to utils.py with tests\"\n\n# Fix a bug\nclaudetm start \"Fix authentication timeout in login.py\" --no-auto-merge\n\n# Feature development\nclaudetm start \"Add dark mode toggle to settings\" --model opus\n\n# Refactoring\nclaudetm start \"Refactor API client to use async/await\" --max-sessions 5\n\n# Limit PRs for focused changes\nclaudetm start \"Add user authentication\" --prs 1\nclaudetm start \"Build admin dashboard\" --prs 2 --max-sessions 8\n\n# Documentation\nclaudetm start \"Add API documentation and examples\"\n```\n\n### Available Guides\n\n1. **[Basic Usage](./examples/01-basic-usage.md)** - Simple tasks and fundamentals\n2. **[Feature Development](./examples/02-feature-development.md)** - Building complete features\n3. **[Bug Fixing](./examples/03-bug-fixing.md)** - Debugging and fixing issues\n4. **[Code Refactoring](./examples/04-refactoring.md)** - Improving code structure\n5. **[Testing](./examples/05-testing.md)** - Adding test coverage\n6. **[Documentation](./examples/06-documentation.md)** - Documentation and examples\n7. **[CI/CD Integration](./examples/07-cicd.md)** - GitHub Actions workflows\n8. **[Advanced Workflows](./examples/08-advanced-workflows.md)** - Complex scenarios\n\n## AI Developer Workflow\n\nClaude Task Master includes built-in support for repository cloning and setup, enabling an AI-driven development environment. This is particularly useful for:\n\n- **AI Server Deployments** - Deploy Claude Task Master to servers and have it autonomously clone and setup projects\n- **Development Environment Setup** - Automatically configure repositories for local development\n- **Multi-Project Coordination** - Manage multiple projects simultaneously, each in isolated directories\n- **Continuous AI Development** - Receive work requests, setup projects, implement tasks, all autonomously\n\n### Repo Setup Workflow\n\nThe repo setup workflow consists of three phases:\n\n1. **Clone** - Clone a git repository to `~/workspace/claude-task-master/{project-name}`\n2. **Setup** - Automatically install dependencies, create virtual environments, run setup scripts\n3. **Plan or Work** - Either analyze the project and create a plan, or immediately start working on tasks\n\n### Clone a Repository\n\n**Via REST API:**\n```bash\ncurl -X POST http://localhost:8000/repo/clone \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"repo_url\": \"https://github.com/example/my-project.git\",\n    \"project_name\": \"my-project\"\n  }'\n```\n\n**Via MCP Tools (IDE Integration):**\n```\nClaude: Clone the repository https://github.com/example/my-project.git\n→ Uses clone_repo tool to clone to ~/workspace/claude-task-master/my-project\n```\n\n### Setup a Cloned Repository\n\nAfter cloning, setup installs dependencies and prepares the project for development:\n\n**Via REST API:**\n```bash\ncurl -X POST http://localhost:8000/repo/setup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project_name\": \"my-project\"\n  }'\n```\n\n**Via MCP Tools:**\n```\nClaude: Set up the project my-project for development\n→ Uses setup_repo tool to configure and prepare the repository\n```\n\nThe setup phase:\n- Detects project type (Python, Node.js, Ruby, etc.)\n- Installs package manager if needed (uv, npm, pip, bundler, etc.)\n- Creates virtual environments (venv, node_modules, etc.)\n- Runs setup scripts if present (setup.sh, Makefile, scripts/setup-hooks.sh, etc.)\n- Installs dependencies from lock files (requirements.txt, package.json, Gemfile, etc.)\n\n### Plan a Repository (Analysis Only)\n\nAnalyze a project and generate a task plan without executing work:\n\n**Via REST API:**\n```bash\ncurl -X POST http://localhost:8000/repo/plan \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project_name\": \"my-project\",\n    \"goal\": \"Add authentication to the application\"\n  }'\n```\n\n**Via MCP Tools:**\n```\nClaude: Plan the task \"Add authentication\" for project my-project\n→ Uses plan_repo tool to analyze and generate a task plan\n```\n\nThis phase creates a plan in `.claude-task-master/plan.md` without executing any tasks, allowing review before work begins.\n\n### Complete AI Developer Workflow Example\n\nA full end-to-end workflow:\n\n```bash\n# 1. Clone a repository\ncurl -X POST http://localhost:8000/repo/clone \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"repo_url\": \"https://github.com/example/myapp.git\", \"project_name\": \"myapp\"}'\n\n# 2. Setup the project for development\ncurl -X POST http://localhost:8000/repo/setup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"project_name\": \"myapp\"}'\n\n# 3. Plan the work (optional - just analyze)\ncurl -X POST http://localhost:8000/repo/plan \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"project_name\": \"myapp\", \"goal\": \"Add user authentication with OAuth\"}'\n\n# 4. Or start work directly with a goal\ncurl -X POST http://localhost:8000/task/init \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"project_dir\": \"~/workspace/claude-task-master/myapp\", \"goal\": \"Add user authentication with OAuth\"}'\n```\n\n### Directory Structure\n\nWhen using the repo setup workflow, projects are organized as follows:\n\n```\n~/workspace/claude-task-master/\n├── my-project/\n│   ├── .git/\n│   ├── src/\n│   ├── .claude-task-master/      # State directory (auto-created by claudetm)\n│   │   ├── goal.txt\n│   │   ├── plan.md\n│   │   ├── state.json\n│   │   └── logs/\n│   └── ...\n├── another-project/\n│   └── ...\n```\n\n### Use Cases\n\n**1. Server-Based AI Development Platform**\n\nDeploy Claude Task Master to a server with git credentials and have it:\n- Clone repositories on demand\n- Setup development environments automatically\n- Execute work assignments from a job queue\n- Report results via webhooks\n\n```bash\n# Server startup\ndocker run -d \\\n  -p 8000:8000 \\\n  -v ~/.claude:/root/.claude:ro \\\n  -v ~/.gitconfig:/root/.gitconfig:ro \\\n  -v ~/.config/gh:/root/.config/gh:ro \\\n  -v ~/workspace:/root/workspace \\\n  ghcr.io/developerz-ai/claude-task-master:latest\n\n# External system sends work\ncurl http://ai-dev-server:8000/repo/clone -d '{\"repo_url\": \"...\", \"project_name\": \"...\"}'\ncurl http://ai-dev-server:8000/repo/setup -d '{\"project_name\": \"...\"}'\ncurl http://ai-dev-server:8000/task/init -d '{\"project_dir\": \"...\", \"goal\": \"...\"}'\n```\n\n**2. Local Development Workspace Management**\n\nSetup a local workspace where Claude helps manage multiple projects:\n\n```bash\n# Initialize workspace\nmkdir -p ~/workspace/claude-task-master\ncd ~/workspace/claude-task-master\n\n# Clone and setup multiple projects\nclaudetm repo clone https://github.com/org/api-server api-server\nclaudetm repo setup api-server\n\nclaudetm repo clone https://github.com/org/web-client web-client\nclaudetm repo setup web-client\n\n# Work on individual projects\ncd api-server\nclaudetm start \"Add rate limiting to API endpoints\"\n\ncd ../web-client\nclaudetm start \"Implement dark mode toggle\"\n```\n\n**3. Continuous Integration as AI Development**\n\nIntegrate with CI/CD to have Claude automatically work on issues:\n\n```bash\n# GitHub Action or external trigger\ncurl http://localhost:8000/repo/clone \\\n  -d '{\"repo_url\": \"'$GITHUB_REPOSITORY'\", \"project_name\": \"repo\"}'\n\ncurl http://localhost:8000/repo/setup \\\n  -d '{\"project_name\": \"repo\"}'\n\ncurl http://localhost:8000/task/init \\\n  -d '{\"project_dir\": \"~/workspace/claude-task-master/repo\", \"goal\": \"'$ISSUE_TITLE'\"}'\n\n# Results reported via webhook callback\n```\n\n## Troubleshooting\n\n### Credentials \u0026 Setup\n\n#### \"Claude CLI credentials not found\"\n```bash\n# Run the Claude CLI to authenticate\nclaude\n\n# Verify credentials were saved\nls -la ~/.claude/.credentials.json\n\n# Run doctor to check setup\nclaudetm doctor\n```\n\n#### \"GitHub CLI not authenticated\"\n```bash\n# Authenticate with GitHub\ngh auth login\n\n# Verify authentication\ngh auth status\n```\n\n### Common Issues\n\n#### Task appears stuck or not progressing\n\n```bash\n# Check current status\nclaudetm status\n\n# View detailed logs\nclaudetm logs -n 100\n\n# If truly stuck, you can interrupt and resume\n# Press Ctrl+C, then:\nclaudetm resume\n```\n\n#### PR creation fails\n\n```bash\n# Verify you're in a git repository\ngit status\n\n# Verify remote is set up\ngit remote -v\n\n# Check if a PR already exists\ngh pr list\n\n# Run doctor to diagnose\nclaudetm doctor\n```\n\n#### Tests or linting failures\n\nThe system will handle failures and retry. To debug:\n\n```bash\n# Check the latest logs\nclaudetm logs\n\n# View progress summary\nclaudetm progress\n\n# See what Claude learned from errors\nclaudetm context\n```\n\n#### Clean up and restart\n\n```bash\n# Safe cleanup - removes state but keeps logs\nclaudetm clean\n\n# Force cleanup without confirmation\nclaudetm clean -f\n\n# Start fresh task\nclaudetm start \"Your new goal\"\n```\n\n### Performance Tips\n\n1. **Use the right model**:\n   - `opus` for complex tasks (default)\n   - `sonnet` for balanced speed/quality\n   - `haiku` for simple tasks\n\n2. **Limit sessions to prevent infinite loops**:\n   ```bash\n   claudetm start \"Task\" --max-sessions 10\n   ```\n\n3. **Manual review for critical changes**:\n   ```bash\n   claudetm start \"Task\" --no-auto-merge\n   ```\n\n4. **Monitor in another terminal**:\n   ```bash\n   watch -n 5 'claudetm status'\n   ```\n\n### Debug Mode\n\nView detailed execution information:\n\n```bash\n# Show recent log entries\nclaudetm logs -n 200\n\n# View current plan and progress\nclaudetm plan\nclaudetm progress\n\n# See accumulated context from previous sessions\nclaudetm context\n```\n\n## Architecture\n\nThe system follows SOLID principles with strict Single Responsibility:\n\n### Server Architecture\n\nWhen running with the unified server (`claudetm-server`), the following components work together:\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                      Claude Task Master Server                       │\n│                                                                       │\n│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐             │\n│  │  REST API    │   │  MCP Server  │   │   Webhooks   │             │\n│  │  (FastAPI)   │   │  (FastMCP)   │   │   (httpx)    │             │\n│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘             │\n│         │                  │                  │                      │\n│         └──────────────────┼──────────────────┘                      │\n│                            │                                         │\n│                    ┌───────▼───────┐                                 │\n│                    │ Auth Module   │                                 │\n│                    │ (Password)    │                                 │\n│                    └───────────────┘                                 │\n└─────────────────────────────────────────────────────────────────────┘\n\nDocker Container:\n┌─────────────────────────────────────────────────────────────────────┐\n│  claudetm-server                                                     │\n│                                                                       │\n│  Volumes:                                                            │\n│  - /app/project → project directory                                 │\n│  - /root/.claude → Claude credentials (~/.claude)                   │\n│                                                                       │\n│  Env: CLAUDETM_PASSWORD, CLAUDETM_WEBHOOK_URL, ...                   │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Server Features:**\n- **REST API** - Create and manage tasks, view status, manage webhooks\n- **MCP Server** - Claude editor integration for native IDE support\n- **Webhooks** - Send notifications on task events with HMAC verification\n- **Unified Authentication** - Single password protects all three interfaces\n- **Docker Ready** - Multi-arch image published to GitHub Container Registry\n\nFor detailed Docker deployment, see [Docker Deployment Guide](./docs/docker.md).\nFor authentication details, see [Authentication Guide](./docs/authentication.md).\n\n### Core Components\n\n| Component | Responsibility |\n|-----------|----------------|\n| **Credential Manager** | OAuth credential loading from `~/.claude/.credentials.json` |\n| **State Manager** | Persistence to `.claude-task-master/` directory |\n| **Agent Wrapper** | Claude Agent SDK interactions with streaming output |\n| **Planner** | Planning phase with read-only tools (Read, Glob, Grep, Bash) |\n| **Orchestrator** | Main execution loop and workflow stage management |\n| **GitHub Client** | PR creation, CI monitoring, comment handling |\n| **PR Cycle Manager** | Full PR lifecycle (create → CI → reviews → merge) |\n| **Context Accumulator** | Builds learnings across sessions |\n\n### Workflow Stages\n\n```\nworking → pr_created → waiting_ci → ci_failed → waiting_reviews → addressing_reviews → ready_to_merge → merged\n```\n\nEach stage has specific handlers that determine when to transition to the next stage.\n\n## State Directory\n\n```\n.claude-task-master/\n├── goal.txt              # Original user goal\n├── criteria.txt          # Success criteria\n├── plan.md               # Task list with checkboxes\n├── state.json            # Machine-readable state\n├── progress.md           # Progress summary\n├── context.md            # Accumulated learnings\n├── mailbox.json          # Pending messages for plan updates\n└── logs/\n    └── run-{timestamp}.txt    # Full log (kept on success)\n```\n\n## Exit Codes\n\n- **0 (Success)**: All tasks completed, criteria met. State cleaned up, logs preserved.\n- **1 (Blocked)**: Task cannot proceed, needs human intervention or error occurred.\n- **2 (Interrupted)**: User pressed Ctrl+C, state preserved for resume.\n\n## Development\n\n### Testing\n\n```bash\npytest                    # Run all tests\npytest -v                 # Verbose output\npytest -k \"test_name\"     # Run specific tests\n```\n\n### Linting \u0026 Formatting\n\n```bash\nruff check .              # Lint\nruff format .             # Format\nmypy .                    # Type check\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloperz-ai%2Fclaude-task-master","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeveloperz-ai%2Fclaude-task-master","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloperz-ai%2Fclaude-task-master/lists"}