Automating Claude Code Workflows with Claude Task Master

Introduction

Claude Task Master (CLI claudetm) is an autonomous orchestration layer built on the Claude Agent SDK. It keeps Claude working until a goal is achieved by planning, executing, opening pull requests, handling CI failures and merging automatically. This article explains how the system works, how to set it up, and how to extend it with the provided REST API.

Core Workflow

The workflow follows a clear loop: planning, working, pull request lifecycle, verification. In the planning stage the tool scans the codebase, creates a task list and defines success criteria. During the working stage it makes changes, runs tests, commits and pushes each task. All changes are pushed as pull requests, never as direct commits. The pull request lifecycle waits for CI checks, fixes failures, addresses review comments and merges when approved. Verification runs final tests and lint checks before marking the task as done.

Installation and Quick Start

# Install via uv, pip or Docker
uv tool install claude-task-master

# Authenticate with Claude Code
claude login

# Run a task in your project
cd my-project
claudetm start "Add user authentication with tests"

The CLI requires Python 3.10 or higher, an authenticated Claude CLI and GitHub CLI.

Profiles for Parallel Instances

Claude Task Master supports isolated profiles. An oauth profile stores a separate Claude Code configuration, allowing multiple subscriptions to run without conflict. An api-key profile lets you point the tool at any Anthropic compatible endpoint by setting ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL. Profiles are created under ~/.claudetm/profiles/<name>/ and selected with the --profile flag.

Extending with the REST API

The tool exposes a REST API and MCP server for external systems to dispatch tasks and monitor progress. A simple example using curl to start a task:

curl -X POST https://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -d '{"goal":"Implement pagination for API endpoint"}'

The API returns a task identifier that can be used to query status or send dynamic updates via the mailbox system. Webhooks can be configured to receive events such as PR creation, CI failure or merge completion.

Real-World Example

A team running multiple Claude subscriptions used Claude Task Master to automate their nightly release pipeline. Each profile handled a different microservice, all coordinated through the mailbox. When a CI failure occurred, the tool automatically fixed the issue, pushed a new commit and re-triggered checks without human intervention. Once all services passed, the tool merged the pull requests and reported success via a webhook to the team’s Slack channel.

Conclusion

Claude Task Master provides a hands-off, pull request based automation layer for Claude Code users. Its state persistence, profile isolation and API integration make it suitable for both individual developers and large engineering teams. The open source MIT license and simple installation process lower the barrier to adoption. Give it a goal and let the tool handle the rest.

DEV Community