Metadata-Version: 2.4
Name: claude-task-master
Version: 0.1.84
Summary: Autonomous task orchestration system that keeps Claude working until a goal is achieved
Author: Claude Task Master Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/developerz-ai/claude-task-master
Project-URL: Documentation, https://github.com/developerz-ai/claude-task-master#readme
Project-URL: Repository, https://github.com/developerz-ai/claude-task-master
Project-URL: Issues, https://github.com/developerz-ai/claude-task-master/issues
Project-URL: Changelog, https://github.com/developerz-ai/claude-task-master/blob/main/CHANGELOG.md
Keywords: claude,agent,autonomous,task,orchestration,ai,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claude-agent-sdk<0.3,>=0.2.126
Requires-Dist: typer<1,>=0.22.0
Requires-Dist: pydantic<3,>=2.12.0
Requires-Dist: rich<16,>=14.3.2
Requires-Dist: httpx<1,>=0.28.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.26.0; extra == "mcp"
Provides-Extra: api
Requires-Dist: fastapi>=0.128.7; extra == "api"
Requires-Dist: uvicorn[standard]>=0.40.0; extra == "api"
Requires-Dist: passlib[bcrypt]>=1.7.4; extra == "api"
Requires-Dist: bcrypt<5.0.0,>=4.0.0; extra == "api"
Provides-Extra: dev
Requires-Dist: claude-task-master[api]; extra == "dev"
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: hypothesis>=6.151.6; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16.1; extra == "dev"
Requires-Dist: mypy<2,>=1.19.0; extra == "dev"
Provides-Extra: all
Requires-Dist: claude-task-master[api,dev,mcp]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/developerz-ai/claude-task-master/main/assets/logo.png" alt="Claude Task Master" width="340">
</p>

<h1 align="center">Claude Task Master</h1>

[![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)
[![codecov](https://codecov.io/gh/developerz-ai/claude-task-master/graph/badge.svg)](https://codecov.io/gh/developerz-ai/claude-task-master)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/claude-task-master.svg)](https://badge.fury.io/py/claude-task-master)

Autonomous task orchestration system that keeps Claude working until a goal is achieved.

## Quick Start

### Installation

**Option 1: Using uv (recommended)**

```bash
# Install with uv
uv tool install claude-task-master
```

**Option 2: Using pip**

```bash
# Install from PyPI
pip install claude-task-master
```

**Option 3: Using Docker**

```bash
# Pull the official Docker image from GitHub Container Registry
docker pull ghcr.io/developerz-ai/claude-task-master:latest

# One time: give the agent its own scoped credential (never a human's ~/.claude)
docker volume create claudetm-profiles
docker run --rm -v claudetm-profiles:/home/claudetm/.claudetm \
  -e CLAUDETM_API_KEY="$AGENT_API_KEY" \
  ghcr.io/developerz-ai/claude-task-master:latest \
  claudetm profile add agent --type api-key --base-url https://your-gateway.example/anthropic

# Run with Docker
docker run -d \
  --name claudetm \
  -p 8000:8000 \
  -v claudetm-profiles:/home/claudetm/.claudetm \
  -e CLAUDETM_PROFILE=agent \
  -v $(pwd):/app/project \
  -v ~/.gitconfig:/home/claudetm/.gitconfig:ro \
  -v ~/.config/gh:/home/claudetm/.config/gh:ro \
  ghcr.io/developerz-ai/claude-task-master:latest
```

See [Docker Deployment Guide](./docs/docker.md) for detailed Docker setup, volume mounts, and configuration options.

### Authentication

Before using claudetm, you need to authenticate with Claude:

```bash
# Run Claude CLI and login (this saves credentials that claudetm will use)
claude
/login

# Verify claudetm can access credentials
claudetm doctor
```

**For Docker users:** containers do **not** use your `~/.claude` — never bind-mount it into one. The agent runs under its own scoped, rotatable API key held in an `api-key` profile; see [Agent Credentials](./docs/docker.md#1-agent-credentials-claudetm).

### Profiles (multiple accounts / custom endpoints)

By default claudetm uses the global `~/.claude/.credentials.json` session. **Profiles** let you run under isolated credentials so you can switch between Claude subscriptions — or a custom Anthropic-compatible endpoint — and even run several in parallel.

There are two profile types:

- **`oauth`** — an isolated Claude Code config home. Each profile gets its own credentials directory under `~/.claudetm/profiles/<name>/`, so two subscriptions never clobber each other.
- **`api-key`** — a direct API key + base URL (e.g. z.ai / GLM via an Anthropic-compatible endpoint), injected as `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. It can also carry **per-tier model and context-window overrides** so claudetm routes every complexity level to a model the endpoint actually serves.

```bash
# Create an oauth profile and log into it (opens claude in its isolated dir)
claudetm profile add work
claudetm profile login work          # run /login inside, then exit

# Create an api-key profile (e.g. z.ai). The key is read from the
# CLAUDETM_API_KEY env var or prompted for securely — never a CLI flag.
CLAUDETM_API_KEY=sk-... claudetm profile add zai --type api-key \
    --base-url https://api.z.ai/api/anthropic

# An api-key profile against a custom endpoint: name a model for each tier
# (and optionally its context size in tokens). Tiers you omit inherit from a
# family neighbour, so naming just opus/sonnet/haiku covers every task.
#
#   --model-opus        coding tasks (complex implementation) — the smart tier
#   --model-sonnet      general tasks (balanced)
#   --model-haiku       quick tasks (fast/cheap)
#   --model-sonnet-1m   debugging/QA (big context)  — defaults to sonnet
#   --model-fable       premium smart tier          — defaults to opus
CLAUDETM_API_KEY=sk-... claudetm profile add kimi --type api-key \
    --base-url https://api.kimi.com/coding \
    --model-opus k3 --model-sonnet k3 --model-haiku kimi-for-coding-highspeed \
    --context-opus 131072 --context-sonnet 131072

# Manage profiles
claudetm profile list                # active profile is marked with →
claudetm profile use work            # set the active profile
claudetm profile use default         # back to the ambient ~/.claude OAuth login
claudetm profile show                # show active profile (secrets masked)
claudetm profile remove zai
```

`default` is a built-in profile name, not a registry entry: it means the ordinary Claude Code login at `~/.claude` (or `CLAUDE_CONFIG_DIR`) — the credentials a run uses when no profile is selected. Selecting it clears the active pointer, so `claudetm profile use default` is how you get back to your normal subscription after switching to an isolated or api-key profile. It works as a `CLAUDETM_PROFILE=default` per-run override too.

The active profile's model overrides take precedence over the config file but yield to an explicit `CLAUDETM_MODEL_*` env var. claudetm passes the resolved model id to the SDK, and also emits Claude Code's native `ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL` so subagents resolve to provider-valid ids too.

The active profile applies to subsequent runs. Override it for a single run with the `CLAUDETM_PROFILE` environment variable:

```bash
# Run two subscriptions in parallel from two checkouts
CLAUDETM_PROFILE=accountA claudetm start "..."   # in repo-a/
CLAUDETM_PROFILE=accountB claudetm start "..."   # in repo-b/
```

Because each profile has its own credentials directory and run state is per-project, **different subscriptions run in parallel without colliding**. Storage location is overridable with `CLAUDETM_HOME` (defaults to `~/.claudetm`).

> **Note:** Parallel isolation is between *different accounts*. Running two copies of the *same* subscription in parallel can still trigger OAuth refresh-token rotation that invalidates the other session — use a distinct account (profile) per concurrent run.

### Upgrading

**With uv:**
```bash
uv tool install claude-task-master --force --reinstall
```

**With pip:**
```bash
pip install --upgrade claude-task-master
```

**With Docker:**
```bash
# Pull the latest image
docker pull ghcr.io/developerz-ai/claude-task-master:latest

# Restart your container with the new image
docker-compose up -d
```

**Check version:**
```bash
claudetm --version
```

### Run a Task

**Using the CLI:**
```bash
cd your-project
claudetm start "Add user authentication with tests"
```

**Using Docker:**
```bash
# Task execution is handled through the unified server
# Create tasks via the REST API or MCP interface
curl -H "Authorization: Bearer password" \
     http://localhost:8000/tasks -X POST \
     -d '{"goal": "Add user authentication"}'
```

## Overview

Claude Task Master uses the Claude Agent SDK to autonomously work on complex tasks. Give it a goal, and it will:

1. **Plan** - Analyze codebase and create a task list organized by PRs
2. **Execute** - Work through each task, committing and pushing changes
3. **Create PRs** - All work is pushed and submitted as pull requests
4. **Handle CI** - Wait for checks, fix failures, address review comments
5. **Merge** - Auto-merge once CI is green and review feedback is resolved (configurable)
6. **Verify** - Confirm all success criteria are met
7. **Adapt** - Accept dynamic plan updates via mailbox while working

**Core Philosophy**: Claude is smart enough to do the work AND verify it. Task Master keeps the loop going and persists state between sessions.

### Key Features

- **Autonomous Execution** - Runs until goal is achieved or needs human input
- **PR-Based Workflow** - All work flows through pull requests for review
- **CI Integration** - Handles CI failures and review comments together
- **Conflict Resolution** - Merges the base branch and resolves conflicts with an agent instead of blocking
- **Never Merges Stale** - A PR behind production is re-synced and re-tested by an agent before it merges
- **Mailbox System** - Receive dynamic plan updates while working (via REST API, MCP, or CLI)
- **Multi-Instance Coordination** - Multiple instances can communicate via mailbox
- **State Persistence** - Survives interruptions, resumes where it left off

## Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                         PLANNING                                 │
│  Read codebase → Create task list → Define success criteria     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      WORKING (per task)                          │
│  Make changes → Run tests → Commit → Push → Create PR           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                       PR LIFECYCLE                               │
│  Wait for CI → Fix failures → Address reviews → Resolve         │
│  conflicts → Merge                                              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                       VERIFICATION                               │
│  Run tests → Check lint → Verify criteria → Done                │
└─────────────────────────────────────────────────────────────────┘
```

### Work Completion Requirements

Every task must be:
- **Committed** with a descriptive message
- **Pushed** to remote (`git push -u origin HEAD`)
- **In a PR** (`gh pr create ...`)

Work is NOT complete until it's pushed and in a pull request.

## Installation

### Prerequisites

1. **Python 3.10+** - [Install Python](https://www.python.org/downloads/)
2. **Claude CLI** - [Install Claude](https://github.com/anthropics/anthropic-sdk-python) and run `claude` to authenticate
3. **GitHub CLI** - [Install gh](https://cli.github.com/) and run `gh auth login`

### Install Claude Task Master

**Option 1: Using uv (recommended)**

```bash
# Install uv if you haven't already
curl https://astral.sh/uv/install.sh | sh

# Install Claude Task Master
uv sync

# Verify installation
uv run claudetm doctor
```

**Option 2: Using pip**

```bash
# Install from PyPI
pip install claude-task-master

# Verify installation
claudetm doctor
```

**Option 3: Development installation**

```bash
# Clone the repository
git clone https://github.com/developerz-ai/claude-task-master
cd claude-task-master

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest
```

### Initial Setup

Run the doctor command to verify everything is configured:

```bash
claudetm doctor
```

This checks for:
- ✓ Claude CLI credentials at `~/.claude/.credentials.json`
- ✓ GitHub CLI authentication
- ✓ Git configuration
- ✓ Python version compatibility

## Configuration

Claude Task Master uses a config file to override environment variables. This is useful for:
- Using alternative API providers (OpenRouter, etc.)
- Customizing model names
- Setting project-specific settings

### Create Config File

```bash
# Initialize default config
claudetm --init-config

# View current config
claudetm --show-config
```

This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defaults to **Claude Opus 5** (`claude-opus-5`), whose context window is **1M tokens natively** — so `context_windows.opus` defaults to `1000000`. (There is no `claude-opus-5[1m]` model ID; that suffix is a Claude Code CLI convention and 404s against the API.) Override the model by editing the `"opus"` key or setting `CLAUDETM_MODEL_OPUS`; drop `context_windows.opus` to `200000` if your account is capped at standard context. A separate opt-in `fable` tier defaults to **Claude Fable 5** (`claude-fable-5`, premium-priced at 2x Opus) — mirroring Claude Code's `ANTHROPIC_DEFAULT_FABLE_MODEL`; override via the `"fable"` key or `CLAUDETM_MODEL_FABLE`. No task routes to it by default; set `CLAUDETM_MODEL_OPUS=claude-fable-5` to run the smartest tier on Fable.

```json
{
  "version": "1.0",
  "api": {
    "anthropic_api_key": null,
    "anthropic_base_url": "https://api.anthropic.com",
    "openrouter_api_key": null,
    "openrouter_base_url": "https://openrouter.ai/api/v1"
  },
  "models": {
    "sonnet": "claude-sonnet-5",
    "opus": "claude-opus-5",
    "fable": "claude-fable-5",
    "haiku": "claude-haiku-4-5"
  },
  "context_windows": {
    "opus": 1000000,
    "fable": 1000000,
    "sonnet": 200000,
    "haiku": 200000
  },
  "git": {
    "target_branch": "main",
    "auto_push": true
  }
}
```

> **Note:** `context_windows` only drives claudetm's **auto-compact threshold** — it does not grant a bigger window. Over-stating a window means compaction fires too late and the session overflows; under-stating it just compacts early, which is harmless. So the defaults are deliberately conservative, and only `opus` claims 1M:
>
> | Tier | Default | Why |
> |---|---|---|
> | `opus` | 1000000 | Opus is upgraded to 1M automatically on Max/Team/Enterprise. **On Pro that upgrade is billed to usage credits** — set `200000` if you don't buy them. |
> | `sonnet` | 200000 | Conservative. On a subscription the 1M window is the paid extra, so this only goes to `1000000` once you've confirmed your account actually serves it. |
> | `haiku` | 200000 | Haiku 4.5's real window. |
>
> Two setups cap 1M-capable models at 200K regardless of plan, and want `200000` for every tier: an LLM gateway (`ANTHROPIC_BASE_URL` pointing somewhere Claude Code can't verify 1M support) and `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`.
> ```json
> "context_windows": {
>   "opus": 200000,
>   "sonnet": 200000,
>   "haiku": 200000
> }
> ```

### Environment Variables

The config file sets these environment variables before Python starts:

| Config Key | Environment Variable | Description |
|------------|---------------------|-------------|
| `api.anthropic_api_key` | `ANTHROPIC_API_KEY` | Anthropic API key |
| `api.anthropic_base_url` | `ANTHROPIC_BASE_URL` | API base URL |
| `api.openrouter_api_key` | `OPENROUTER_API_KEY` | OpenRouter API key |
| `api.openrouter_base_url` | `OPENROUTER_BASE_URL` | OpenRouter base URL |
| `models.sonnet` | `CLAUDETM_MODEL_SONNET` | Model for sonnet tier |
| `models.opus` | `CLAUDETM_MODEL_OPUS` | Model for opus tier |
| `models.fable` | `CLAUDETM_MODEL_FABLE` | Model for fable tier (opt-in, premium) |
| `models.haiku` | `CLAUDETM_MODEL_HAIKU` | Model for haiku tier |
| `models.sonnet_1m` | `CLAUDETM_MODEL_SONNET_1M` | Model for debugging/QA tier (big context) |
| `context_windows.*` | `CLAUDETM_CONTEXT_{OPUS,FABLE,SONNET,HAIKU,SONNET_1M}` | Context window per tier (tokens) |
| `git.target_branch` | `CLAUDETM_TARGET_BRANCH` | Target branch for PRs |

Precedence (highest first): real environment variables, then the **active profile** (api-key/oauth profiles supply these same keys), then the config file.

**Session limits** (environment only — sensible defaults, rarely need changing):

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `CLAUDETM_MAX_TURNS` | `400` | Max agent steps per session — a runaway backstop, not a working budget. Set `0` to disable. Overrunning retries the task rather than marking it done |
| `CLAUDETM_STREAM_IDLE_TIMEOUT_SEC` | `1800` | Max silence between SDK stream messages before treating the stream as hung |
| `CLAUDETM_POST_COMPLETION_IDLE_TIMEOUT_SEC` | `120` | Max wait for the final result message after the agent signals it's done |
| `CLAUDETM_HIVE_MAX_PARALLEL` | `10` | Safety ceiling on concurrent `hive-worker` subagents (1 lead + up to N workers) — a ceiling, not a target; the lead sizes its own team |

Sessions are bounded in steps, not wall-clock: a wall-clock cap would punish a slow-but-healthy session (big test suite, slow CI) exactly as hard as a looping one. Use `--budget` for a per-session cost cap.

### Using OpenRouter

To use OpenRouter instead of direct Anthropic API:

```json
{
  "api": {
    "openrouter_api_key": "sk-or-v1-xxx",
    "openrouter_base_url": "https://openrouter.ai/api/v1"
  },
  "models": {
    "sonnet": "anthropic/claude-sonnet-4",
    "opus": "anthropic/claude-opus-4",
    "haiku": "anthropic/claude-haiku"
  }
}
```

### Debug Config Loading

```bash
# Enable debug mode to see config loading
CLAUDETM_DEBUG=1 claudetm status
```

## Documentation

Complete documentation for all features and deployment options:

| Guide | Description |
|-------|-------------|
| **[Docker Deployment](./docs/docker.md)** | Docker installation, configuration, volume mounts, and production deployment |
| **[Authentication](./docs/authentication.md)** | Password-based authentication for REST API, MCP server, and webhooks |
| **[REST API Reference](./docs/api-reference.md)** | Complete REST API endpoint documentation with examples |
| **[Webhooks](./docs/webhooks.md)** | Webhook events, payload formats, HMAC signature verification, and integration examples |
| **[Mailbox System](./docs/mailbox.md)** | Inter-instance communication, dynamic plan updates, and multi-instance coordination |

## Usage

### CLI Commands

| Command | Description |
|---------|-------------|
| `claudetm start "goal"` | Start a new task |
| `claudetm resume` | Resume a paused task |
| `claudetm resume "message"` | Update plan with message, then resume |
| `claudetm status` | Show current status |
| `claudetm plan` | View task list |
| `claudetm progress` | View progress summary |
| `claudetm context` | View accumulated learnings |
| `claudetm logs` | View session logs |
| `claudetm pr` | Show PR status and CI checks |
| `claudetm comments` | Show review comments |
| `claudetm clean` | Clean up task state |
| `claudetm doctor` | Verify system setup |
| `claudetm mailbox` | Show mailbox status |
| `claudetm mailbox send "msg"` | Send message to mailbox |
| `claudetm mailbox clear` | Clear pending messages |
| `claudetm update` | Self-update to the latest PyPI release (`--check` to only check) |

### Start Options

```bash
claudetm start "Your goal here" [OPTIONS]
```

| Option | Description | Default |
|--------|-------------|---------|
| `--model` | Model to use (sonnet, opus, haiku) | sonnet |
| `--auto-merge/--no-auto-merge` | Auto-merge PRs once CI is green and review feedback is resolved (no approving review is required) | True |
| `--max-sessions` | Limit number of sessions | unlimited |
| `--prs` | Limit number of PRs to create | unlimited |
| `--pause-on-pr` | Pause after creating PR | False |
| `--resolve-conflicts/--no-resolve-conflicts` | Let an agent rebase onto the base and resolve merge conflicts (3 attempts, then block) | True |
| `--sync-before-merge/--no-sync-before-merge` | Also rebase PRs that merely trail the base, so CI verifies the combined tree (3 attempts, then merge as-is) | False |
| `--parallel/--no-parallel` | Let each work session split its one task across `hive-worker` subagents with disjoint write sets | True |
| `--admin` | Merge via `gh pr merge --admin`, overriding base-branch protection (requires repo-admin rights) | False |
| `--budget` | Max spending per session in USD | unlimited |

#### When you need `--admin`

Green CI is not always enough to merge. If the base branch requires **an approving review**, a required check the run can't satisfy, or any other protection rule, `gh pr merge` is refused with:

```
Pull request #NNN is not mergeable: the base branch policy prohibits the merge.
```

The run then blocks with a finished, green PR it isn't allowed to land. `--admin` merges past the rule, which is what you want for an unattended run on a repo you own:

```bash
claudetm start "Your goal here" --admin
claudetm merge-pr 42 --admin          # same override for a single PR
claudetm resume --admin               # or turn it on mid-run
```

It requires repo-admin rights and it is a real override — the review requirement is bypassed, not satisfied. On a repo where those reviews are the point, leave it off and merge by hand.

`--admin` also force-advances a check **timeout** (`CI_POLL_TIMEOUT`, 120 min) instead of blocking — at the CI stage and at the review stage alike, both of which block by default. It does not skip CI, ignore failures, or merge a conflicted PR: failing checks still route to the fix loop, and conflicts still go to the resolver.

It also does **not** override a **`CHANGES_REQUESTED`** review. Auto-merge never requires an *approving* review — that is the whole reason `--admin` exists — but a reviewer who actively requested changes is a human pushing back, and claudetm refuses to merge over that even with `--admin`. Clear it on GitHub by approving or dismissing the review; the run continues on its own from the next cycle.

#### Parallel work inside a task (`--parallel`, on by default)

Each work session still owns exactly one task from the plan. What `--parallel` adds is that the agent running that session is a **lead**: if *its own task* breaks into pieces with **disjoint write sets**, it hands those pieces to `hive-worker` subagents running concurrently and does everything that overlaps itself.

```bash
claudetm start "Port 20 view models to the new API"     # parallel by default
claudetm start "Tweak the retry backoff" --no-parallel  # strictly one agent per session
claudetm config-update --no-parallel                    # turn it off mid-run
```

**The lead decides how many workers it needs — including none.** Nothing outside the session can tell how big a task is before it runs, so the split is the lead's judgement, not a number claudetm computes. Most tasks come back with zero workers, and that is the right answer: fan-out is not free, because every worker pays a full cold start re-reading the repo. Spawning four agents for four one-line edits costs more than doing them inline.

**Everyone shares this one checkout.** No git worktrees, no clones, no per-agent copies — the work has to land in the tree the lead commits from. Each worker gets an exclusive file set in its brief, and that is the only lock there is; a worker that needs a file it does not own stops and reports instead of reaching across.

**Only the lead runs git.** Workers read, edit and run narrow checks; they never stage, commit, branch or push. The lead waits for every worker to finish, verifies the changes on disk itself, runs the full project gate, and only then commits, pushes and opens the PR — exactly as a single-agent session does.

Cap the fan-out with `CLAUDETM_HIVE_MAX_PARALLEL` (default 10 = one lead plus up to 10 workers). It is a safety ceiling, not a target.

Use `--no-parallel` when you want every session strictly single-agent — debugging a run, or a repo where concurrent edits are hard to reason about.

### Common Workflows

```bash
# Simple task with auto-merge
claudetm start "Add factorial function to utils.py with tests"

# Complex task with manual review
claudetm start "Refactor auth system" --model opus --no-auto-merge

# Limited sessions to prevent runaway
claudetm start "Fix bug in parser" --max-sessions 5

# Limit number of PRs (forces everything into fewer PRs)
claudetm start "Add user dashboard" --prs 1
claudetm start "Implement notifications" --prs 3 --max-sessions 10

# Cap spending per session
claudetm start "Fix bug in login" --budget 5.00

# Monitor progress
watch -n 5 'claudetm status'

# Resume with a change request (updates plan first)
claudetm resume "Also add input validation to the forms"

# Send message to mailbox via REST API
curl -X POST http://localhost:8000/mailbox/send \
  -H "Content-Type: application/json" \
  -d '{"content": "Prioritize security fixes", "priority": 2}'
```

## Examples & Use Cases

Check the [examples/](./examples/) directory for detailed walkthroughs:

### Quick Examples

```bash
# Add a simple function
claudetm start "Add a factorial function to utils.py with tests"

# Fix a bug
claudetm start "Fix authentication timeout in login.py" --no-auto-merge

# Feature development
claudetm start "Add dark mode toggle to settings" --model opus

# Refactoring
claudetm start "Refactor API client to use async/await" --max-sessions 5

# Limit PRs for focused changes
claudetm start "Add user authentication" --prs 1
claudetm start "Build admin dashboard" --prs 2 --max-sessions 8

# Documentation
claudetm start "Add API documentation and examples"
```

### Available Guides

1. **[Basic Usage](./examples/01-basic-usage.md)** - Simple tasks and fundamentals
2. **[Feature Development](./examples/02-feature-development.md)** - Building complete features
3. **[Bug Fixing](./examples/03-bug-fixing.md)** - Debugging and fixing issues
4. **[Code Refactoring](./examples/04-refactoring.md)** - Improving code structure
5. **[Testing](./examples/05-testing.md)** - Adding test coverage
6. **[Documentation](./examples/06-documentation.md)** - Documentation and examples
7. **[CI/CD Integration](./examples/07-cicd.md)** - GitHub Actions workflows
8. **[Advanced Workflows](./examples/08-advanced-workflows.md)** - Complex scenarios

## AI Developer Workflow

Claude Task Master includes built-in support for repository cloning and setup, enabling an AI-driven development environment. This is particularly useful for:

- **AI Server Deployments** - Deploy Claude Task Master to servers and have it autonomously clone and setup projects
- **Development Environment Setup** - Automatically configure repositories for local development
- **Multi-Project Coordination** - Manage multiple projects simultaneously, each in isolated directories
- **Continuous AI Development** - Receive work requests, setup projects, implement tasks, all autonomously

### Repo Setup Workflow

The repo setup workflow consists of three phases:

1. **Clone** - Clone a git repository to `~/workspace/claude-task-master/{project-name}`
2. **Setup** - Automatically install dependencies, create virtual environments, run setup scripts
3. **Plan or Work** - Either analyze the project and create a plan, or immediately start working on tasks

### Clone a Repository

**Via REST API:**
```bash
curl -X POST http://localhost:8000/repo/clone \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/example/my-project.git",
    "project_name": "my-project"
  }'
```

**Via MCP Tools (IDE Integration):**
```
Claude: Clone the repository https://github.com/example/my-project.git
→ Uses clone_repo tool to clone to ~/workspace/claude-task-master/my-project
```

### Setup a Cloned Repository

After cloning, setup installs dependencies and prepares the project for development:

**Via REST API:**
```bash
curl -X POST http://localhost:8000/repo/setup \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-project"
  }'
```

**Via MCP Tools:**
```
Claude: Set up the project my-project for development
→ Uses setup_repo tool to configure and prepare the repository
```

The setup phase:
- Detects project type (Python, Node.js, Ruby, etc.)
- Installs package manager if needed (uv, npm, pip, bundler, etc.)
- Creates virtual environments (venv, node_modules, etc.)
- Runs setup scripts if present (setup.sh, Makefile, scripts/setup-hooks.sh, etc.)
- Installs dependencies from lock files (requirements.txt, package.json, Gemfile, etc.)

### Plan a Repository (Analysis Only)

Analyze a project and generate a task plan without executing work:

**Via REST API:**
```bash
curl -X POST http://localhost:8000/repo/plan \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-project",
    "goal": "Add authentication to the application"
  }'
```

**Via MCP Tools:**
```
Claude: Plan the task "Add authentication" for project my-project
→ Uses plan_repo tool to analyze and generate a task plan
```

This phase creates a plan in `.claude-task-master/plan.md` without executing any tasks, allowing review before work begins.

### Complete AI Developer Workflow Example

A full end-to-end workflow:

```bash
# 1. Clone a repository
curl -X POST http://localhost:8000/repo/clone \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/example/myapp.git", "project_name": "myapp"}'

# 2. Setup the project for development
curl -X POST http://localhost:8000/repo/setup \
  -H "Content-Type: application/json" \
  -d '{"project_name": "myapp"}'

# 3. Plan the work (optional - just analyze)
curl -X POST http://localhost:8000/repo/plan \
  -H "Content-Type: application/json" \
  -d '{"project_name": "myapp", "goal": "Add user authentication with OAuth"}'

# 4. Or start work directly with a goal
curl -X POST http://localhost:8000/task/init \
  -H "Content-Type: application/json" \
  -d '{"project_dir": "~/workspace/claude-task-master/myapp", "goal": "Add user authentication with OAuth"}'
```

### Directory Structure

When using the repo setup workflow, projects are organized as follows:

```
~/workspace/claude-task-master/
├── my-project/
│   ├── .git/
│   ├── src/
│   ├── .claude-task-master/      # State directory (auto-created by claudetm)
│   │   ├── goal.txt
│   │   ├── plan.md              # Task plan with per-PR release checks
│   │   ├── state.json
│   │   ├── coding-style.md      # Generated coding conventions
│   │   ├── release.md           # Generated deploy/release guide
│   │   └── logs/
│   └── ...
├── another-project/
│   └── ...
```

### Use Cases

**1. Server-Based AI Development Platform**

Deploy Claude Task Master to a server with git credentials and have it:
- Clone repositories on demand
- Setup development environments automatically
- Execute work assignments from a job queue
- Report results via webhooks

```bash
# Server startup
docker run -d \
  -p 8000:8000 \
  -v claudetm-profiles:/home/claudetm/.claudetm \
  -e CLAUDETM_PROFILE=agent \
  -v ~/.gitconfig:/home/claudetm/.gitconfig:ro \
  -v ~/.config/gh:/home/claudetm/.config/gh:ro \
  -v ~/workspace:/home/claudetm/workspace \
  ghcr.io/developerz-ai/claude-task-master:latest

# External system sends work
curl http://ai-dev-server:8000/repo/clone -d '{"repo_url": "...", "project_name": "..."}'
curl http://ai-dev-server:8000/repo/setup -d '{"project_name": "..."}'
curl http://ai-dev-server:8000/task/init -d '{"project_dir": "...", "goal": "..."}'
```

**2. Local Development Workspace Management**

Setup a local workspace where Claude helps manage multiple projects:

```bash
# Initialize workspace
mkdir -p ~/workspace/claude-task-master
cd ~/workspace/claude-task-master

# Clone and setup multiple projects
claudetm repo clone https://github.com/org/api-server api-server
claudetm repo setup api-server

claudetm repo clone https://github.com/org/web-client web-client
claudetm repo setup web-client

# Work on individual projects
cd api-server
claudetm start "Add rate limiting to API endpoints"

cd ../web-client
claudetm start "Implement dark mode toggle"
```

**3. Continuous Integration as AI Development**

Integrate with CI/CD to have Claude automatically work on issues:

```bash
# GitHub Action or external trigger
curl http://localhost:8000/repo/clone \
  -d '{"repo_url": "'$GITHUB_REPOSITORY'", "project_name": "repo"}'

curl http://localhost:8000/repo/setup \
  -d '{"project_name": "repo"}'

curl http://localhost:8000/task/init \
  -d '{"project_dir": "~/workspace/claude-task-master/repo", "goal": "'$ISSUE_TITLE'"}'

# Results reported via webhook callback
```

## Troubleshooting

### Credentials & Setup

#### "Claude CLI credentials not found"
```bash
# Run the Claude CLI to authenticate
claude

# Verify credentials were saved
ls -la ~/.claude/.credentials.json

# Run doctor to check setup
claudetm doctor
```

#### "GitHub CLI not authenticated"
```bash
# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status
```

### Common Issues

#### Task appears stuck or not progressing

```bash
# Check current status
claudetm status

# View detailed logs
claudetm logs -n 100

# If truly stuck, you can interrupt and resume
# Press Ctrl+C, then:
claudetm resume
```

#### PR creation fails

```bash
# Verify you're in a git repository
git status

# Verify remote is set up
git remote -v

# Check if a PR already exists
gh pr list

# Run doctor to diagnose
claudetm doctor
```

#### Tests or linting failures

The system will handle failures and retry. To debug:

```bash
# Check the latest logs
claudetm logs

# View progress summary
claudetm progress

# See what Claude learned from errors
claudetm context
```

#### Clean up and restart

```bash
# Safe cleanup - removes state but keeps logs
claudetm clean

# Force cleanup without confirmation
claudetm clean -f

# Start fresh task
claudetm start "Your new goal"
```

### Performance Tips

1. **Use the right model**:
   - `opus` for complex tasks (default)
   - `sonnet` for balanced speed/quality
   - `haiku` for simple tasks

2. **Limit sessions to prevent infinite loops**:
   ```bash
   claudetm start "Task" --max-sessions 10
   ```

3. **Manual review for critical changes**:
   ```bash
   claudetm start "Task" --no-auto-merge
   ```

4. **Monitor in another terminal**:
   ```bash
   watch -n 5 'claudetm status'
   ```

### Debug Mode

View detailed execution information:

```bash
# Show recent log entries
claudetm logs -n 200

# View current plan and progress
claudetm plan
claudetm progress

# See accumulated context from previous sessions
claudetm context
```

## Architecture

The system follows SOLID principles with strict Single Responsibility:

### Server Architecture

When running with the unified server (`claudetm-server`), the following components work together:

```
┌─────────────────────────────────────────────────────────────────────┐
│                      Claude Task Master Server                       │
│                                                                       │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐             │
│  │  REST API    │   │  MCP Server  │   │   Webhooks   │             │
│  │  (FastAPI)   │   │  (FastMCP)   │   │   (httpx)    │             │
│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘             │
│         │                  │                  │                      │
│         └──────────────────┼──────────────────┘                      │
│                            │                                         │
│                    ┌───────▼───────┐                                 │
│                    │ Auth Module   │                                 │
│                    │ (Password)    │                                 │
│                    └───────────────┘                                 │
└─────────────────────────────────────────────────────────────────────┘

Docker Container:
┌─────────────────────────────────────────────────────────────────────┐
│  claudetm-server                                                     │
│                                                                       │
│  Volumes:                                                            │
│  - /app/project → project directory                                 │
│  - /home/claudetm/.claudetm → agent api-key profile (scoped key)    │
│                                                                       │
│  Env: CLAUDETM_PASSWORD, CLAUDETM_WEBHOOK_URL, ...                   │
└─────────────────────────────────────────────────────────────────────┘
```

**Server Features:**
- **REST API** - Create and manage tasks, view status, manage webhooks
- **MCP Server** - Claude editor integration for native IDE support
- **Webhooks** - Send notifications on task events with HMAC verification
- **Unified Authentication** - Single password protects all three interfaces
- **Docker Ready** - Multi-arch image published to GitHub Container Registry

For detailed Docker deployment, see [Docker Deployment Guide](./docs/docker.md).
For authentication details, see [Authentication Guide](./docs/authentication.md).

### Core Components

| Component | Responsibility |
|-----------|----------------|
| **Credential Manager** | OAuth credential loading from `~/.claude/.credentials.json` |
| **State Manager** | Persistence to `.claude-task-master/` directory |
| **Agent Wrapper** | Claude Agent SDK interactions with streaming output |
| **Planner** | Planning phase with read-only tools (Read, Glob, Grep, Bash) |
| **Orchestrator** | Main execution loop and workflow stage management |
| **GitHub Client** | PR creation, CI monitoring, comment handling |
| **PR Cycle Manager** | Full PR lifecycle (create → CI → reviews → merge) |
| **Context Accumulator** | Builds learnings across sessions |

### Workflow Stages

```
working → pr_created → waiting_ci → ci_failed → waiting_reviews → addressing_reviews → ready_to_merge → merged → releasing → release_fix
                                                                          ↑                    ↓
                                                                          └── resolving_conflicts (on CONFLICTING)
```

Each stage has specific handlers that determine when to transition to the next stage.

**Release phase** (stages `releasing` and `release_fix`) runs automatically after each PR merge when `auto_merge=True`. It verifies the deployment is healthy using whatever access is available (health checks, deploy status, error monitoring, DB migrations). If nothing is checkable, it's a no-op. If verification fails, creates a quick-fix PR (max 5 attempts).

## State Directory

```
.claude-task-master/
├── goal.txt              # Original user goal
├── criteria.txt          # Success criteria
├── plan.md               # Task list with checkboxes + per-PR release checks
├── state.json            # Machine-readable state
├── progress.md           # Progress summary
├── context.md            # Accumulated learnings
├── coding-style.md       # Generated coding conventions (preserved across runs)
├── release.md            # Generated deploy/release guide (preserved across runs)
├── mailbox.json          # Pending messages for plan updates
└── logs/
    └── run-{timestamp}.txt    # Full log (kept on success)
```

## Exit Codes

- **0 (Success)**: All tasks completed, criteria met. State cleaned up (logs, coding-style.md, release.md preserved).
- **1 (Blocked)**: Task cannot proceed, needs human intervention or error occurred.
- **2 (Interrupted)**: User pressed Ctrl+C, state preserved for resume.

## Development

### Testing

```bash
pytest                    # Run all tests
pytest -v                 # Verbose output
pytest -k "test_name"     # Run specific tests
```

### Linting & Formatting

```bash
ruff check .              # Lint
ruff format .             # Format
mypy .                    # Type check
```

## License

MIT
