| name | todoist |
| description | Use when creating or processing Todoist tasks, triaging inbox items, doing daily task review, calibrating Todoist triage behavior, or turning corrections into reusable preferences. Routes to operations (CLI actions) vs calibrated triage (policy, context recovery, preference memory, evals). Trigger this whenever the user asks what to do with Todoist items, wants better task triage, or is refining how Todoist decisions should work. |
Todoist (Entrypoint)
Prefer the claude.ai Todoist MCP when it's connected — structured data, batch writes, and safe
rescheduling. The td CLI (@doist/todoist-cli) is the fallback (when the MCP isn't connected,
e.g. headless/cron) and is required inside shell scripts. Full MCP↔td mapping +
priority gotcha: references/operations.md.
Prerequisites
td must be installed: npm install -g @doist/todoist-cli- Auth:
td auth login or set TODOIST_API_TOKEN in ~/.env.zsh
- Verify:
td auth status
Safety / Guardrails
- Do not create or modify tasks proactively without explicit user request.
- If the user asks to "process my tasks", fetch the full relevant set first (don't silently process a subset).
- Read comments before acting; comments may contain critical context and attachments.
- Always confirm before destructive actions (delete, complete, archive).
- When context is weak, do not guess. Prefer
needs_context or needs_user_judgment over a polished but brittle answer.
Writing task content (human-readable)
Task titles/descriptions/comments are read by a human glancing under time pressure — write for fast
comprehension, not machine completeness. The habit to kill: raw IDs, one run-on line, bare URLs.
- Structure, never run-on — bold lead line, then bullets.
- Legible references, never raw IDs — "Review the target list", not
(6gw…); [Title](url), not bare UUIDs/URLs.
- Lead with the action / current state; context below.
Done = line (or checklist) where the finish line is fuzzy.- Status markers (
✅/⏳) on their own bullets, not buried mid-sentence.
- Link, don't dump — point to the source of truth.
Applies to subagent-written tasks too — put this style in their prompt. Full rules + before/after
examples: references/writing-task-content.md.
Quick Reference
| Need | MCP tool (preferred) | td fallback |
|---|
| Today + overdue | find-tasks ("today | overdue") | td today |
| Inbox | find-tasks (projectId "inbox") | td inbox |
| Next 7 days | find-tasks-by-date | td upcoming 7 |
| Create task(s) | add-tasks (batch) | td add "text" |
| View task | fetch-object / find-tasks | td task view id:xxx |
| Read / add comments | find-comments / add-comments (batch) | td comment list id:xxx |
Operating Model
Todoist triage is a copilot workflow, not a blind classifier.
- Recover as much context as possible before deciding.
- Classify the item into a small set of decision buckets.
- Recommend a specific next step only when confidence is justified.
- Record durable corrections as preference memory, not as one-off prose.
- Verify new rules in fresh-session evals before trusting them.
Choose A Mode
