[](https://github.com/iloveitaly/todoist-scheduler/releases) [](https://pepy.tech/project/todoist-scheduler) [](https://pypi.org/project/todoist-scheduler)  [](https://opensource.org/licenses/MIT)
# Todoist Task Scheduler & Filterer
I'm a heavy user of [Todoist](http://mikebian.co/todoist) and I noticed that:
1. If I have [a smaller list of tasks to accomplish](https://mikebian.co/improve-motivation-and-focus-with-small-contexts/), 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](https://mikebian.co/hyper-focus).
## Usage
```text
Usage: todoist-scheduler [OPTIONS]
Organizes todoist tasks based on custom rules
Options:
--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:
```text
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
```json5
[
// 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](https://json5.org) so you can add comments.
You can also override options for specific entries and reference saved/named filters:
```json5
[
// 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](/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:
```shell
LOG_LEVEL=DEBUG todoist-scheduler
```
Play with the Todoist API (in `ipython`):
```python
from todoist_api_python.api import TodoistAPI
import os
api = TodoistAPI(os.getenv("TODOIST_API_KEY"))
```
Note that `ipython` is not included in the repo, [I install all my debugging tools via this alias](https://github.com/iloveitaly/dotfiles/blob/e41a309b0ca1f5099bc6d902d0956ba0fc997db1/.aliases#L76-L77) instead of including them in the poetry config.
Raw data
{
"_id": null,
"home_page": "https://github.com/iloveitaly/todoist-scheduler",
"name": "todoist-scheduler",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "todoist, scheduler, task, management",
"author": "Michael Bianco",
"author_email": "mike@mikebian.co",
"download_url": "https://files.pythonhosted.org/packages/f9/04/4df9d6c9c3d81042f4a36237e11c5a6d1ff358a2322b5624171bff9d82c2/todoist_scheduler-0.6.0.tar.gz",
"platform": null,
"description": "[](https://github.com/iloveitaly/todoist-scheduler/releases) [](https://pepy.tech/project/todoist-scheduler) [](https://pypi.org/project/todoist-scheduler)  [](https://opensource.org/licenses/MIT)\n\n# Todoist Task Scheduler & Filterer\n\nI'm a heavy user of [Todoist](http://mikebian.co/todoist) and I noticed that:\n\n1. If I have [a smaller list of tasks to accomplish](https://mikebian.co/improve-motivation-and-focus-with-small-contexts/), I get through them faster.\n2. Having a large list of tasks creates 'cognitive drag' and stresses me out\n3. It takes time to look through and review long list of tasks\n\nThis 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.\n\nThis 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](https://mikebian.co/hyper-focus).\n\n## Usage\n\n```text\nUsage: todoist-scheduler [OPTIONS]\n\n Organizes todoist tasks based on custom rules\n\nOptions:\n --task-limit INTEGER Total task limit for the day [default: 20]\n --default-filter TEXT Default todoist filter [default: (today | overdue) &\n !assigned to:others & !recurring]\n --filter-json TEXT Default filter file [default: filters.json]\n --punt-time TEXT How far to punt a task into the future. Use todoist\n natural language format. The special value 'jitter'\n will generate a random date. [default: in 2 days]\n --jitter-days INTEGER What day range to jitter tasks across when\n rescheduling them [default: 14]\n --dry-run Dry run the task updates\n --api-key TEXT API key. Sourced from TODOIST_API_KEY as well\n --help Show this message and exit.\n```\n\nTake a closer look at the default filter:\n\n```text\ndefault: (today | overdue) & !assigned to:others & !recurring\n```\n\nHere's what this does:\n\n* Only applies filters to task that are assigned to you\n* Ignores recurring tasks\n* Looks at tasks due on or before today\n\n#### filters.json schema\n\n```json5\n[\n // limit defines the number of tasks you think you can complete today\n { \"filter\": \"@writing\", \"limit\": 2 },\n { \"filter\": \"@research\", \"limit\": 3 },\n\n // the filter text uses the todoist search syntax\n { \"filter\": \"#House\", \"limit\": 3 },\n]\n```\n\nThe JSON file is loaded in as [JSON5](https://json5.org) so you can add comments.\n\nYou can also override options for specific entries and reference saved/named filters:\n\n```json5\n[\n // loosen the priority filter\n { \"filter\": \"@writing\", \"limit\": 2, \"priority\": 2 },\n\n // reference a saved filter\n { \"filter\": \"Communication\", \"limit\": 3 },\n]\n```\n\n### Docker\n\nEasiest way to use this is using the pre-built docker image. Here's an example [docker-compose.yml](/docker-compose.yml). This uses the `main.py` as a cron-like entrypoint to run this script on a schedule.\n\n## Development\n\nRun with debug logging:\n\n```shell\nLOG_LEVEL=DEBUG todoist-scheduler\n```\n\nPlay with the Todoist API (in `ipython`):\n\n```python\nfrom todoist_api_python.api import TodoistAPI\nimport os\napi = TodoistAPI(os.getenv(\"TODOIST_API_KEY\"))\n```\n\nNote that `ipython` is not included in the repo, [I install all my debugging tools via this alias](https://github.com/iloveitaly/dotfiles/blob/e41a309b0ca1f5099bc6d902d0956ba0fc997db1/.aliases#L76-L77) instead of including them in the poetry config.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically reschedule tasks in Todoist to reduce the size of the todo lists you see each day.",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/iloveitaly/todoist-scheduler"
},
"split_keywords": [
"todoist",
" scheduler",
" task",
" management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02f62198c447bec570c8fdf6ca0ab42283afc43bb3eda6357a9a04f894f12ba6",
"md5": "aa3b0f0418e53b674a7c465d5c22b2c2",
"sha256": "294a689b1016831271082f70038ec1a7bdc8265c3bc26b39d62d4007ce951d29"
},
"downloads": -1,
"filename": "todoist_scheduler-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa3b0f0418e53b674a7c465d5c22b2c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 11941,
"upload_time": "2024-08-17T12:34:37",
"upload_time_iso_8601": "2024-08-17T12:34:37.201936Z",
"url": "https://files.pythonhosted.org/packages/02/f6/2198c447bec570c8fdf6ca0ab42283afc43bb3eda6357a9a04f894f12ba6/todoist_scheduler-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9044df9d6c9c3d81042f4a36237e11c5a6d1ff358a2322b5624171bff9d82c2",
"md5": "f701c3e99c5b6af6aac20538b5cbf114",
"sha256": "93a71f9992fdb39b52191a29075e4b4a535d881dc3c63252d6bd53b3d1d5f7cd"
},
"downloads": -1,
"filename": "todoist_scheduler-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "f701c3e99c5b6af6aac20538b5cbf114",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 11000,
"upload_time": "2024-08-17T12:34:38",
"upload_time_iso_8601": "2024-08-17T12:34:38.732302Z",
"url": "https://files.pythonhosted.org/packages/f9/04/4df9d6c9c3d81042f4a36237e11c5a6d1ff358a2322b5624171bff9d82c2/todoist_scheduler-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-17 12:34:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iloveitaly",
"github_project": "todoist-scheduler",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "todoist-scheduler"
}
JSON
