| 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
