This article will cover everything you need to know to use Reclaim's Todoist integration, which automatically syncs items created in Todoist to scheduled Tasks in Reclaim. It's a great way to make sure that you actually get time blocked in your calendar for the things you need to do in Todoist.

Requirements for using the integration

Setting up the integration for the first time

To get started with Todoist, go to Settings -> Integrations in Reclaim. You'll see a list of integrations. Click "Connect Todoist" on the Todoist integration:

Todoist Settings Reclaim

This will prompt you to log into Todoist, and you'll see a screen asking you to give Reclaim a set of permissions. Once you provide those permissions, you'll be automatically redirected back to the integration's settings page in Reclaim.

Note: if you're using Todoist's Google Calendar sync, we recommend disabling it before enabling the integration. If you use both the Reclaim integration and Todoist's own Google Calendar integration, you'll end up with duplicated events.

Integration settings

Once you're on the settings page for the Todoist integration, you'll see a couple of settings to customize how and when Reclaim syncs issues from your items in Todoist.

Todoist Reclaim Settings Page

There are two main settings on this page:

  • Synced projects: this setting tells Reclaim which projects in Todoist should have the integration enabled.

    • Reclaim will automatically display the list of projects associated with your Todoist account, minus the standard onboarding projects (”Welcome”, and “Try Boards”).

  • Item sync preferences: this setting tells Reclaim whether you want to automatically sync items from Todoist, or just sync items that are manually tagged by you.

    • By default, Reclaim will only sync Todoist items from your selected projects which have a due date and the reclaim label applied in Todoist. Items without the reclaim label or due date will not sync to Reclaim. Reclaim will automatically create the reclaim label in your Todoist account if it doesn't already exist.

    • Optionally, you can elect to automatically sync any item in projects that you've enabled the integration on. If you turn this mode on, Reclaim will automatically sync all issues from projects in Todoist where the integration is enabled as long as they include a due date.

How Reclaim tasks display in synced Todoist items

When Reclaim syncs a Todoist item, it adds a comment to the item with a link to the Reclaim task and the date/time for the associated calendar event. As time burns down in Reclaim for that task, the comment text is updated to reflect that progress, as well as to indicate whether the task is at risk based on the due date you have selected in Todoist.

Any item that has been synced as a Task in Reclaim will look like this:

Synced Todoist item Reclaim

How to estimate time for Todoist items in Reclaim

Reclaim will create tasks for Todoist items based on your settings in Reclaim for default task duration. However, you can specify how much time you want to schedule for the task by adding text in either the Todoist item title or description.

Simply indicate the number of minutes, hours, or days enclosed in square brackets, such as [45m] (45 minutes), [2h] (2 hours), [4d] (4 days). The unit of time is case insensitive. If you want to adjust the amount of time after you've created the item, just update the text to reflect the new duration and re-save the Todoist item.

For example, if you wanted to sync a Todoist item called "Get board slides done" for a total duration of 2 hours, you'd write the title as shown below:

Estimate duration Reclaim Todoist item

If you change the duration for a synced Todoist task in Reclaim, it will not update the text of the Todoist item. However, it will update the duration of the task as seen by Reclaim.

How due dates affect synced items from Todoist

Reclaim treats due dates differently from Todoist. Whereas in Todoist, a due date reflects the desire of "I want to do this task on this date," in Reclaim, a due date means "I want to get this task done before this date." Reclaim automatically pulls in due dates from Todoist to defend time on your calendar before the task is due.

Due dates are required for Todoist items to sync, as Reclaim will use it as the due date for the associated task in Reclaim. When you select a due date for an item in Todoist, updates to that due date can be made from either Reclaim or Todoist.

Due dates determine how aggressively Reclaim will defend time for the item from Todoist, with earlier due dates getting defended sooner than later due dates.

Specifying personal vs. work tasks in Todoist

Reclaim can schedule tasks during different time ranges based on your scheduling hours settings. There are two ways to tell Todoist to use your personal vs. working hours for Tasks:

  1. Use the reclaim_personal tag on any item in Todoist (this tag is automatically created for you when you set up the integration)

  2. Use type:personal or type:work in the title of the Todoist item, as shown below.

For example, if you want to create a task for 2 hours to wash the dishes during your personal hours, you'd type the following into the title field of your Todoist item:

Wash the dishes (type:personal) [2h]

Similarly, if you want to create a task to create a slide deck for 4 hours during your work hours, you'd type the following into the title of your Todoist item:

Create slide deck (type:work) [4h]

By default, if no type: is specified, Reclaim will use your working hours.

Specifying "don't schedule before" dates in Todoist

Sometimes you might not want an item to be scheduled on your calendar until a certain date, or want to make sure that Reclaim doesn't schedule a task immediately. To do this in Todoist, simply add notbefore:[date] to your item titles in Todoist.

For example, if you want to schedule time to catch up on email for 45 minutes from Todoist on your calendar no earlier than next Friday, you'd write the following into your item title field:

Catch up on email (notbefore: next Friday) [45m]

Similarly, you can use a hard date in the notbefore: field. For example, if you want to tell Reclaim to not schedule 4 hours for your OKR review before March 31st 2022, you'd write the following into your item title field in Todoist:

OKR review (notbefore: 3/31/2022) [4h]

How Reclaim completes/un-completes Todoist items

Once all the scheduled time for a synced Todoist item has burned down, that task moves to the Completed state in Reclaim. Reclaim won't schedule any more time for the item until you either add time or mark instances for the task as incomplete, but it won't automatically mark the Todoist item as complete until you explicitly mark it as done via Reclaim.

Conversely, if you mark a synced item in Reclaim as Done by checking it off, Reclaim will automatically mark the synced item as complete in Todoist. If there are scheduled events for the item that haven't occurred yet, those future blocks will be automatically removed from your calendar.

If you reopen the Reclaim task, the Todoist item will be automatically un-completed and will show back up in the Todoist project as something to do.

If you mark a Todoist item as complete which has been synced to Reclaim, the associated Reclaim task will be marked as done, and any upcoming time scheduled for that task will be removed from your calendar.

Did this answer your question?