Automating Claude-Based Development with Claude Task Master

Introduction

Developers using Claude Code often spend time managing pull requests, fixing CI failures, and handling review comments. Claude Task Master (CLI claudetm) removes that manual overhead by orchestrating the entire development loop autonomously. The tool reads a high-level goal, creates a detailed plan, executes code changes, opens pull requests, monitors CI, addresses feedback, and merges when the defined success criteria are satisfied. This article explains how the system works, its core features, and how to integrate it into existing workflows.

Core Concepts

Claude Task Master is built on the Claude Agent SDK and follows a PR-based workflow. The main concepts are:

• Planning - The CLI scans the repository, generates a list of tasks, and defines success criteria for each.
• Working - For each task it modifies the code, runs tests, commits, and pushes the changes.
• PR Lifecycle - All work is submitted as a pull request. The tool waits for CI, fixes any failures, addresses review comments, and merges when approved.
• Verification - After merging, the tool runs a final verification step to ensure all success criteria are met.
• State Persistence - The current state is saved to disk, allowing the process to survive interruptions and resume without loss of progress.
• Profiles - Multiple isolated Claude subscriptions can run in parallel using separate profiles.

Workflow Details

The typical workflow proceeds through four phases:

1. Planning - claudetm reads the codebase, creates a task list organized by pull requests, and writes a plan file. The plan includes the goal, the tasks, and the criteria that define success.
2. Working - The CLI executes each task in order. For each task it makes the required code changes, runs the test suite, commits the changes, and pushes them to a remote branch.
3. PR Lifecycle - Once a branch is pushed, a pull request is opened automatically. The tool monitors the CI checks, and if a check fails it attempts to fix the issue and pushes a new commit. Review comments are fetched via the GitHub API; the tool can apply suggested changes and push updates. When the PR receives approval and all checks pass, it is merged automatically (if auto-merge is configured).
4. Verification - After merging, a final verification step runs the full test suite, linting, and any custom validation scripts defined in the plan. Only when every criterion is satisfied does the task mark itself as complete.

Each phase can be interrupted at any point. Because the state is persisted, a subsequent run of claudetm picks up where it left off, re-establishes the PR, and continues the verification.

Profiles and Multi-Instance Coordination

Claude Task Master supports profiles to isolate credentials and configuration for multiple Claude subscriptions. A profile is a directory under ~/.claudetm/profiles/<name>/ containing its own Claude Code configuration. There are two profile types:

• OAuth profiles - Use the standard Claude Code login flow. Each profile maintains a separate ~/.claude directory, preventing credential clashes.
• API-key profiles - Directly inject an Anthropic-compatible API key and base URL via environment variables ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL.

Multiple instances of claudetm can run concurrently, each using a different profile. The instances communicate through a mailbox system (REST API, MCP server, or CLI) to exchange dynamic plan updates and status information.

Integration Points

Beyond the CLI, Claude Task Master offers three integration mechanisms:

• REST API - Allows external services to create tasks, query status, and receive updates via HTTP endpoints.
• MCP server - A lightweight message-passing server that routes plan updates and task events between instances.
• Webhooks - HMAC-signed HTTP callbacks that fire on key events such as PR creation, CI failure, or task completion. Webhooks enable custom actions like posting to Slack, triggering a deployment pipeline, or updating a dashboard.

These mechanisms make it possible to embed Claude Task Master in larger automation platforms, CI/CD pipelines, or custom developer tools.

Getting Started

The following steps show a minimal setup for a Python project. The same commands work for Ruby or JavaScript projects as long as the Claude CLI is authenticated.

# Install the CLI (uv, pip, or Docker are supported)
uv tool install claude-task-master

# Authenticate with Claude Code
claude login

# Navigate to your repository
cd your-project

# Start a task with a clear goal
claudetm start "Add user authentication with tests"

The CLI will create a plan, open a branch, push commits, and open a pull request. You can monitor progress with claudetm status or via the web UI provided by the REST API.

Advanced Usage

Handling Existing Pull Requests

If a pull request already exists, you can hand over its lifecycle to Claude Task Master:

claudetm merge-pr 42

The command takes ownership of the PR, monitors CI, fixes failures, and merges when ready.

Building a Dashboard

Using the REST API, you can query the list of active tasks, their current phase, and any pending actions. A simple Flask app can display this information in real time, giving managers visibility into the autonomous development process.

import requests
response = requests.get('https://your-server/api/tasks')
print(response.json())

Webhook Example

A webhook that posts a message to Slack after a successful merge might look like this:

import hmac, hashlib, json, requests

def verify_signature(payload, signature, secret):
    mac = hmac.new(secret.encode(), payload, hashlib.sha256)
    return hmac.compare_digest('sha256=' + mac.hexdigest(), signature)

def handle(event):
    if event['type'] == 'pr_merged':
        requests.post('https://hooks.slack.com/services/XXX/YYY/ZZZ', json={
            'text': f"PR #{event['pr_number']} merged successfully."
        })

Deploy this endpoint and register its URL in the Claude Task Master configuration.

Conclusion

Claude Task Master turns Claude Code into an autonomous development assistant that manages the full PR lifecycle, survives interruptions, and integrates with external systems via REST, MCP, and webhooks. By offloading repetitive tasks such as CI handling and review comment resolution, engineering teams can focus on higher-level design and architecture. The tool is open source under the MIT license and can be installed via PyPI or Docker. Give it a goal, walk away, and let the CLI deliver a merged pull request when the work is done.

Explore the repository for more details and contribution guidelines: https://github.com/developerz-ai/claude-task-master