Voiceos Todoist

Voice-control Todoist from VoiceOS — and optionally keep Apple Reminders in sync with it.

License: MIT Platform: macOS Todoist API v1

A local Model Context Protocol server that adds Todoist to VoiceOS, plus a one-way Apple Reminders → Todoist sync. Your API token stays on your Mac — nothing is sent anywhere except Todoist's own API.

🎙️  "Add buy milk to Todoist tomorrow at 9am"
🎙️  "What's on my Todoist for today?"
🎙️  "Mark the expenses task done"

---

✨ Features

• Add / list / complete / update tasks by voice
• Natural-language due dates — "tomorrow at 9am", "every friday"
• Priorities (p1–p4), projects, and filters ("today", "overdue")
• Fuzzy completion — "mark the milk task done" matches Buy milk
• Optional Reminders sync — anything you drop in Apple Reminders lands in Todoist
• One-command installer with guided token setup
• No keys in code — token lives at ~/.config/todoist/token (chmod 600)

---

🚀 Quick start

git clone https://github.com/gabeperez/voiceos-todoist.git
cd voiceos-todoist
./setup.sh

The installer will:

1. Walk you through getting your Todoist API token and validate + save it securely.
2. Install dependencies.
3. Register the integration in VoiceOS automatically.
4. Optionally set up the Reminders → Todoist sync (with a dry-run preview first).

Then restart VoiceOS (or toggle the Todoist integration) and start talking.

Prefer not to clone? Grab todoist-voiceos.zip from the latest release, unzip, and run ./setup.sh.

---

📋 Requirements

OS	macOS with VoiceOS installed
Runtime	Node.js 18+ (setup checks for it)
Account	A Todoist account

Getting your API token

Todoist → Settings → Integrations → Developer → API token (https://app.todoist.com/app/settings/integrations/developer). The setup script links you straight there and validates the token before saving.

---

🛠️ Tools

Tool	What it does
add_task	Create a task — NL due date, priority p1–p4, project, description.
list_tasks	List active tasks; filter by project or query (today, overdue).
complete_task	Close a task by id or content substring (milk → Buy milk).
update_task	Change text / due date / priority / description.
list_projects	List your projects and their ids.

Priority is UI-style: p1 = highest, p4 = none.

---

🔁 Apple Reminders → Todoist sync (optional)

Mirrors incomplete reminders into Todoist on a 5-minute timer:

• Due dates + notes are copied; each Reminders list maps to a Todoist project (auto-created).
• Dedupe + completion state in ~/.config/todoist/sync-state.json.
• When a synced reminder is completed or removed, its Todoist task is closed.
• One-way only — Todoist changes never flow back to Reminders.

npm run sync:dry            # preview what would sync — writes nothing
sync/install-launchd.sh     # enable the 5-minute background timer
sync/uninstall-launchd.sh   # stop it

The first run triggers a macOS Automation → Reminders permission prompt — approve it.

Sync options

Set these in sync/run-sync.sh:

Env	Effect
SYNC_LISTS="Inbox,Work"	Only sync these Reminders lists (default: all).
TODOIST_PROJECT="Inbox"	Force everything into one project (default: list→project).
SYNC_COMPLETIONS="false"	Don't close Todoist tasks on completion/removal.
SYNC_DUE="false"	Don't copy due dates.
DRY_RUN="true"	Report what would sync; write nothing.

---

🧹 Uninstall

./uninstall.sh

Unregisters from VoiceOS, stops the sync timer, and offers to delete your saved token + state.

---

🔍 How it works

                 ┌───────────────────────────┐
   VoiceOS ──────►  mcp-server.ts (stdio)     ├──► Todoist API v1
   (voice)        └───────────────────────────┘
                 ┌───────────────────────────┐
 Apple Reminders─►  sync (launchd, every 5m)  ├──► Todoist API v1
                 └───────────────────────────┘

• mcp-server.ts — the MCP server VoiceOS launches over stdio (via start.sh).
• sync/sync-reminders-to-todoist.mjs — reads Reminders via JXA, pushes to Todoist.
• register-voiceos.mjs — adds/removes the entry in VoiceOS's config.json.
• Uses the Todoist unified API v1 (/api/v1); the old /rest/v2 is deprecated.

---

🔒 Privacy

Your token is stored locally at ~/.config/todoist/token (chmod 600) and used only to call Todoist's API directly from your Mac. Nothing is proxied through any third party. The Reminders sync reads your local Reminders via macOS scripting and writes only to your Todoist.

---

License

MIT © Gabe Perez