# Todoist Setup

> Todoist Setup is an Agent Skill for apps & automation published in the davekilleen/Dex repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Connect Todoist so Dex can read and update your Todoist tasks on request

- Skill name: `todoist-setup`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/davekilleen/Dex/blob/HEAD/.claude/skills/todoist-setup/SKILL.md
- Repository: davekilleen/Dex (436 GitHub stars when collected)

## SKILL.md

# Todoist Setup

Connect your Todoist account so Dex can work with your Todoist tasks whenever you ask — check what's due, create a task there instead of in Dex, or mark something done.

**What this enables (on request):** Once connected, say "sync with Todoist" — Dex pushes
new tasks to the right Todoist project, marks completions, and pulls back tasks you completed
or created in Todoist directly. Sync runs on demand; Dex does not poll Todoist in the
background without you asking.

## What This Enables

Once connected, you can ask Dex to:
- **See what's due**: "What's due in Todoist today?" — including alongside your daily plan
- **Create there instead**: "Add that to Todoist, not Dex" during triage or any conversation
- **Complete from chat**: "Mark the invoice task done in Todoist"
- **Cross-check**: "Anything in Todoist that isn't tracked in Dex?"

## Privacy

- Dex reads and writes your Todoist tasks only when you ask it to
- Your API key stays local on your machine in `System/integrations/config.yaml` (gitignored)
- Dex never shares your Todoist data with third parties

## 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.**

Once connected, you can ask me to check, create, or complete Todoist tasks
right from our conversations.

**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):

```json
{
  "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:

```bash
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: Save Configuration

Write to `System/integrations/config.yaml` — update the todoist section. Build
`pillar_map` dynamically from the user's actual pillars in `System/pillars.yaml`
(one entry per pillar id — never assume fixed pillar names); it's used when the
user asks Dex to file a task in the matching Todoist project.

```yaml
todoist:
  enabled: true
  configured_at: YYYY-MM-DD
  mcp_server: todoist-mcp
  auth_type: api_key
  api_key: <user's API key>
  project: <default project name>
  pillar_map:
    [pillar_id]: <Todoist project name>   # one entry per pillar, from pillars.yaml
```

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

### Step 8: Capability Cascade

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

```
**Todoist is connected!** Here's what you can do now:

- **Ask about Todoist anytime** — "What's due in Todoist today?", "Add that to
  Todoist", "Mark the invoice task done in Todoist".
- **Bring it into your planning** — during `/daily-plan` or `/triage`, ask Dex to
  include or route to Todoist and it will.
- **Sync on demand** — say "sync Dex with Todoist" and new tasks push, completions flow
  both directions, and tasks you added in Todoist come in for review

**Sync is on demand** — say "sync with Todoist" anytime. Dex doesn't poll in the background.
```

---

## 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

### "Dex doesn't see my Todoist tasks"

Dex only reads Todoist when you ask it to — there is no background sync. Ask
directly ("what's in Todoist?") and if that errors, re-run `/todoist-setup` to
check the connection.

### "Todoist MCP not found"

The connection runs through the Todoist MCP server. 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 the current pillar-to-project mapping
4. Offer options:
   - Update project mapping
   - Update API key
   - Disconnect Todoist

### Disconnect Flow

If user wants to disconnect:

1. Update `System/integrations/config.yaml`:
   ```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."

---

Source: https://www.openparable.com/skill/apps-automation/todoist-setup (OpenParable). Cite the canonical URL above.
