Introduction
Claude Task Master is a command-line tool that automates the full pull request lifecycle for projects that use Claude Code. By giving the CLI a high-level goal, it plans the work, writes code, runs tests, opens pull requests, addresses CI failures, and merges when the changes are approved. The system is built on the Claude Agent SDK and is open source under the MIT license.
How Claude Task Master Works
The workflow consists of four main phases: planning, execution, pull request handling, and verification. In the planning phase the tool scans the repository, creates a list of tasks, and defines success criteria. During execution it makes code changes, runs the test suite, and commits each change as a separate pull request. The pull request handling phase monitors CI, fixes any failures, and responds to review comments. Finally, verification runs linting and additional tests to confirm that all criteria are met before the task is marked as complete.
Setting Up
# Install via pip, uv, or Docker
uv tool install claude-task-master
# Authenticate with Claude Code
claude login
# Start a task in your project directory
cd my-project
claudetm start "Add user authentication with tests"
The CLI requires Python 3.10 or newer, a logged-in Claude CLI, and the GitHub CLI for push operations. After authentication the tool creates a pull request for each task and tracks its progress.
Using Profiles for Parallel Subscriptions
Profiles allow multiple Claude subscriptions to run side by side without interfering with each other. An oauth profile stores a separate Claude Code configuration directory, while an api-key profile injects a direct API key and base URL. This isolation is useful for teams that need to test different Claude models or run separate pipelines in the same environment.
# Create a new profile named "beta"
claudetm profile create beta --api-key $ANTHROPIC_API_KEY --base-url $ANTHROPIC_BASE_URL
# Run a task using the new profile
claudetm --profile beta start "Refactor payment module"
Each profile maintains its own state, so interruptions do not affect other running instances.
Extending with REST API, MCP Server, and Webhooks
Claude Task Master exposes a REST API that mirrors the CLI commands. The MCP server provides a message-passing layer for instances to exchange updates, and HMAC-signed webhooks can notify external systems about task progress. These integrations enable developers to embed the tool in CI pipelines, dashboards, or custom bots.
POST /tasks
Content-Type: application/json
{
"goal": "Implement rate limiting",
"profile": "beta"
}
The response includes a task identifier that can be used to query status or cancel the job.
Real-World Example
A team working on a Rails application defined the goal “Add OAuth login with tests”. Claude Task Master generated a plan that split the work into three pull requests: one for the authentication controller, one for the test suite, and one for documentation. CI failures in the first PR were automatically fixed, and a review comment about a missing edge case was addressed by the tool. After the reviewer approved, the CLI auto-merged the PRs and ran a final verification step. The team saved several hours of manual coordination and could focus on higher-level design decisions.
Conclusion
Claude Task Master offers a hands-off approach to code changes that integrates tightly with existing Claude Code workflows. By persisting state, handling CI, and supporting multiple profiles, it provides a reliable foundation for autonomous development pipelines. The open-source nature and extensible API make it a strong candidate for teams looking to automate repetitive PR tasks while maintaining control over the codebase. #ClaudeCode #AIAgents #DevTools #OpenSource
Top comments (0)