TaskWing

AI-powered CLI task manager built for developers

TaskWing integrates directly with Claude Code, Cursor, and other AI tools via the Model Context Protocol. Manage tasks from your terminal or let AI handle it for you.

Why TaskWing?

• 🤖 AI-Native: Full MCP integration for Claude Code, Cursor, and other AI tools
• ⚡ Zero Config: Works immediately, stores data locally in your project
• 🔗 Smart Dependencies: Automatic dependency tracking and circular reference prevention
• 📚 Learning System: Captures patterns from completed projects for future AI assistance
• 🚀 Developer-First: Built for developers who value focus and efficiency

By @josephgoksu

Quick Start

Installation

One-liner install (recommended)

curl -sSfL https://raw.githubusercontent.com/josephgoksu/TaskWing/main/install.sh | sh

Note: After installation, you may need to add ~/.local/bin to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Alternative: Go install

If you have Go installed:

go install github.com/josephgoksu/TaskWing@latest

Verify installation

taskwing version

First Steps

New to TaskWing? Start with the interactive guide:

taskwing quickstart

Or jump straight in:

# Initialize in your project
taskwing init

# Interactive menu (great for beginners)
taskwing interactive

# Or use direct commands
taskwing add "Fix authentication bug" --priority urgent
taskwing ls                    # List all tasks
taskwing start <task-id>       # Begin working
taskwing done <task-id>        # Mark complete

AI Integration

Quick setup for Claude Code:

1. Start MCP server:

   taskwing mcp

2. Add to Claude Code config:

   {
     "mcpServers": {
       "taskwing": {
         "command": "taskwing",
         "args": ["mcp"]
       }
     }
   }

3. Ask Claude: "What tasks do I have?" or "Create a task to refactor the auth module"

Example AI interactions:

• "Break down this feature into tasks"
• "What should I work on next?"
• "Create tasks from this GitHub issue"
• "Show me my current sprint status"

See MCP Setup Guide for detailed configuration and AI Examples for advanced patterns.

Core Features

🎯 Task Management

• Rich metadata: Priority, status, dependencies, acceptance criteria
• Flexible workflow: todo → doing → review → done
• Smart search: Find tasks by title, description, or partial ID
• Board view: Kanban-style project visualization

🤖 AI Integration

• MCP Protocol: Direct integration with Claude Code, Cursor, and AI tools
• Context-aware: AI knows your current task and project state
• Intelligent suggestions: Get next task recommendations
• Planning assistance: Break down features into actionable tasks

🔗 Smart Dependencies

• Relationship tracking: Parent/child tasks and dependencies
• Circular prevention: Automatic detection and prevention
• Dependency health: Analyze and fix broken relationships

⚡ Developer Experience

• Zero config: Works immediately in any project
• Local-first: All data stored in your project directory
• Fast commands: Optimized for daily use with aliases
• Interactive mode: Menu-driven interface for exploration

Example workflows:

# Sprint planning
taskwing add "Implement user auth" --priority high
taskwing add "Add login form" --parent <auth-task-id>
taskwing add "Add logout functionality" --parent <auth-task-id>
taskwing board-snapshot                 # See the plan

# Daily workflow
taskwing current                        # See active task
taskwing next                          # Get AI suggestions
taskwing start <task-id>               # Focus on task
taskwing done <task-id>                # Mark complete

# Project analysis
taskwing search "auth"                 # Find auth-related tasks
taskwing analytics                     # View completion metrics
taskwing workflow-status               # See project phase

For complete command reference, see User Guide.

Real-World Examples

Daily Development Workflow

# Morning standup
taskwing current                    # What am I working on?
taskwing board-snapshot            # Sprint overview

# Start new work
taskwing add "Implement OAuth2 flow" --priority high
taskwing start <task-id>           # Focus mode

# AI assistance
# Ask Claude: "Break down this OAuth task into smaller steps"
# Claude creates subtasks automatically via MCP

# End of day
taskwing done <task-id>            # Mark complete
taskwing next                      # What's next?

Project Planning with AI

# Upload PRD to Claude and ask:
# "Create a task breakdown for this feature spec"

# Claude uses MCP to:
taskwing batch-create-tasks        # Create multiple tasks
taskwing board-reconcile          # Organize dependencies
taskwing workflow-status          # Show project phases

Documentation

Document	Purpose
DOCS.md	User guide - Installation, commands, workflows
MCP.md	AI integration - Setup and tool reference
EXAMPLES.md	AI interaction examples - Common usage patterns
CLAUDE.md	Developer guide - Architecture and contributing

For Developers

Quick Development Setup

# Clone and setup
git clone https://github.com/josephgoksu/TaskWing.git
cd TaskWing
make dev-setup                 # Install dev tools

# Development workflow
make build                     # Build binary
make test-quick               # Fast tests
make lint                     # Format and lint

# Testing
make test-all                 # Comprehensive test suite
make test-mcp                 # Test MCP integration
make coverage                 # Generate coverage report

Architecture

• Local-first: All data in project .taskwing/ directory
• Go 1.24+: Built with Cobra CLI framework
• MCP Integration: Full Model Context Protocol support
• File-based storage: JSON/YAML/TOML with file locking
• 33+ MCP tools: Comprehensive AI integration

Contributing

We welcome contributions! Key areas:

• 🐛 Bug fixes: See issues
• ✨ New MCP tools: Extend AI capabilities
• 📄 Documentation: Improve user experience
• 🧪 Testing: Increase coverage and reliability

See CLAUDE.md for detailed development guide.

License

MIT License - see LICENSE file.

---

Built for the terminal. Powered by AI. Made for developers. 🚀