ClickUp Sync - Claude Code Integration

A Node.js/TypeScript command-line tool that enables seamless integration between Claude Code and ClickUp, allowing you to create and manage Stories, Tasks, and Subtasks through simple comment syntax.

Features

• 🚀 Interactive Setup: Easy initialization with ClickUp API integration
• 📝 Comment-Based Commands: Create tasks using simple comment syntax
• 🔄 One-Way Sync: Automatically sync your project structure to ClickUp
• 🎯 Hierarchical Tasks: Support for Stories → Tasks → Subtasks
• 🛡️ Secure: API tokens are encrypted and stored safely
• 🔍 Validation: Built-in validation for commands and project structure
• 📊 Progress Tracking: Status updates and comprehensive reporting

Installation

Global Installation (Recommended)

npm install -g clickup-sync

Local Installation

npm install clickup-sync
npx clickup-sync --help

Quick Start

1. Initialize Your Project

clickup-sync init

This will guide you through:

• Entering your ClickUp API token
• Selecting or creating a workspace
• Setting up your project configuration

2. Add Claude Code Comments

Add comments to your project files using the syntax:

// #story:User Authentication System:Implement complete user authentication with login, logout, and password reset functionality

// #task:story-user-authentication-system:Create Login Component:Build a React component for user login with form validation and error handling

// #subtask:task-create-login-component:Add Form Validation:Implement client-side form validation for login form

// #status:task-create-login-component:in progress

3. Process Comments

# Dry run to see what would be created
clickup-sync process --dry-run

# Actually create the tasks in ClickUp
clickup-sync process

Comment Syntax

Story

Creates a top-level story/epic in ClickUp:

#story:title:description

Task

Creates a task under a story:

#task:story_id:title:description

Subtask

Creates a subtask under a task:

#subtask:task_id:title:description

Status Update

Updates the status of any item:

#status:item_id:new_status

Valid statuses: to do, in progress, complete, closed

Commands

clickup-sync init

Interactive setup wizard to initialize your project with ClickUp integration.

clickup-sync process [options]

Process Claude Code comments in your project and sync to ClickUp.

Options:

• --dry-run - Show what would be done without executing
• --verbose - Show detailed output
• --batch-size <size> - Number of commands to process in parallel (default: 5)
• --include <files...> - Only process specific files
• --exclude <files...> - Exclude specific files from processing

clickup-sync status

Show current configuration and connection status.

clickup-sync validate

Validate project configuration and command syntax.

clickup-sync config [options]

Show current configuration.

Options:

• --show-token - Show API token (use with caution)

clickup-sync help

Show detailed help information.

Configuration

The tool creates a .clickup-config.json file in your project root:

{
  "clickup": {
    "apiToken": "encrypted_token",
    "workspaceId": "workspace_id",
    "workspaceName": "Workspace Name",
    "spaceId": "space_id",
    "listId": "list_id"
  },
  "claude": {
    "instructions": [
      "# Create Story: #story:title:description",
      "# Create Task: #task:story_id:title:description",
      "# Create Subtask: #subtask:task_id:title:description",
      "# Update Status: #status:item_id:new_status"
    ]
  },
  "project": {
    "name": "My Project",
    "type": "web",
    "rootPath": "/path/to/project"
  }
}

Supported File Types

The tool scans these file types for comments:

• .ts - TypeScript
• .js - JavaScript
• .py - Python
• .java - Java
• .cs - C#
• .md - Markdown
• .txt - Text files

ID Generation

Task IDs are automatically generated based on the title:

• #story:User Authentication System:... → story-user-authentication-system
• #task:story-user-authentication-system:Login Component:... → task-login-component

Examples

Complete Workflow Example

// example.js

// #story:E-commerce Cart System:Implement shopping cart functionality with add, remove, and checkout features

// #task:story-e-commerce-cart-system:Cart Component:Create React component for displaying cart items
// #task:story-e-commerce-cart-system:Add to Cart Function:Implement function to add items to cart
// #task:story-e-commerce-cart-system:Checkout Process:Create checkout workflow with payment integration

// #subtask:task-cart-component:Cart Item Display:Show individual cart items with quantity and price
// #subtask:task-cart-component:Remove Item Function:Add ability to remove items from cart
// #subtask:task-cart-component:Update Quantity:Allow users to update item quantities

// #subtask:task-checkout-process:Payment Integration:Integrate with payment gateway
// #subtask:task-checkout-process:Order Summary:Display order summary before payment

// #status:task-cart-component:in progress
// #status:subtask-cart-item-display:complete

Multi-Language Support

# Python file
# #story:Data Processing Pipeline:Build ETL pipeline for customer data

# TypeScript file
// #task:story-data-processing-pipeline:Data Validation:Implement data validation functions

/* Java file */
// #subtask:task-data-validation:Email Validation:Validate email format and domain

Security

• API Token Encryption: Tokens are encrypted using AES-256 before storage
• File Permissions: Configuration files are set to owner-only access (600)
• Input Validation: All inputs are validated and sanitized
• No Logging: Sensitive information is never logged

Troubleshooting

Common Issues

1. "Configuration not found"

   clickup-sync init

2. "Authentication failed"

   • Check your API token at https://app.clickup.com/settings/apps
   • Ensure token has proper permissions

3. "Referenced story/task not found"

   • Ensure parent items are defined before child items
   • Check that IDs match exactly (case-sensitive)

4. Rate limiting

   • The tool automatically handles rate limits
   • Reduce batch size with --batch-size option

Debug Mode

For verbose output:

clickup-sync process --verbose

For dry run testing:

clickup-sync process --dry-run

API Token Setup

1. Go to https://app.clickup.com/settings/apps
2. Click "Generate" to create a new API token
3. Copy the token (starts with "pk_")
4. Run clickup-sync init and enter the token when prompted

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: Report bugs and request features via GitHub issues
• Documentation: Complete documentation available in the repository
• Community: Join discussions in GitHub Discussions

Made with ❤️ for the Claude Code community