Manage TickTick tasks and projects
---
name: ticktick
description: Manage TickTick tasks and projects
triggers:
- "/tasks"
- "/ticktick"
---
# TickTick Skill
Manage your TickTick tasks and projects directly from OpenClaw.
## Setup
Before using, authenticate once (OAuth2):
```bash
cd ~/.openclaw/workspace/skills/ticktick
bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
```
Follow the OAuth flow. Credentials are stored securely in `~/.clawdbot/credentials/ticktick-cli/`.
Check status: `bun run scripts/ticktick.ts auth --status`
## Commands
### List Projects
`/tasks projects` or `/ticktick projects`
Shows all your TickTick projects with IDs and names.
### List Tasks
`/tasks [options]` or `/ticktick tasks [options]`
List tasks with powerful filtering and sorting.
**Options:**
- `--project <name>` – Filter by project name or ID
- `--status <pending|completed>` – Filter by status
- `--due <filter>` – Filter by due: `today`, `overdue`, `none`, `unspecified`
- `--priority <level>` – Filter: `high`, `medium`, `low`, `none`
- `--sort <field>` – Sort by: `due`, `priority`, `title`, `created`
- `--limit <N>` – Maximum number of tasks to return
- `--offset <N>` – Skip first N tasks (for pagination)
- `--group` – Group output by project
- `--format <type>` – Output format: plain, rich, json, yaml
- `--verbose` – Show API requests for debugging
Examples:
```
/tasks --project Work --status pending --sort due
/tasks --due overdue --format rich
/tasks --priority high --limit 20
/tasks --project Hobbies --group
```
### Create Task
`/tasks add "<title>" [options]`
**Options:**
- `--list <project>` – Project (required if no default configured)
- `--due <when>` – Due date: "today", "tomorrow", "in 3 days", or ISO date
- `--priority <low|medium|high>` – Priority level
- `--content "<notes>"` – Task description/notes
- `--tags <tag1 tag2 ...>` – Tags to apply
Example:
```
/tasks add "Upgrade thermostat firmware" --list Hillcrest --due today --priority medium --content "Flash new firmware from repo"
```
### Edit Task
`/tasks edit <task-id> [options]`
Modify an existing task. **Task ID (24-character hex) is required.** Obtain IDs from `/tasks --json`.
**Options:**
- `--title "<new title>"` – Change title
- `--content "<new notes>"` – Replace content/notes
- `--due <date>` – Change due date
- `--priority <level>` – Change priority (none, low, medium, high)
- `--tags <tags...>` – Replace tags (space-separated)
- `--json` – Output updated task as JSON
- `--verbose` – Show diagnostic info
Examples:
```
/tasks edit 65a54fce2026ccc8b729349b --priority high
/tasks edit 65a54fce2026ccc8b729349b --due "in 3 days" --content "Urgent: complete this week"
```
### Complete Task
`/tasks complete <task-id> [--json]` or `/tasks done <task-id> [--json]`
Mark a task as complete. Both `complete` and `done` are aliases. **Task ID is required.**
### Abandon Task
`/tasks abandon <task-id> [--json]`
Mark a task as "won't do" (abandoned). **Task ID is required.**
### Task Details
`/tasks details <task-id> [options]`
Show full information about a single task. **Task ID is required.**
**Options:**
- `--json` – Output as JSON
- `--verbose` – Show full task object
Example:
```
/tasks details 65a54fce2026ccc8b729349b
```
### Batch Abandon
`/tasks batch-abandon <task-id-1> <task-id-2> ...`
Abandon multiple tasks in a single API call using their IDs.
### Config
`/tasks config get <key>` – Get a configuration value
`/tasks config set <key> <value>` – Set a configuration value
`/tasks config list` – Show all config
**Configuration keys:**
- `default.project` – Default project for `add` when `--list` omitted
- `default.due` – Default due date for new tasks ("none", "today", "tomorrow")
- `display.colors` – Enable/disable colored output (true/false)
- `display.timezone` – Timezone for date display (e.g., "America/New_York")
Example:
```
/tasks config set default.project Personal
/tasks config set default.due none
/tasks config list
```
Config is stored in `~/.config/ticktick-skill/config.json`.
---
## ADHD-Friendly Usage
### Morning Triage
Use the following to start your day:
```
/tasks --due overdue --format rich
/tasks --due today --format rich
/tasks --priority high --format rich
```
Or combine: `/tasks --format rich` (shows all pending, sorted by urgency)
### Quick Wins
Find small tasks to build momentum:
```
/tasks --priority low --limit 10 --sort title
```
Or use `/tasks details <id>` to assess quickly.
### Focus Mode
Show only what needs attention today:
```
/tasks --due today --sort due
```
### Reduce Overwhelm
- Use `--limit` to avoid seeing everything at once
- Group by project: `/tasks --group` to break into chunks
- Use colored output (`--format rich`) to prioritize by color
---
## Notes
- **Task IDs**: All commands that operate on a specific task require the 24-character hex ID for reliability. Get IDs from `/tasks --json`.
- **Project names**: Case-insensitive, partial match works (e.g., "Hill" matches "Hillcrest")
- **Due dates**: Flexible parsing supports "today", "tomorrow", "in 3 days", "next monday", and ISO dates (YYYY-MM-DD)
- **Rate limits**: TickTick API allows ~100 requests/minute. The CLI respects limits; if you hit them, wait a minute and retry.
- **JSON output**: Add `--json` to any command for machine-readable output (useful for scripts)
## Troubleshooting
**"Task not found"**
- Verify you're using the correct 24-char task ID
- Get fresh IDs with `/tasks --json`
**"Project not found"**
- List all projects with `/tasks projects`
- Project names are case-insensitive but must match exactly (partial match works)
**Authentication errors**
- Re-run: `bun run scripts/ticktick.ts auth`
- Check credentials exist: `ls ~/.clawdbot/credentials/ticktick-cli/`
**Rate limit exceeded**
- Wait ~60 seconds and retry
- Use `--verbose` to see request counts
**Dates not parsing**
- Use ISO format: `2026-03-25`
- Or natural language: `tomorrow`, `in 5 days`, `next friday`
## Implementation
Wrapper skill uses `bun run scripts/ticktick.ts` with `--json` flag and parses responses. Authentication stored in `~/.clawdbot/credentials/ticktick-cli/`.
### Command Reference Table
| Command | Purpose | Key Options |
|---------|---------|-------------|
| `projects` | List all projects | – |
| `tasks` | List tasks | `--project`, `--status`, `--due`, `--priority`, `--sort`, `--limit`, `--group` |
| `add` | Create task | `--list`, `--due`, `--priority`, `--content`, `--tags` |
| `edit` | Modify task | `--title`, `--content`, `--due`, `--priority`, `--tags` |
| `complete` / `done` | Mark complete | – |
| `abandon` | Mark won't-do | – |
| `details` | Show full task info | `--json`, `--verbose` |
| `batch-abandon` | Abandon multiple | `<task-id>...` |
| `config` | Manage config | `get`, `set`, `list` |
---
*Happy task managing!*
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs section with oauth setup and api rate limits, broke monolithic commands into numbered procedure steps with edge cases and decision points, documented empty results and timeout handling, clarified output formats and file locations, and added outcome signals for common use patterns.
manage ticktick tasks and projects directly from your cli or chat interface. use this skill to list, create, edit, complete, and organize tasks across projects. handles filtering by status, priority, due date, and project. best for daily task triage, batch operations, and keeping your task list in sync without leaving your workspace.
External connection: TickTick API
bun run scripts/ticktick.ts auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET~/.clawdbot/credentials/ticktick-cli/bun run scripts/ticktick.ts auth --statusConfiguration file
~/.config/ticktick-skill/config.jsondefault.project, default.due, display.colors, display.timezoneTask identifiers
65a54fce2026ccc8b729349b). required for edit, complete, abandon, details, batch-abandon commands. obtain from /tasks --json or /tasks --format json output.Due date formats
Command: /tasks projects or /ticktick projects
Input: None (uses OAuth credentials from setup).
Output: table or json listing all projects with their IDs and names.
Edge case: if no projects exist, returns empty list.
Command: /tasks [options] or /ticktick tasks [options]
Input options:
--project <name> , filter by project name or ID (case-insensitive partial match)--status <pending|completed> , filter by completion state--due <today|overdue|none|unspecified> , filter by due date category--priority <high|medium|low|none> , filter by priority level--sort <due|priority|title|created> , sort results--limit <N> , cap results to N tasks (default: all)--offset <N> , skip first N tasks for pagination--group , group output by project--format <plain|rich|json|yaml> , output format--verbose , log API requests for debuggingOutput: formatted list of tasks matching filters, or json/yaml for machine parsing.
Edge cases: empty result set (no tasks match filters), rate limit hit (wait 60s, retry), network timeout (retry with backoff).
Command: /tasks add "<title>" [options]
Input:
<title> (required): task name as quoted string--list <project> (required if no default.project configured): project name or ID--due <when> (optional): due date in natural language or ISO format--priority <low|medium|high> (optional): priority level--content "<notes>" (optional): task description--tags <tag1 tag2 ...> (optional): space-separated tagsOutput: created task object with ID, or confirmation message.
Edge case: project not found (returns error; verify with /tasks projects), invalid due date format (retried with iso parsing), no default project and --list omitted (returns error requiring project).
Command: /tasks edit <task-id> [options]
Input:
<task-id> (required): 24-character hex task ID--title "<new title>" (optional): replace title--content "<new notes>" (optional): replace content--due <date> (optional): change due date--priority <level> (optional): change priority (none, low, medium, high)--tags <tags...> (optional): replace tags (space-separated)--json (optional): output updated task as json--verbose (optional): log diagnostic infoOutput: updated task object or confirmation message.
Edge case: task not found (returns error; verify ID with /tasks --json), invalid task ID format (returns parse error), network timeout during update (retry, check task state with /tasks details <id>).
Command: /tasks complete <task-id> or /tasks done <task-id> or /ticktick complete <task-id> (aliases)
Input:
<task-id> (required): 24-character hex task ID--json (optional): output as jsonOutput: confirmation message or json representation of completed task.
Edge case: task not found (returns error), task already completed (api may accept idempotently or error; check with /tasks details).
Command: /tasks abandon <task-id> or /ticktick abandon <task-id>
Input:
<task-id> (required): 24-character hex task ID--json (optional): output as jsonOutput: confirmation or json of abandoned task.
Edge case: task not found (returns error), task already abandoned (check state with details).
Command: /tasks batch-abandon <task-id-1> <task-id-2> ... or /ticktick batch-abandon <task-id-1> ...
Input: space-separated list of task IDs (24-character hex strings).
Output: summary of abandoned tasks or json array.
Edge case: one or more IDs invalid or not found (operation may fail atomically or skip bad IDs; check output), rate limit hit (waits ~60s, retries).
Command: /tasks details <task-id> or /ticktick details <task-id>
Input:
<task-id> (required): 24-character hex task ID--json (optional): output as json--verbose (optional): show full task objectOutput: formatted or json task object with all fields (title, content, due date, priority, tags, status, created, updated, etc.).
Edge case: task not found (returns error), auth expired (re-run auth setup).
Command: /tasks config get <key> or /tasks config set <key> <value> or /tasks config list
Input:
get <key>: retrieve single config valueset <key> <value>: store config key-valuelist: show all config keys and valuesSupported keys:
default.project , default project for add when --list omitteddefault.due , default due date for new tasks ("none", "today", "tomorrow")display.colors , enable/disable colored output (true/false)display.timezone , timezone for date display (e.g., "America/New_York")Output: current value, confirmation, or full config dict.
Edge case: invalid key (returns error with supported keys listed), timezone invalid (falls back to UTC).
if oauth credentials not found or expired: re-run bun run scripts/ticktick.ts auth --client-id ... --client-secret ... and retry command.
if --list not provided in add command and no default.project configured: return error requiring --list flag or config set default.project <name>.
if --project filter is provided but no matching project exists: return empty result set (not an error; user may have misspelled name).
if task ID not found in any edit, complete, abandon, details, or batch-abandon command: return "task not found" error; user should verify ID with /tasks --json.
if rate limit (100 req/min) is hit: wait ~60 seconds before retrying. the cli logs backoff info; user can see with --verbose.
if network timeout occurs during api call: retry with exponential backoff (1s, 2s, 4s, then fail). return error after 3 failed attempts.
if due date parsing fails (invalid natural language or malformed iso): fall back to iso parsing, then error if both fail.
if --format json or --format yaml is requested: output raw machine-readable format for scripting; ignore --format rich or --format plain in same command.
if --group is set: group tasks by project name in output, ignoring sort order within groups.
Success looks like:
projects command: json array of {id, name} or formatted tabletasks command: json array of task objects or formatted list with columns (title, due, priority, project)add command: json object {id, title, project, due, priority, created} or string confirmationedit command: json object representing updated task or confirmation messagecomplete/done/abandon command: json object or string confirmation (e.g., "task marked complete")details command: json object with all task fields or pretty-printed textbatch-abandon command: json array of abandoned task objects or summary stringconfig command: json object {key: value} or confirmation messageStorage: config file written to ~/.config/ticktick-skill/config.json (created if missing). credentials stored in ~/.clawdbot/credentials/ticktick-cli/ by auth setup.
Format defaults: human-readable (rich or plain) unless --json, --yaml, or --format <type> specified. all json output valid json parseable by standard parsers.
user knows the skill worked when:
/tasks output after /tasks add ... with correct title, project, due date, priority/tasks --status completed after /tasks complete <id>/tasks abandon <id> (visible in /tasks details <id>)/tasks --project Work shows only work tasks/tasks --due today shows only today's tasks/tasks edit <id> --title "new"/tasks config set default.project Personal then /tasks add "foo" uses Personal without --list--group used--format rich used and display.colors is truejq and other tools parse it without errorcredits: original skill from clawhub. enriched to include explicit inputs, edge cases, decision points, and output contract per implexa standards.