todoist

name	todoist
description	Todoist CRUD via API v1 — tasks (due + deadline), projects, sections, labels, comments, reminders. Use when user mentions Todoist, their todo list, scheduling/completing a task, "加到待辦", "今天的 Todoist".
allowed-tools	Bash(python3 *)

Todoist CRUD

Wraps the Todoist REST API v1 via a bundled Python script. Token: ${CLAUDE_SKILL_DIR}/.apikey (or TODOIST_API_TOKEN env var, takes precedence).

Path conventions

${CLAUDE_SKILL_DIR} = directory holding this SKILL.md. Resolve once per shell:

export CLAUDE_SKILL_DIR=<path reported by the Skill tool's "Base directory">

The script self-locates via __file__; the env var is only for shell invocations.

Invocation

python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" <resource> <action> [args...]

Resources: tasks, projects, sections, labels, comments, reminders. Successful calls print JSON; errors print HTTP <code> to stderr and exit non-zero.

References (load on demand)

• references/api-reference.md — endpoint matrix, body fields, date-parsing notes, Premium-only details, Sync API (filters), error codes, soft-delete semantics
• references/filter-system.md — the user's deliberate 8-filter / label system. Source of truth for "what should I do now?" / weekly review / prioritization questions
• references/reminders.md — reminders write API (Premium-gated; load when user upgrades or for read-side audit)

Common playbooks

Add a task

python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" tasks add "買牛奶" --due "tomorrow 9am" --priority 2

• --due accepts English natural-language or YYYY-MM-DD. Chinese relative dates fail — resolve to absolute date yourself before calling. Details in api-reference.md § Date parsing notes.
• --priority 1 (lowest) → 4 (highest, p1 in UI).
• --labels comma-separated.
• --project-id to target a project (resolve name → id with projects list).

Today's tasks

python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" tasks list --filter "today"

Filter strings: overdue, 7 days, p1, @label, #Project. Combine with & |.

Complete / reschedule / edit

python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" tasks close <id>
python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" tasks update <id> --due "friday"
python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" tasks update <id> --content "new title" --priority 3

reopen to un-complete, delete to remove. Update only flags you pass — omitted fields untouched.

Premium-only operations

--deadline-date (tasks) and reminders add/update return HTTP 403 PREMIUM_ONLY on Free. Don't call. Free-tier substitutes:

• Day-of reminder → just --due "YYYY-MM-DD HH:MM" (Todoist auto-creates the reminder).
• T-N pre-event nudge → create a separate prep task due on the T-N date.

Full Premium-gate behavior + read-side ops (work on Free): see api-reference.md § Premium-only writes and references/reminders.md.

Project / label bookkeeping

python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" projects list
python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" projects add "Side project"
python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" labels list
python3 "${CLAUDE_SKILL_DIR}/scripts/todoist.py" labels add "deep-work"

Workflow guidance

1. Resolve names → IDs first. Todoist uses numeric IDs. list the resource, match by name/content, act on the id.
2. close > delete for completed tasks (preserves history). Confirm before delete — irreversible.
3. Soft-delete: DELETE flips is_deleted: true; subsequent GET returns 200 with tombstone. Script exits 2 with stderr warning. Treat exit 2 as "gone".
4. Token errors (HTTP 401/403): regenerate at Todoist Settings → Integrations → Developer; write to ${CLAUDE_SKILL_DIR}/.apikey.
5. Rate limit: ~450 req / 15 min. For bulk reads, prefer tasks list --ids "1,2,3" over loops of get.

Token file

${CLAUDE_SKILL_DIR}/.apikey, mode 600. Rotate:

printf '%s' "<new-token>" > "${CLAUDE_SKILL_DIR}/.apikey"
chmod 600 "${CLAUDE_SKILL_DIR}/.apikey"

Or export TODOIST_API_TOKEN=... to override without touching the file.