clickup-agent-cli 0.2.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "clickup-agent-cli",
+  "version": "0.2.0",
+  "description": "CLI covering the entire ClickUp API v2 surface",
+  "type": "module",
+  "bin": {
+    "clickup": "./dist/bin/clickup.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx bin/clickup.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "clickup",
+    "cli",
+    "agent",
+    "project-management",
+    "tasks",
+    "mcp"
+  ],
+  "author": "Henry Reith",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.0.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.0",
+    "conf": "^13.0.0",
+    "ora": "^8.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/clickup/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: clickup
+description: Manages ClickUp projects, tasks, spaces, lists, time tracking, goals, and more via CLI. Use when the user needs to create tasks, check project status, manage sprints, track time, find work items, or interact with ClickUp data in any way.
+user-invocable: false
+---
+
+# ClickUp CLI
+
+You have access to `clickup`, a command-line tool for the full ClickUp API v2. It outputs structured JSON by default when used programmatically.
+
+## When to Use This
+
+Use the ClickUp CLI when you need to:
+- Create, update, search, or manage tasks
+- Navigate workspaces, spaces, folders, and lists
+- Track time, manage goals, or work with views
+- Manage users, groups, guests, and webhooks
+- Run project management workflows (sprint planning, reviews, triage)
+
+## Discovery
+
+**Do not guess command syntax.** Discover the correct flags using:
+
+```bash
+clickup schema <resource>              # List actions (list, get, create, ...)
+clickup schema <resource>.<action>     # Show required/optional fields
+clickup <resource> <action> --help     # Full help text
+```
+
+## Sub-Skills (load when needed)
+
+| Skill | What it covers |
+|-------|---------------|
+| `clickup-tasks` | Tasks, subtasks, checklists, dependencies, attachments |
+| `clickup-spaces` | Workspaces, spaces, folders, lists (hierarchy navigation) |
+| `clickup-comments` | Comments, threaded replies, comment assignment |
+| `clickup-time` | Time entries, running timers, time tags, reports |
+| `clickup-goals` | Goals, key results, OKR tracking |
+| `clickup-views` | Views (board, list, Gantt, etc.), view tasks |
+| `clickup-users` | Users, groups, guests, roles, members, workspace member search |
+| `clickup-chat` | Chat channels, sending messages and notifications |
+| `clickup-webhooks` | Webhook registration and management |
+| `clickup-fields` | Custom fields, tags, custom task types |
+
+## Recipe Skills (multi-step workflows)
+
+Recipes accept natural language arguments. Scope them to any team, department, person, or project.
+
+| Skill | Workflow |
+|-------|----------|
+| `clickup-weekly-review` | Weekly progress report for any team or scope |
+| `clickup-team-report` | Department/team status rundown (marketing, engineering, ops, etc.) |
+| `clickup-custom-report` | Any ad-hoc query or filtered report |
+| `clickup-sprint-planning` | Plan a sprint from backlog |
+| `clickup-task-triage` | Triage and prioritize incoming tasks |
+| `clickup-standup` | Daily standup summary for a person or team |
+| `clickup-sprint-closeout` | Close a sprint, carry over incomplete work |
+| `clickup-time-audit` | Audit time tracking and utilization |
+| `clickup-project-setup` | Scaffold a new project structure |
+| `clickup-capacity-check` | Check team workload and availability |
+| `clickup-blocker-report` | Find blocked tasks and dependency chains |
+| `clickup-goal-progress` | Report on goal/OKR completion |
+
+## Quick Patterns
+
+```bash
+# List tasks in a list
+clickup task list --list-id <id>
+
+# Create a task and capture its ID
+TASK_ID=$(clickup task create --list-id <id> --name "Task name" --format id)
+
+# Search across workspace
+clickup task search --workspace-id <id> --query "search text"
+
+# Pipe IDs for batch operations
+clickup task list --list-id <id> --format quiet | xargs -I{} clickup task get {}
+```
+
+## Global Flags
+
+All commands support: `--format json|table|csv|tsv|quiet|id|md`, `--dry-run`, `--debug`, `--no-color`
+
+Use `--format md` to render output as a markdown table -- ideal for displaying results in chat messages or documents.
+
+## Auth
+
+Requires a ClickUp API token.
+
+```bash
+# Set up authentication
+clickup auth login --token pk_XXXXXXXX_YYYYYYYY
+
+# Or use an environment variable
+export CLICKUP_TOKEN=pk_XXXXXXXX_YYYYYYYY
+
+# Store default workspace
+clickup config set workspace_id <id>
+
+# Check current auth status
+clickup auth status
+```
+
+## Creating Custom Skills
+
+Users can create their own skills alongside the built-in ones. Add a SKILL.md to `.claude/skills/<name>/` in any project:
+
+```yaml
+---
+name: marketing-weekly
+description: Weekly marketing department review
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+allowed-tools: Bash(clickup *)
+---
+
+Generate a marketing department weekly review:
+1. Get all tasks in the Marketing space (space ID: YOUR_SPACE_ID)
+2. Focus on campaign tasks, content pipeline, and ad performance items
+3. Highlight completed deliverables and upcoming deadlines
+4. Flag any blocked creative reviews
+```
+
+This creates `/marketing-weekly` as a custom skill that works alongside the built-in `/clickup:*` skills.

package/skills/clickup-blocker-report/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: clickup-blocker-report
+description: Finds blocked tasks, dependency chains, and stale items that need attention. Use when the user asks about blockers, stuck tasks, stalled work, dependency issues, or wants to find what is holding up progress.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[workspace-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Blocker Report
+
+Identify blocked tasks, broken dependency chains, and items that have been stalled.
+
+## Prerequisites
+
+- Workspace ID
+
+## Workflow
+
+### Step 1: Find explicitly blocked tasks
+
+```bash
+clickup task search --workspace-id <id> \
+  --status "blocked" --status "waiting" --status "on hold" \
+  --format json
+```
+
+### Step 2: Find stale in-progress tasks
+
+Tasks that have been "in progress" for too long without updates:
+
+```bash
+# In-progress tasks not updated in the last 7 days
+clickup task search --workspace-id <id> \
+  --status "in progress" \
+  --date-updated-lt <seven-days-ago-ms> \
+  --format json
+```
+
+### Step 3: Check dependencies on blocked tasks
+
+For each blocked task, get its full details to see dependency info:
+
+```bash
+clickup task get <blocked-task-id> --format json
+```
+
+The response includes `dependencies` and `linked_tasks` arrays showing what is blocking the task.
+
+### Step 4: Find overdue unassigned tasks
+
+```bash
+clickup task search --workspace-id <id> \
+  --due-date-lt <now-ms> \
+  --include-closed false \
+  --format json
+```
+
+Filter results for tasks with empty assignee arrays - these are orphaned and overdue.
+
+### Step 5: Check time-in-status for stuck tasks
+
+```bash
+# How long have blocked tasks been in their current status?
+clickup task bulk-time-in-status --task-id <id1> --task-id <id2> --format json
+```
+
+### Step 6: Compile the report
+
+- **Blocked tasks**: What, who, and what is blocking them
+- **Stale tasks**: In progress but not updated recently
+- **Overdue + unassigned**: Nobody owns these
+- **Dependency chains**: If A blocks B blocks C, surface the chain
+
+### Step 7: Take action
+
+```bash
+# Reassign a stale task
+clickup task update <task-id> --assignee-add <id>
+
+# Add a comment to escalate
+clickup comment create --task-id <task-id> --text "This has been blocked for 5 days. Needs attention."
+
+# Update status if blocker is resolved
+clickup task update <task-id> --status "in progress"
+```
+
+## Tips
+
+- Run blocker reports at least twice per sprint
+- Tasks in "blocked" status for more than 3 days should be escalated
+- Cross-reference with the capacity-check recipe to see if blockers are due to overload

package/skills/clickup-capacity-check/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: clickup-capacity-check
+description: Checks team workload and capacity by analyzing who is overloaded, who has bandwidth, and suggesting rebalancing. Use when the user asks about team capacity, workload, who is overloaded, or wants to balance task assignments.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[workspace-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Capacity Check
+
+Assess team workload by analyzing task assignments, time estimates, and time logged.
+
+## Prerequisites
+
+- Workspace ID
+- Team member user IDs
+
+## Workflow
+
+### Step 1: Get each team member's active tasks
+
+```bash
+# For each team member, get their in-progress and to-do tasks
+clickup task search --workspace-id <id> --assignee <user-id> \
+  --status "to do" --status "in progress" --status "in review" \
+  --format json
+```
+
+### Step 2: Sum time estimates per person
+
+From the task data, calculate:
+- Total estimated hours per person (sum `time_estimate` fields)
+- Number of active tasks per person
+- Number of high-priority (P1/P2) tasks per person
+
+### Step 3: Check time logged this period
+
+```bash
+clickup time list --workspace-id <id> \
+  --start <period-start-ms> --end <period-end-ms> \
+  --assignee <user-id> \
+  --format json
+```
+
+### Step 4: Check for overdue tasks per person
+
+```bash
+clickup task search --workspace-id <id> --assignee <user-id> \
+  --due-date-lt <now-ms> --include-closed false \
+  --format json
+```
+
+### Step 5: Compile capacity report
+
+For each team member:
+- **Active tasks**: Count and total estimated hours
+- **Time logged this week**: Hours
+- **Overdue tasks**: Count
+- **Capacity status**: Under / At / Over capacity
+
+### Step 6: Rebalance (if needed)
+
+```bash
+# Move a task from overloaded person to someone with bandwidth
+clickup task update <task-id> --assignee-remove <overloaded-id> --assignee-add <available-id>
+```
+
+## Tips
+
+- Time estimates are in milliseconds. Divide by 3600000 for hours.
+- If time estimates are not set on tasks, use task count as a rough proxy
+- Run capacity checks at sprint planning and mid-sprint
+- Use `--format quiet` to get just task IDs for batch reassignment

package/skills/clickup-chat/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: clickup-chat
+description: Lists ClickUp chat channels and sends messages. Use when the user wants to post a notification, send a standup summary, notify a channel, or check what chat channels exist in the workspace.
+allowed-tools: Bash(clickup chat *), Bash(clickup schema chat*)
+---
+
+# ClickUp Chat
+
+List channels and send messages to chat channels in the workspace.
+
+## Channel Commands
+
+```bash
+# List all chat channels
+clickup chat channels --workspace-id <id>
+
+# List channels as JSON (for scripting)
+clickup chat channels --workspace-id <id> --format json
+
+# Get channel IDs only
+clickup chat channels --workspace-id <id> --format quiet
+```
+
+## Send Message
+
+```bash
+# Send a message to a channel
+clickup chat send --channel-id <id> --message "Message text"
+
+# With explicit workspace ID
+clickup chat send --workspace-id <id> --channel-id <id> --message "Message text"
+```
+
+## Common Patterns
+
+```bash
+# Find a channel by name then message it
+CHANNEL_ID=$(clickup chat channels --format json | jq -r '.[] | select(.name=="general") | .id')
+clickup chat send --channel-id "$CHANNEL_ID" --message "Deploy complete"
+
+# Post a standup summary to a channel
+clickup chat send --channel-id <id> --message "$(clickup task list --list-id <id> --format md)"
+
+# Notify channel after creating a task
+TASK_ID=$(clickup task create --list-id <id> --name "Incident: API down" --priority 1 --format id)
+clickup chat send --channel-id <id> --message "Incident task created: $TASK_ID"
+
+# Output channels as markdown table for display
+clickup chat channels --format md
+```
+
+## Discovery
+
+```bash
+clickup schema chat            # List chat actions
+clickup schema chat.channels   # Show channels flags
+clickup schema chat.send       # Show send fields
+```

package/skills/clickup-comments/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: clickup-comments
+description: Creates, lists, and manages comments on ClickUp tasks, lists, and views. Supports threading and replies. Use when the user wants to add comments, read discussion threads, reply to comments, or assign action items via comments.
+allowed-tools: Bash(clickup comment *), Bash(clickup schema comment*)
+---
+
+# ClickUp Comments
+
+Comments can be attached to tasks, lists, or views. Supports threaded replies and comment assignment.
+
+## List Comments
+
+```bash
+clickup comment list --task-id <id> [--start <ts>] [--start-id <id>]
+clickup comment list --list-id <id> [--start <ts>] [--start-id <id>]
+clickup comment list --view-id <id> [--start <ts>] [--start-id <id>]
+```
+
+Provide exactly one of `--task-id`, `--list-id`, or `--view-id`.
+
+## Create a Comment
+
+```bash
+clickup comment create --task-id <id> --text <text> [--assignee <id>] [--notify-all]
+clickup comment create --list-id <id> --text <text> [--assignee <id>] [--notify-all]
+clickup comment create --view-id <id> --text <text> [--assignee <id>] [--notify-all]
+```
+
+## Update / Delete
+
+```bash
+clickup comment update <comment-id> --text <text> [--assignee <id>] [--resolved <bool>]
+clickup comment delete <comment-id> --confirm
+```
+
+## Threading
+
+```bash
+clickup comment list-threaded <comment-id>    # List replies to a comment
+clickup comment reply <comment-id> --text <text> [--assignee <id>] [--notify-all]
+```
+
+## Common Patterns
+
+```bash
+# Add a status update comment on a task
+clickup comment create --task-id abc9zt --text "Deployed to staging. Ready for QA."
+
+# Assign a comment as an action item
+clickup comment create --task-id abc9zt --text "Please review the API changes" --assignee 112233
+
+# Resolve a comment thread
+clickup comment update cmt_123 --resolved true
+
+# Reply in a thread
+clickup comment reply cmt_123 --text "Done - merged to main"
+
+# List comments as markdown table
+clickup comment list --task-id <id> --format md
+```
+
+## Discovery
+
+```bash
+clickup schema comments.create    # Show create fields
+clickup schema comments.list      # Show list options
+```

package/skills/clickup-custom-report/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: clickup-custom-report
+description: Generates a custom ClickUp report based on any criteria the user describes. Handles ad-hoc queries like "show me all high-priority tasks assigned to John", "what's overdue in the backend", or "tasks created this month with no assignee". Use when the user asks for a specific data pull, custom query, filtered view, or any report that does not match a predefined recipe.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[describe what you want to see]"
+allowed-tools: Bash(clickup *)
+---
+
+# Custom Report
+
+Generate any report the user asks for by composing CLI commands to match their criteria.
+
+## Understanding the Request
+
+`$ARGUMENTS` is a natural language description of what the user wants. Parse it to determine:
+
+1. **What data**: tasks, time entries, goals, comments, etc.
+2. **Filters**: status, assignee, priority, dates, space, list, tags, custom fields
+3. **Grouping**: by person, by status, by space, by priority, by date
+4. **Output style**: summary, detailed list, counts, comparison
+
+## Available Filters
+
+Use these CLI flags to build the right query:
+
+### Task filters
+```bash
+clickup task search --workspace-id <id> \
+  --status "in progress"            # Filter by status
+  --assignee <user-id>              # Filter by assignee
+  --priority 1                      # Filter by priority (1=urgent, 2=high, 3=normal, 4=low)
+  --due-date-gt <timestamp-ms>      # Due after date
+  --due-date-lt <timestamp-ms>      # Due before date
+  --date-created-gt <timestamp-ms>  # Created after date
+  --date-updated-gt <timestamp-ms>  # Updated after date
+  --tag "bug"                       # Filter by tag
+  --space-id <id>                   # Scope to space
+  --list-id <id>                    # Scope to list
+  --include-closed true             # Include completed tasks
+  --format json
+```
+
+### Time entry filters
+```bash
+clickup time list --workspace-id <id> \
+  --start <timestamp-ms>            # Period start
+  --end <timestamp-ms>              # Period end
+  --assignee <user-id>              # Filter by person
+  --format json
+```
+
+### Other data
+```bash
+clickup goal list --workspace-id <id> --format json
+clickup comment list --task-id <id> --format json
+clickup view tasks --view-id <id> --format json
+```
+
+## Workflow
+
+### Step 1: Parse the request
+
+Break down the natural language request into concrete filters. Examples:
+
+| User says | Filters to apply |
+|-----------|-----------------|
+| "High priority tasks with no assignee" | `--priority 1 --priority 2`, then filter results for empty assignee |
+| "What did the team complete last month" | `--status complete --date-updated-gt <month-start> --date-updated-lt <month-end>` |
+| "Tasks in the design space due this week" | `--space-id <design-space> --due-date-lt <end-of-week>` |
+| "Show me everything tagged 'urgent'" | `--tag urgent` |
+| "Overdue tasks by priority" | `--due-date-lt <now> --include-closed false`, group by priority |
+
+### Step 2: Resolve names to IDs
+
+If the user used names instead of IDs, look them up:
+
+```bash
+# Find a space by name
+clickup space list --format json
+
+# Find a user by name
+clickup member list --workspace-id <id> --format json
+
+# Find a list by name within a space
+clickup list list --space-id <id> --format json
+```
+
+### Step 3: Run the query
+
+Execute the search with all applicable filters. Use `--format json` for structured data.
+
+### Step 4: Process and format results
+
+- Group results as the user requested (by person, status, priority, etc.)
+- Calculate aggregates (counts, totals, averages) if asked
+- Sort by the most relevant field (due date, priority, creation date)
+
+### Step 5: Present the report
+
+Format the output clearly with:
+- A summary line (e.g., "Found 23 high-priority tasks across 3 spaces")
+- Grouped/sorted data with relevant details
+- Actionable insights if patterns emerge (e.g., "12 of 23 are unassigned")
+
+## Example Requests
+
+These all work with this recipe:
+
+- "Show me all tasks created this week"
+- "How many tasks does each team member have?"
+- "What's overdue in engineering?"
+- "Tasks tagged 'client-facing' that are still in progress"
+- "Compare task completion rates between marketing and sales this quarter"
+- "Find tasks with time estimates but no time logged"
+- "All tasks due in the next 3 days with priority 1 or 2"
+- "What tasks were closed without any comments?"
+
+## Tips
+
+- Combine multiple searches if a single query can't capture everything
+- Use `clickup schema tasks.search` to discover available filter flags
+- For complex comparisons, run separate searches and merge the results
+- If the user asks for something the CLI can't filter directly, fetch a broader set and filter in post-processing

package/skills/clickup-fields/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: clickup-fields
+description: Manages ClickUp custom fields, tags, and custom task types. Use when the user asks about custom fields, wants to set field values on tasks, manage tags, or work with custom task types.
+allowed-tools: Bash(clickup custom-field *), Bash(clickup tag *), Bash(clickup custom-task-type *), Bash(clickup schema field*), Bash(clickup schema tag*)
+---
+
+# ClickUp Custom Fields, Tags, and Task Types
+
+## Custom Field Commands
+
+Custom fields are defined at the list level and set on individual tasks.
+
+```bash
+clickup field list --list-id <id>                              # List field definitions
+clickup field set --task-id <id> --field-id <fid> --value <v>  # Set a field value
+clickup field remove --task-id <id> --field-id <fid>           # Clear a field value
+```
+
+### Value formats by field type
+
+| Type | Format | Example |
+|------|--------|---------|
+| text | Plain string | `"Approved"` |
+| number | Numeric string | `"42"` |
+| currency | Numeric string | `"99.99"` |
+| date | Unix timestamp (ms) | `"1735689600000"` |
+| checkbox | `true` or `false` | `"true"` |
+| dropdown | Option ID | `"1"` |
+| label | JSON array of option IDs | `"[1,2]"` |
+| user | User ID | `"112233"` |
+| url | URL string | `"https://example.com"` |
+| rating | Integer | `"4"` |
+
+## Tag Commands
+
+Tags are defined at the space level and applied to tasks.
+
+```bash
+clickup tag list --space-id <id>
+clickup tag create --space-id <id> --name <name> [--fg-color <hex>] [--bg-color <hex>]
+clickup tag update --space-id <id> --name <name> [--new-name <name>] [--fg-color <hex>] [--bg-color <hex>]
+clickup tag delete --space-id <id> --name <name> --confirm
+clickup tag add --task-id <id> --name <name>
+clickup tag remove --task-id <id> --name <name>
+```
+
+## Custom Task Type Commands
+
+Custom task types (Bug, Feature, Milestone, etc.) are defined at the workspace level (Enterprise plan).
+
+```bash
+clickup task-type list --workspace-id <id>
+```
+
+## Common Patterns
+
+```bash
+# Set a custom field on a task
+clickup field set --task-id abc9zt --field-id cf_001 --value "Approved"
+
+# Create and apply a tag
+clickup tag create --space-id 55544433 --name "urgent" --bg-color "#FF0000"
+clickup tag add --task-id abc9zt --name "urgent"
+
+# List all fields available in a list (to find field IDs)
+clickup field list --list-id 998877 --format json
+
+# Render field list as markdown table
+clickup field list --list-id 998877 --format md
+```
+
+## Discovery
+
+```bash
+clickup schema fields.set      # Show field set options
+clickup schema tags.create     # Show tag create fields
+```