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