From todoist-manager
Complete Todoist integration for natural-language task management, daily planning workflows, and productivity coaching through Claude Code conversations
npx claudepluginhub infiquetra/infiquetra-claude-plugins --plugin todoist-managerThis skill uses the workspace's default tool permissions.
Complete personal productivity manager integrating Todoist with Claude Code for natural-language task management, strategic planning, and productivity coaching.
Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.
Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.
Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.
Complete personal productivity manager integrating Todoist with Claude Code for natural-language task management, strategic planning, and productivity coaching.
echo $TODOIST_TOKEN
If not set:
❌ TODOIST_TOKEN not set. You need a Todoist API token to use this skill.
How to get your token:
1. Go to https://todoist.com/app/settings/integrations/developer
2. Scroll to "API token" section
3. Copy your token
4. Run: export TODOIST_TOKEN="your_token_here"
5. Add to your shell profile (~/.zshrc or ~/.bashrc) to persist
python -c "import todoist_api_python; print('✓ SDK installed')"
If not installed:
pip install 'todoist-api-python>=3.1.0,<4.0.0'
# or
uv pip install 'todoist-api-python>=3.1.0,<4.0.0'
Script location: plugins/todoist-manager/skills/todoist-manage/scripts/todoist_client.py
Test:
python3 plugins/todoist-manager/skills/todoist-manage/scripts/todoist_client.py overview
Expected: JSON output with overview data
All operations use the todoist_client.py script with JSON output.
python3 <script_path> <resource> <action> [--options]
Resources: tasks, projects, sections, labels, comments, overview, daily-summary
Output: Always JSON with this structure:
{
"success": true,
"data": { ... },
"count": 5
}
Or for errors:
{
"error": true,
"message": "Error description",
"context": { ... }
}
python3 todoist_client.py tasks list
Options:
--project-id 12345 - Filter by project--section-id 67890 - Filter by section--label urgent - Filter by label name--ids 111 222 333 - Specific task IDs--include-child-projects - Include tasks from all child/descendant projects (requires --project-id)python3 todoist_client.py tasks filter --query "today & p1"
Common queries:
"today" - Tasks due today"overdue" - All overdue tasks"7 days" - Tasks due in next 7 days"today & p1" - Urgent tasks due today"#Work" - Tasks in Work project"@urgent" - Tasks with urgent label"today & !@routine" - Today's tasks excluding routine"(overdue | today) & (p1 | p2)" - High-priority tasks needing attentionSee: references/filter-query-syntax.md for complete query language
python3 todoist_client.py tasks get --task-id 12345
Full form:
python3 todoist_client.py tasks add \
--content "Task title" \
--description "Additional details" \
--project-id 12345 \
--section-id 67890 \
--labels urgent important \
--priority 4 \
--due-string "tomorrow at 3pm" \
--duration 30 \
--duration-unit minute
Minimal:
python3 todoist_client.py tasks add --content "Buy milk"
Priority values:
1 = Normal (P4 in UI)2 = High (P3 in UI)3 = Higher (P2 in UI)4 = Urgent (P1 in UI)Due date options (use ONE):
--due-string "tomorrow at 3pm" - Natural language (recommended)--due-date "2025-02-24" - Date only (YYYY-MM-DD)--due-datetime "2025-02-24T15:00:00Z" - Full datetime (RFC3339)Duration for time-blocking:
--duration 30 --duration-unit minute - 30-minute task--duration 2 --duration-unit day - 2-day taskpython3 todoist_client.py tasks quick-add --text "Buy milk tomorrow @shopping p1"
Quick-add syntax:
tomorrow - Due date@shopping - Labelp1 - Priority (urgent)#Work - Project!3 - Priority (alternative syntax)every monday - Recurring^today - Due date with time//Section Name - SectionExamples:
"Call John tomorrow at 2pm @phone p2 #Work""Team meeting every Friday at 10am #Work""Review PR !1 ^today"python3 todoist_client.py tasks update \
--task-id 12345 \
--content "Updated title" \
--priority 4 \
--due-string "friday"
Updatable fields: content, description, labels, priority, due (date/string/datetime), duration
python3 todoist_client.py tasks complete --task-id 12345
python3 todoist_client.py tasks uncomplete --task-id 12345
python3 todoist_client.py tasks delete --task-id 12345
⚠️ Confirm before deleting unless clearly temporary or user explicitly requested deletion.
For multiple tasks, use parallel bash calls or loop:
# Complete multiple tasks
for task_id in 111 222 333; do
python3 todoist_client.py tasks complete --task-id $task_id
done
Present summary:
✅ Completed 3 tasks:
- Task A
- Task B
- Task C
List all:
python3 todoist_client.py projects list
Get one:
python3 todoist_client.py projects get --project-id 12345
Add project:
python3 todoist_client.py projects add \
--name "New Project" \
--color "blue" \
--is-favorite \
--view-style "board"
Colors: berry_red, red, orange, yellow, olive_green, lime_green, green, mint_green, teal, sky_blue, light_blue, blue, grape, violet, lavender, magenta, salmon, charcoal, grey, taupe
Update:
python3 todoist_client.py projects update --project-id 12345 --name "Renamed Project"
Delete:
python3 todoist_client.py projects delete --project-id 12345
⚠️ Confirm before deleting projects - this deletes all contained tasks.
List (all or by project):
python3 todoist_client.py sections list
python3 todoist_client.py sections list --project-id 12345
Add section:
python3 todoist_client.py sections add --name "In Progress" --project-id 12345 --order 1
Update:
python3 todoist_client.py sections update --section-id 67890 --name "Completed"
Delete:
python3 todoist_client.py sections delete --section-id 67890
List all:
python3 todoist_client.py labels list
Add label:
python3 todoist_client.py labels add \
--name "urgent" \
--color "red" \
--is-favorite
Update:
python3 todoist_client.py labels update --label-id 54321 --name "super-urgent" --color "berry_red"
Delete:
python3 todoist_client.py labels delete --label-id 54321
List (for task or project):
python3 todoist_client.py comments list --task-id 12345
python3 todoist_client.py comments list --project-id 67890
Add comment:
python3 todoist_client.py comments add --content "Progress update: 50% complete" --task-id 12345
Update:
python3 todoist_client.py comments update --comment-id 99999 --content "Updated progress: 75% complete"
Delete:
python3 todoist_client.py comments delete --comment-id 99999
Use comments for:
Goal: Start the day with clarity and focus.
1. Fetch overview:
python3 todoist_client.py overview
Output structure:
{
"success": true,
"data": {
"overdue": {
"count": 3,
"by_project": {
"Work": [...],
"Personal": [...]
}
},
"today": {
"count": 12,
"by_project": {...}
},
"upcoming": {
"count": 25,
"by_project": {...}
},
"total_pending": 40
}
}
2. Present with priority grouping:
📊 Good morning! Here's your overview:
🔴 Overdue (3)
Work:
□ [P1] Fix production bug (urgent!)
□ [P2] Client proposal draft
Personal:
□ [P3] Schedule dentist appointment
📅 Today (12 tasks)
Work (8):
□ [P1] Team standup (9am)
□ [P1] Deploy feature X
□ [P2] Code review for PR #123
□ [P2] Update documentation
□ [P3] Clean up backlog
...
Personal (4):
□ [P2] Gym workout
□ [P3] Meal prep
...
📆 Upcoming (25 tasks in next 7 days)
Top priorities:
- [P1] Quarterly planning (Friday)
- [P1] Client demo (Thursday)
- [P2] 1-on-1 with manager (Wednesday)
3. Coach for focus selection:
Ask user:
4. Generate time-blocked schedule:
Based on user selections and task durations:
⏰ Your Focus Plan for Today
🌅 Morning (9am-12pm) - Deep Work
□ 9:00-9:15 Team standup (15 min)
□ 9:30-11:00 Deploy feature X (90 min) [P1] 🔴
□ 11:00-12:00 Code review PR #123 (60 min) [P2]
☀️ Afternoon (1pm-5pm) - Collaboration
□ 1:00-2:00 Update documentation (60 min) [P2]
□ 2:00-3:00 Client proposal draft (60 min) [P2] ⚠️ overdue
□ 3:00-4:00 Fix production bug (60 min) [P1] 🔴 ⚠️ overdue
🌙 Evening (5pm-6pm) - Personal
□ 5:00-6:00 Gym workout (60 min) [P2]
⏱️ Total: 6.25 hours (buffer: 30 min) ✅
💡 Tips:
- You have 3 overdue tasks - prioritizing those first
- Schedule looks achievable with buffer
- Consider gym as optional if running behind
5. Create focus filter:
# Save user's focus selections as custom filter
python3 todoist_client.py tasks filter --query "(id:111 | id:222 | id:333 | id:444 | id:555)"
Or create a label:
python3 todoist_client.py labels add --name "today-focus"
# Then add label to selected tasks
python3 todoist_client.py tasks update --task-id 111 --labels today-focus work
6. Proactive suggestions:
See: references/productivity-workflows.md for complete morning review template
Goal: Reflect on progress and prep for tomorrow.
1. Fetch daily summary:
python3 todoist_client.py daily-summary
Output:
{
"success": true,
"data": {
"completed_today": {
"count": 8,
"tasks": [...]
},
"remaining_today": {
"count": 4,
"tasks": [...]
},
"completion_rate": "66.7%"
}
}
2. Celebrate wins:
🎉 Great work today!
✅ Completed: 8/12 tasks (67%)
What you accomplished:
✓ Deploy feature X (P1) - Nice work!
✓ Team standup
✓ Code review PR #123 (P2)
✓ Update documentation
✓ Gym workout
...
🌟 You cleared 2 overdue tasks and completed all P1s!
3. Review incomplete tasks:
⏳ Remaining tasks (4):
□ Client proposal draft (P2) - Due today
→ Reschedule to tomorrow?
□ Fix production bug (P1) - Due today
→ What blocked this?
□ Clean up backlog (P3)
→ Still relevant or defer?
□ Meal prep (P3)
→ Move to weekend?
For each incomplete, ask:
Actions:
python3 todoist_client.py tasks update --task-id 123 --due-string "tomorrow"--due-string "next week" or remove due datepython3 todoist_client.py tasks delete --task-id 1234. Prep for tomorrow:
python3 todoist_client.py tasks filter --query "tomorrow"
Present tomorrow's overview:
📅 Tomorrow Preview (8 tasks)
Top priorities:
□ [P1] Client proposal draft (rescheduled from today)
□ [P1] Quarterly planning prep
□ [P2] 1-on-1 with manager
Looks manageable! Get good rest. 😴
5. Flag patterns:
See: references/productivity-workflows.md for complete evening review template
Goal: Big-picture perspective and course correction.
1. Generate weekly metrics:
# Approximate with filters
python3 todoist_client.py tasks filter --query "completed this week"
python3 todoist_client.py tasks filter --query "next 7 days"
python3 todoist_client.py tasks filter --query "overdue"
2. Present weekly dashboard:
📊 Week of Feb 17-23, 2025
Completed: 45 tasks ✅
Overdue: 3 tasks ⚠️
Completion rate: 82% 🎯
By Project:
Work: 28 tasks (62%)
Personal: 15 tasks (33%)
Side Project: 2 tasks (5%)
By Priority:
P1: 15 tasks (33%)
P2: 20 tasks (44%)
P3+: 10 tasks (22%)
Project Health:
🟢 Work - On track (8 tasks/week, low overdue)
🟡 Side Project - At risk (no activity in 5 days)
🔴 Personal - Stalled (10 tasks overdue, no progress)
3. Review project health:
For each project:
Status indicators:
4. Coaching questions:
5. Identify patterns:
6. Weekly maintenance:
See: references/productivity-workflows.md for complete weekly review template
When to trigger:
Process:
1. Clarify outcome:
2. Identify steps:
3. Create subtasks:
# Add parent task if needed
python3 todoist_client.py tasks add \
--content "Write quarterly report" \
--project-id 12345 \
--due-string "Friday"
# Get task ID from response, then add subtasks
python3 todoist_client.py tasks add \
--content "Research last quarter's data" \
--parent-id [parent_task_id] \
--duration 30 \
--duration-unit minute \
--labels computer \
--priority 2
python3 todoist_client.py tasks add \
--content "Draft executive summary" \
--parent-id [parent_task_id] \
--duration 45 \
--duration-unit minute \
--labels computer focus \
--priority 2
# Continue for all subtasks
4. Add context:
--duration, --duration-unit)@computer, @phone, @office)@focus, @quick, @routine)Example breakdown:
"Write quarterly report" →
1. Research last quarter's data (30 min) @computer
2. Draft executive summary (45 min) @focus @computer
3. Create performance charts (30 min) @computer
4. Write detailed sections (90 min) @focus @computer
5. Review and edit (20 min) @computer
6. Get feedback from manager (async) @waiting
7. Incorporate feedback (30 min) @computer
8. Final proofread (15 min) @computer
9. Submit report (5 min) @computer
Total: ~4.5 hours of work time + async feedback
See: references/productivity-workflows.md for complete breakdown framework
When to use:
Process:
1. Calculate available time:
Ask:
Calculate:
Available = End - Start - Meetings - Breaks - Buffer (10%)
Example:
9am-6pm = 9 hours = 540 minutes
- Meetings: 2 hours = 120 minutes
- Lunch + breaks: 1 hour = 60 minutes
- Buffer (10%): 36 minutes
= Available: 324 minutes (5.4 hours)
2. Fetch tasks with durations:
python3 todoist_client.py tasks filter --query "today & !no duration"
3. Prioritize and fit:
Algorithm:
4. Present schedule:
📅 Today's Schedule (324 min available)
🔴 Must Do (180 min)
□ 9:00-10:30 Deploy feature X (90 min)
□ 11:00-12:00 Code review (60 min)
□ 2:00-2:30 Client call (30 min)
🟡 Should Do (90 min)
□ 2:30-3:30 Documentation (60 min)
□ 3:30-4:00 Email responses (30 min)
Buffer: 54 minutes ✅
⚠️ Deferred to tomorrow:
□ Backlog cleanup (60 min) - P3
□ Learning time (45 min) - P3
Capacity warnings:
5. Match energy levels:
Morning (9am-12pm): Deep work
Afternoon (1pm-5pm): Collaboration
Evening (5pm-6pm): Admin
# Morning focus tasks
python3 todoist_client.py tasks filter --query "today & @focus & duration > 60"
# Evening quick tasks
python3 todoist_client.py tasks filter --query "today & @quick & duration < 30"
See: references/productivity-workflows.md for complete time-boxing framework
Automatically detect and flag:
🟢 Green Flags (Healthy):
🟡 Yellow Flags (Warning):
🔴 Red Flags (Action Needed):
Coaching interventions:
For priority inflation:
"I notice 15 tasks marked P1. That's overwhelming - not everything can be urgent.
Let's identify the true must-dos for today and downgrade or defer the rest."
For chronic deferrals:
"This task has been rescheduled 5 times. Let's figure out why:
- Still relevant? Or delete?
- Too big? Break it down?
- Blocked? Create unblocking task?
- Lost motivation? Defer indefinitely?"
For overload:
"You have 12 hours of tasks for 6 hours available time.
Let's prioritize the critical 3-4 tasks and defer the rest."
See: references/productivity-workflows.md for complete pattern recognition guide
Always offer when relevant:
After showing tasks:
During planning:
After completion:
Encourage habits:
{
"error": true,
"message": "TODOIST_TOKEN environment variable not set"
}
Response:
❌ Todoist token not configured.
To fix:
1. Get your token: https://todoist.com/app/settings/integrations/developer
2. Set it: export TODOIST_TOKEN="your_token_here"
3. Persist: Add to ~/.zshrc or ~/.bashrc
4. Reload: source ~/.zshrc
Then try again!
{
"error": true,
"message": "Failed to list tasks: 429 Too Many Requests"
}
Response:
⚠️ Hit Todoist rate limit (too many requests).
The API has automatic retry, but you might need to wait a minute.
Try again in 60 seconds.
Tip: Use filter queries instead of listing all tasks to reduce API calls.
{
"error": true,
"message": "Failed to get task: Task not found",
"task_id": "12345"
}
Response:
❌ Task 12345 not found. It may have been deleted or the ID is incorrect.
Want to search for the task instead? I can filter by content.
{
"error": true,
"message": "Failed to list tasks: Connection timeout"
}
Response:
❌ Can't reach Todoist API. Check your internet connection.
If you're online, Todoist might be experiencing issues.
Status: https://status.todoist.com
Format based on context:
As checklist:
□ Task A (P1) - Due today
□ Task B (P2) - Due tomorrow
□ Task C (P3) - No due date
As table:
| Task | Priority | Due Date | Project |
|---------------------|----------|-----------|---------|
| Deploy feature X | P1 🔴 | Today | Work |
| Code review | P2 🟡 | Tomorrow | Work |
| Gym workout | P2 🟡 | Today | Personal|
Grouped by project:
Work (8 tasks):
🔴 P1: Deploy feature X (due today)
🟡 P2: Code review (due tomorrow)
⚪ P3: Documentation update (no date)
Personal (4 tasks):
🟡 P2: Gym workout (due today)
⚪ P3: Meal prep (due Sunday)
For morning review: Group by priority, highlight overdue For time-blocking: Format as timeline with durations For weekly review: Show metrics and trends For search results: Show relevant fields (due date, project, priority)
Always:
Destructive actions:
Prompt: "This will delete [X]. This can't be undone. Confirm?"
Significant changes:
Prompt: "This will [action] affecting [N] items. Proceed?"
Read operations:
Minor updates:
When unclear, err on side of confirmation for user peace of mind.
Exceptions:
references/todoist-api-reference.md - Complete SDK method reference, parameters, return typesreferences/filter-query-syntax.md - Full Todoist filter query language with examplesreferences/productivity-workflows.md - Strategic planning templates, coaching frameworksWhen to consult:
User: "Good morning, let's plan my day"
Claude:
Runs python3 todoist_client.py overview
Parses JSON output
Presents with priority grouping:
📊 Good morning! Here's your overview:
⚠️ 3 overdue tasks (2 urgent)
📅 12 tasks due today
📆 25 upcoming in next 7 days
Top priorities for today:
🔴 [P1] Fix production bug (overdue)
🔴 [P1] Deploy feature X
🔴 [P1] Client call at 2pm
This looks achievable. Which 3-5 tasks would make today a success?
User selects focus tasks
Generates time-blocked schedule
Creates focus filter or label
Estimates total time vs available
Offers to defer if over capacity
User: "I need to work on the client proposal but don't know where to start"
Claude:
Asks clarifying questions:
Let me help break this down.
- What's the proposal for? (Service offering? Pricing? Pitch?)
- Who's the audience? (Technical? Executive?)
- What's the deadline?
- How long do you think this will take total?
User answers
Suggests breakdown:
Here's a breakdown:
1. Research client's needs (30 min) @computer
2. Draft outline (20 min) @computer
3. Write executive summary (45 min) @focus @computer
4. Detail service offering (60 min) @focus @computer
5. Create pricing table (30 min) @computer
6. Design cover page (20 min) @computer
7. Review and polish (20 min) @computer
8. Get internal feedback (async) @waiting
9. Incorporate feedback (30 min) @computer
10. Send to client (5 min) @computer
Total: ~4 hours of work + async feedback
Should I create these as subtasks in Todoist?
User confirms
Creates parent task + all subtasks with appropriate metadata
Suggests starting with research (first subtask)
User: "Let's review my day"
Claude:
Runs python3 todoist_client.py daily-summary
Parses output
Celebrates wins:
🎉 Solid day!
✅ Completed: 8/12 tasks (67%)
What you accomplished:
✓ Deploy feature X (P1) - Big win! 🚀
✓ Client call
✓ Code review
✓ Documentation update
✓ Gym workout
✓ Email responses
✓ Team standup
✓ Planning session
You cleared all your P1 tasks and made progress on 2 projects!
Reviews incomplete tasks:
⏳ Remaining (4 tasks):
□ Fix production bug (P1) - Due today
What blocked this? Still urgent?
□ Client proposal (P2) - Due today
Want to reschedule to tomorrow?
□ Backlog cleanup (P3)
Defer to this weekend?
□ Meal prep (P3)
Move to tomorrow or Sunday?
For each, gets user input and takes action (reschedule, defer, delete)
Prepares tomorrow's overview
Flags any patterns (if applicable)
Essential operations:
# Morning overview
python3 todoist_client.py overview
# Today's tasks
python3 todoist_client.py tasks filter --query "today"
# Add task
python3 todoist_client.py tasks add --content "Task name" --due-string "tomorrow"
# Quick add (natural language)
python3 todoist_client.py tasks quick-add --text "Buy milk tomorrow @shopping p1"
# Complete task
python3 todoist_client.py tasks complete --task-id 12345
# Filter (custom query)
python3 todoist_client.py tasks filter --query "today & p1"
# Daily summary
python3 todoist_client.py daily-summary
# List projects
python3 todoist_client.py projects list
# List labels
python3 todoist_client.py labels list
Script path: plugins/todoist-manager/skills/todoist-manage/scripts/todoist_client.py
For complex multi-turn workflows (weekly planning, major reorganization, strategic coaching), spawn the todoist-manager agent:
# Example trigger
"I need help completely reorganizing my task list and projects"
The agent has full access to this skill and can conduct extended planning sessions with strategic thinking.
When to use agent:
When to use skill directly: