productivity-todoist

name	productivity-todoist
description	Fetch and manage Todoist tasks. Use when the user asks about "todoist tasks", "show my tasks", "what's due", "overdue tasks", "triage tasks", or when another skill needs Todoist task context.

Todoist

Overview

Read Todoist tasks from synced markdown files and manage them via the Python SDK. Provides task context to other skills (e.g., life-coach planning) and allows direct task management from the CLI.

Context

• Tasks are synced to todoist-sync/tasks/ as markdown files with YAML frontmatter
• Sync freshness is tracked in todoist-sync/sync-status.yml
• Token stored at ~/.config/todoist-cli/config.json (set up via npx @doist/todoist-cli auth token)
• Triage script uses uv run --script so dependencies are handled automatically
• For project structure, labels, priorities, and collaboration model, see the "Todoist organization reference" appendix in todoist-sync/README.md

Process

Step 1: Sync (always do this first)

Run the sync script to refresh local markdown files from Todoist:

./todoist-sync/scripts/sync.py

Or via justfile:

just todoist-sync

Check todoist-sync/sync-status.yml for last sync time. If the sync is recent (within the last hour), you can skip this step.

Step 2: Read tasks from synced files

Tasks live at todoist-sync/tasks/{project-slug}/{section-slug}/{task-slug}.md.

Each file has YAML frontmatter:

---
title: "Review Q1 invoices"
id: "6VpWpv2qfH9pm7fG"
project: "Work"
section: "Business ops"
priority: "p2"
labels: ["30-min", "admin"]
due: "2026-02-15"
recurring: false
created: "2026-02-01T12:00:00+05:30"
updated: "2026-02-08T12:00:00+05:30"
url: "https://app.todoist.com/app/task/..."
parent_id: null
---

To answer common queries, read the frontmatter:

• Today's tasks: find files where due is today or earlier
• Tasks by project: read from the project's subdirectory
• High priority: find files where priority is p1
• Tasks with label: find files where labels contains the label
• All tasks: read all .md files under todoist-sync/tasks/

Step 3: Triage (write operations)

For modifying tasks (close, reschedule, label), use scripts/todoist-triage.py:

echo '[{"action": "drop", "task_name": "old task"}, {"action": "reschedule", "task_name": "deferred", "due_date": "2026-04-01"}]' | \
  ./scripts/todoist-triage.py

Actions: drop (add "dropped" label + close), complete (close), reschedule (update date), someday (add "someday" label + remove date)

After triage, run sync again to update the local files.

Resources

• todoist-sync/scripts/sync.py: One-way sync from Todoist to markdown (run first)
• todoist-sync/tasks/: Synced task files (read these for current state)
• todoist-sync/sync-status.yml: Sync metadata (last sync time, counts)
• scripts/todoist-triage.py: Batch triage via Todoist API (drop/complete/reschedule/someday)

Guidelines

• Always sync before reading tasks to ensure freshness
• Priority mapping: p1 (urgent/important), p2 (important), p3 (urgent, not important), p4 (neither). Todoist API inverts these: API priority 4 = p1, API priority 1 = p4.
• When reviewing tasks during planning: overdue tasks need a decision (reschedule, do today, or drop). Tasks with no due date need --all during weekly review.
• After any triage action, re-run sync to update the local markdown files