Todoist Task Scheduler & Filterer

I'm a heavy user of Todoist and I noticed that:

1. If I have a smaller list of tasks to accomplish, I get through them faster.
2. Having a large list of tasks creates 'cognitive drag' and stresses me out
3. It takes time to look through and review long list of tasks

This tool enables you to set up rules to automatically punt tasks that don't need to get done today. This reduces the size of your todoist lists and tricks your monkey mind into getting more done. The ultimate goal for me is to get to 'inbox zero' on todoist.

This tool has helped in a big way, acting as a 'virtual assistant' in a way: automatically determining what I shouldn't see for the day. I tie this into a 'first awake' script executed by hyper focus.

Installation

uv tool install todoist-scheduler

Or add as a dependency:

uv add todoist-scheduler

Usage

Usage: todoist-scheduler [OPTIONS]

  Organizes todoist tasks based on custom rules

Options:
  -V, --version          Show the version and exit.
  --task-limit INTEGER   Total task limit for the day  [default: 20]
  --default-filter TEXT  Default todoist filter  [default: (today | overdue) &
                         !assigned to:others & !recurring]
  --filter-json TEXT     Default filter file  [default: filters.json]
  --punt-time TEXT       How far to punt a task into the future. Use todoist
                         natural language format. The special value 'jitter'
                         will generate a random date.  [default: in 2 days]
  --jitter-days INTEGER  What day range to jitter tasks across when
                         rescheduling them  [default: 14]
  --dry-run              Dry run the task updates
  --api-key TEXT         API key. Sourced from TODOIST_API_KEY as well
  --help                 Show this message and exit.

Take a closer look at the default filter:

default: (today | overdue) & !assigned to:others & !recurring

Here's what this does:

• Only applies filters to task that are assigned to you
• Ignores recurring tasks
• Looks at tasks due on or before today

filters.json schema

[
  // limit defines the number of tasks you think you can complete today
  { "filter": "@writing", "limit": 2 },
  { "filter": "@research", "limit": 3 },

  // the filter text uses the todoist search syntax
  { "filter": "#House", "limit": 3 },
]

The JSON file is loaded in as JSON5 so you can add comments.

You can also override options for specific entries and reference saved/named filters:

[
  // loosen the priority filter
  { "filter": "@writing", "limit": 2, "priority": 2 },

  // reference a saved filter
  { "filter": "Communication", "limit": 3 },
]

Docker

Easiest way to use this is using the pre-built docker image. Here's an example docker-compose.yml. This uses the main.py as a cron-like entrypoint to run this script on a schedule.

Development

Run with debug logging:

LOG_LEVEL=DEBUG todoist-scheduler

Play with the Todoist API (in ipython):

from todoist_api_python.api import TodoistAPI
import os

api = TodoistAPI(os.getenv("TODOIST_API_KEY"))

This project was created from iloveitaly/python-package-template