# Todoist for VoiceOS

> Voice-control [Todoist](https://todoist.com) from [VoiceOS](https://voiceos.com) — and optionally keep Apple Reminders in sync with it.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Platform: macOS](https://img.shields.io/badge/platform-macOS-black.svg)](#requirements)
[![Todoist API v1](https://img.shields.io/badge/Todoist-API%20v1-e44332.svg)](https://developer.todoist.com/)

A local [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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](https://github.com/gabeperez/voiceos-todoist/releases/latest),
> unzip, and run `./setup.sh`.

---

## 📋 Requirements

| | |
|---|---|
| **OS** | macOS with [VoiceOS](https://voiceos.com) installed |
| **Runtime** | [Node.js](https://nodejs.org) 18+ (setup checks for it) |
| **Account** | A [Todoist](https://todoist.com) 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.

```bash
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

```bash
./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](./LICENSE) © Gabe Perez