todoist-setup

name	todoist-setup
description	Connect Todoist to Dex for two-way task sync
integration	{"id":"todoist","name":"Todoist","mcp_server":"todoist-mcp","auth":"api_key","enhances":[{"skill":"daily-plan","capability":"Merges Todoist tasks due today alongside Dex tasks"},{"skill":"triage","capability":"Routes items to Dex, Todoist, or both"},{"skill":"process-inbox","capability":"Creates tasks in both systems when processing captured items"},{"skill":"week-review","capability":"Shows cross-system completion stats (Dex + Todoist)"}],"new_capabilities":[{"name":"Bidirectional task sync","trigger":"Automatic at daily plan and task creation touchpoints"}],"sync":{"direction":"bidirectional","entities":"tasks"}}

Todoist Setup

Connect your Todoist account to Dex so tasks stay in sync across both systems. Create a task in Dex and it appears in Todoist. Complete one in Todoist and Dex knows about it.

What This Enables

Once connected, Dex can:

• Daily Plan (/daily-plan): Merge Todoist tasks due today alongside your Dex tasks
• Triage (/triage): Route new items to Dex, Todoist, or both
• Process Inbox (/process-inbox): Same routing options when processing captured items
• Week Review (/week-review): See completion stats across both Dex and Todoist

How Sync Works (Plain English)

• When you create a task in Dex, it gets pushed to Todoist automatically
• When you complete a task in Todoist, Dex picks it up during your next daily plan
• Task titles, priorities, and completion status travel between both systems
• Each system keeps its own copy — if one goes offline, the other still works
• Sync happens at natural touchpoints (daily plan, triage) — not constantly in the background
• Tasks created by Dex carry a [dex:task-ID] marker in the description so the systems never duplicate

Privacy

• Task titles and status sync between Dex and Todoist. No task content or notes are stored beyond what you already have in both systems.
• Your API key stays local on your machine in System/integrations/config.yaml (gitignored)
• Dex never shares your Todoist data with third parties
• Tasks created in Todoist are only pulled into Dex if they were NOT originally pushed from Dex (loop prevention via [dex:...] marker)

When to Run

• User types /todoist-setup
• User asks about connecting Todoist or task sync
• User wants Todoist tasks in daily plans
• During /integrate-mcp if Todoist is mentioned

---

Setup Flow

Step 1: Check if Already Connected

1. Check System/integrations/config.yaml for a todoist: section with enabled: true
2. If enabled, test the connection by listing projects with the stored API key
3. If healthy, skip to Reconfiguration section below
4. If not configured or unhealthy, continue to Step 2

Step 2: Explain What We're Setting Up

Say:

**Let's connect Todoist to Dex.**

Two-way task sync. Create in Dex — appears in Todoist. Complete in Todoist — done in Dex.

**What you'll need:**
- Your Todoist API token (I'll show you where to find it)
- About 2 minutes

**Ready to go?**

Wait for confirmation.

Step 3: Get the API Key

Guide the user:

To get your Todoist API token:

1. Open Todoist (web or app)
2. Go to **Settings** → **Integrations** → **Developer**
3. Copy the **API token** shown there

Paste it here when you have it.

Wait for the user to provide their API key. Validate it's a non-empty string (Todoist API tokens are typically 40-character hex strings).

Step 4: Add MCP Server to Config

Check the user's MCP configuration. If todoist-mcp is not listed:

1. Explain:

I'll add the Todoist connector to your configuration.
This lets Dex talk to Todoist using your API token.

2. Add to the user's .mcp.json (use the /dex-add-mcp skill or manual edit):

{
  "todoist-mcp": {
    "command": "npx",
    "args": ["-y", "todoist-mcp-server"],
    "env": {
      "TODOIST_API_KEY": "<user's API key>"
    }
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 5: Test the Connection

Use the API key to list projects as a connectivity test. Run a curl or use the MCP server:

curl -s -H "Authorization: Bearer $API_KEY" https://api.todoist.com/api/v1/projects

If projects load successfully:

Connected! I can see your Todoist projects:

1. Inbox
2. Work
3. Personal
...

Looking good!

If it fails:

That API key didn't work. A few things to check:

1. **Copy the full key** — it should be about 40 characters
2. **Check for extra spaces** before or after the key
3. **Regenerate the key** in Todoist Settings → Integrations → Developer

Want to try again?

Retry up to 2 times, then offer to skip and come back later.

Step 6: Choose Default Project

Ask the user which Todoist project should receive Dex tasks:

**Which Todoist project should Dex tasks go into?**

Your projects:
1. Inbox
2. Work
3. Personal
...

You can pick one default project, or map each Dex pillar to a different project.

**Option A:** All Dex tasks go to one project (simplest)
**Option B:** Map each pillar to a project:
  (Read pillar names from `System/pillars.yaml` and list them here)
  - [pillar 1 name] → [project]
  - [pillar 2 name] → [project]
  - [pillar 3 name] → [project]

Which works for you?

Save their choices for the config file.

Step 7: Trust Level

Ask about sync autonomy — never use the word "tier" (per integration-patterns.md):

**How hands-on do you want to be with task sync?**

1. **"Show me first"** — I'll preview changes before syncing (recommended to start)
2. **"Keep them in sync"** — Tasks auto-sync both ways, silently
3. **"Only pull in"** — Import tasks from Todoist but don't push back

Map their choice to config values:

• Show me first → trust_level: confirm_each
• Keep them in sync → trust_level: autonomous
• Only pull in → trust_level: read_only

Step 8: Save Configuration

Write to System/integrations/config.yaml — update the todoist section:

todoist:
  enabled: true
  configured_at: YYYY-MM-DD
  mcp_server: todoist-mcp
  auth_type: api_key
  api_key: <user's API key>
  task_sync: true
  trust_level: <confirm_each | autonomous | read_only>
  project: <default project name>
  pillar_map:
    deal_support: <project name or omit>
    thought_leadership: <project name or omit>
    product_feedback: <project name or omit>
  sync_labels: []
  auto_sync: true
  features:
    task_sync: true
    external_task_merge: true

If the file already exists, only update the todoist: section. Preserve other integration configs.

Step 9: Capability Cascade

Read the integration manifest from this skill's frontmatter. Present:

**Todoist is connected!** Here's what just changed:

### Enhanced (existing skills that got smarter)

- **`/daily-plan`** → Merges Todoist tasks due today alongside your Dex tasks.
  Externally-created tasks show a [Todoist] label so you know where they came from.

- **`/triage`** → Now offers routing to Dex, Todoist, or both when processing items.

- **`/process-inbox`** → Same routing — "This looks like a task. Add to Dex, Todoist, or both?"

- **`/week-review`** → Shows completion stats across both systems so you see the full picture.

### New Superpowers

- Bidirectional task sync — automatic at daily plan and task creation touchpoints.

### How It Works

- **Reading:** Todoist tasks appear in your daily plan automatically
- **Writing:** [trust level description based on user's choice above]
- **Privacy:** Task titles and status sync. Your API key stays local. No data shared with third parties.

These work automatically starting now. Run `/dex-level-up` anytime to see what else you can do.

---

Troubleshooting

API Key Invalid or Expired

Todoist API keys don't expire unless you regenerate them. If you see auth errors:

1. Go to Todoist Settings → Integrations → Developer
2. Copy the current API token (or regenerate if needed)
3. Update the key by running /todoist-setup again

Tasks Not Syncing

A few possibilities:

• Sync only happens at touchpoints — during /daily-plan, task creation, or /triage. There's no background sync.
• Check the project mapping — if your Dex pillar maps to a project that was renamed or deleted in Todoist, tasks may go to the Inbox instead.
• Rate limits — Todoist allows 450 requests per minute. The adapter handles 429 responses with automatic retry, so this is almost never an issue.

Wrong Project

If tasks are landing in the wrong Todoist project:

1. Run /todoist-setup again
2. Update the pillar-to-project mapping
3. Existing tasks won't move — only new tasks use the updated mapping

Duplicate Tasks

If you see duplicates, check:

• Dex-originated tasks should have [dex:task-...] in their Todoist description. The adapter skips these during pull-in to prevent loops.
• Todoist-originated tasks that you manually add to Dex won't have a mapping in .sync-state.json and may get pulled again. Mark them in Dex to create the mapping.

"Todoist MCP not found"

The Todoist adapter uses direct API calls (not MCP) for the sync bridge. The MCP server is optional but enhances other skills. Re-run /todoist-setup to detect and fix configuration.

---

Reconfiguration

If the user runs /todoist-setup when already configured:

1. Check current config from System/integrations/config.yaml
2. Test the existing API key with a project list call
3. Show current mapping and trust level
4. Offer options:
   • Update project mapping
   • Change sync behavior (trust level)
   • Update API key
   • Disconnect Todoist

Disconnect Flow

If user wants to disconnect:

1. Update System/integrations/config.yaml:

   todoist:
     enabled: false
   

2. Confirm: "Todoist is disconnected. Tasks will no longer sync between systems. Your existing tasks in both Dex and Todoist are unchanged. Run /todoist-setup anytime to reconnect."