Sync Todoist

Sync Todoist keeps Obsidian Markdown tasks and Todoist tasks in sync, while preserving local notes, nested outlines, project metadata, labels, query blocks, and Daily Note planning.

Language: English · 简体中文

Sync Todoist is currently recommended through BRAT while community-plugin submission is being prepared.

What's New in 0.6.1

• Cleans up Community Plugin review issues for Obsidian minAppVersion, bundled built-in modules, and typed settings persistence.
• Adds a Daily Note sub-option for completed recurring tasks.
• Keeps completed recurring occurrences in today's Daily Note when Include completed tasks is enabled.
• Uses Todoist activity logs to recover the completed occurrence because Todoist moves recurring tasks to their next due date after completion.
• Clarifies Daily Note flat rendering, completed-task behavior, and Query Block completed-task date windows in the documentation.

Why Use It?

• 📝 Write tasks where you think - add #todoist to an Obsidian checkbox and it becomes a Todoist task.
• 🔁 Sync both ways - completion, title, due date, priority, labels, and project changes flow between Obsidian and Todoist.
• 🌳 Keep nested work intact - indented Markdown child tasks become Todoist subtasks.
• 📥 Bring Todoist back into notes - import existing Todoist tasks, including subtasks, at the cursor.
• 🔎 Render live Todoist views - use sync-todoist query blocks for filtered task lists.
• 📅 Plan from Daily Notes - write today's Todoist tasks into a managed Daily Note marker region.
• 📱 Work on desktop and mobile - HTTP calls use Obsidian's requestUrl() API, not a Node-only SDK.

Installation

BRAT (recommended)

Use BRAT while Sync Todoist is pending review for the Obsidian Community Plugins directory.

1. Open Settings -> Community plugins.
2. Install and enable BRAT.
3. Run BRAT: Add a beta plugin for testing.
4. Enter https://github.com/o1xhack/obsidian-sync-todoist.
5. Enable Sync Todoist and configure your Todoist API token.

Pending: Community Plugins

Sync Todoist is not yet listed in the Obsidian Community Plugins directory. After approval, install it from Settings -> Community plugins -> Browse.

Manual Release

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create .obsidian/plugins/sync-todoist/ in your vault.
3. Put the three files in that folder.
4. Restart Obsidian and enable Sync Todoist.

Build from Source

git clone https://github.com/o1xhack/obsidian-sync-todoist.git
cd obsidian-sync-todoist
npm install
npm run build

Then copy main.js, manifest.json, and styles.css into .obsidian/plugins/sync-todoist/.

Quick Start

1. Get your Todoist API token from Todoist Settings -> Integrations -> Developer.
2. Open Settings -> Community plugins -> Sync Todoist.
3. Paste the token and click Verify.
4. Add #todoist to a Markdown checkbox.
5. Run Sync Todoist: Sync now.

- [ ] Buy groceries #todoist

After sync, Sync Todoist stores the Todoist task ID in an HTML comment:

- [ ] Buy groceries #todoist <!-- todoist-id:8765432109 -->

Sync Format

Sync Todoist reads and writes plain Markdown task lines. The todoist-id comment is the stable link between an Obsidian line and a Todoist task.

Subtasks

Indented Markdown tasks under a synced parent become Todoist subtasks. Child lines do not need #todoist; they inherit sync from the parent outline.

- [ ] Plan launch #todoist 📁 Work #marketing 📅 2026-06-01
  - [ ] Draft announcement
  - [ ] Review screenshots
  - [ ] Publish release notes

How inheritance works:

• The parent task carries the sync tag.
• Child tasks are created with Todoist parentId.
• Child tasks inherit the Todoist project from the parent when they are created.
• Child task content, completion, due date, priority, and labels remain their own fields after sync.

Projects and Labels

• Use 📁 ProjectName to route a task to a Todoist project.
• If no project is written, new tasks use the configured default project or Inbox.
• Hashtags other than the sync tag become Todoist labels.
• Todoist project moves and label changes sync back to Obsidian when conflict handling allows Todoist to win.

Query Blocks

Embed a live Todoist task list in any note:

```sync-todoist
filter: today | overdue
```

Query blocks use Todoist filter syntax, render checkboxes, include a refresh button, and show the last updated time. The original syncist code block language is still accepted as a migration alias.

Completed Tasks in Query Blocks

include_completed adds a second completed-task lookup and merges those results with the active tasks returned by filter. It does not automatically mean "completed today."

If completed_by is omitted, Sync Todoist infers a default:

• Date-oriented filters such as today, overdue, or due before... default to due_date.
• Label or project filters such as @writing or #Work default to completion_date.

Examples:

```sync-todoist
filter: today
include_completed: true
completed_by: due_date
completed_range: today
```

Shows active tasks due today and completed tasks whose due date is today.

```sync-todoist
filter: @writing
include_completed: true
completed_by: completion_date
completed_range: today
```

Shows active @writing tasks and @writing tasks completed today.

Daily Notes

Sync Todoist can write today's matching Todoist tasks into today's Obsidian Daily Note. Enable Obsidian's core Daily notes plugin first, then open Settings -> Sync Todoist -> Daily Note.

Daily Note controls:

• Enable or disable Daily Note sync.
• Customize the source-mode start and end markers.
• Choose task filters by project, label, and priority.
• Choose primary sorting: time first or priority first.
• Include tasks completed today.
• Include completed recurring occurrences when completed tasks are enabled.
• Run a manual Sync today refresh.

Default marker block:

%% sync-todoist:daily:start %%
- [ ] Review launch tasks #todoist 📁 Work 🔺 📅 2026-05-13 <!-- todoist-id:123456 -->
%% sync-todoist:daily:end %%

Important behavior:

• Sync Todoist fully rewrites everything between the markers during sync.
• Do not manually edit inside the marker region unless you are ready for those edits to be overwritten.
• Daily Note output is a flat list. It does not expand Todoist parent tasks into nested child outlines.
• If a Todoist subtask independently matches the Daily Note filters, it can appear as its own top-level row.
• Daily Note rows copy each task's own content, completion state, due date, priority, labels, and project display.
• Regular Markdown inheritance for subtasks is not applied inside the Daily Note generated block.

Completed and recurring behavior:

• Active tasks are included when their current Todoist due date falls today.
• Timed due dates and current recurring occurrences are treated as today when their local date is today.
• With Include completed tasks, regular tasks completed today remain checked in the Daily Note block.
• With Include completed recurring tasks, Sync Todoist also checks today's activity log and keeps recurring tasks completed today as checked rows.
• Todoist moves recurring tasks to the next occurrence after completion, so the activity-log fallback is required to preserve today's completed occurrence.

Settings

Commands

Development

npm install
npm run lint
npm run build
npx tsc --noEmit
npm test

Use test/TEST_SPEC_v2.0.0.md for manual QA against a test vault and Todoist account.

Release tags must exactly match manifest.json version, and every public release must attach main.js, manifest.json, and styles.css. See RELEASE.md.

FAQ

Why is the repository named obsidian-sync-todoist but the plugin ID is sync-todoist?

The GitHub repository keeps the descriptive Obsidian-focused name. The Obsidian plugin ID is sync-todoist because Obsidian plugin IDs must not include obsidian.

Where is my Todoist API token stored?

It is stored locally in Obsidian's plugin data file for your vault. The runtime data.json file is intentionally gitignored.

Does this use a third-party Todoist SDK?

No. Sync Todoist talks directly to Todoist API v1 through Obsidian's requestUrl() API for desktop and mobile compatibility.

Contributing

Issues and PRs are welcome. Before opening a PR, run:

npm run lint
npm run build
npx tsc --noEmit
npm test

For behavior changes, also walk through the relevant sections of test/TEST_SPEC_v2.0.0.md.

Acknowledgements

Sync Todoist is based on Syncist by Bastiaan Schönhage, used under the MIT License. This repository keeps the upstream history, copyright notice, and license text intact while adding the independent Sync Todoist release line, sync-todoist plugin ID, subtasks, import, projects, labels, query blocks, Daily Notes, and completed-task support.

License

MIT - see LICENSE.