Task Discord Bot

A Discord bot for task management with a pluggable backend architecture. Supports Todoist and Tududi as task backends.

Features

• Quick Task Creation: Simply post a message in an allowed channel to automatically create a task. A ✅ reaction confirms success.
• Create Task: /task create <task_name>
• List Tasks: /task list [project]
• Today's Tasks: /task today
• Complete Task: /task complete <index>
• Delete Task: /task delete <index>
• List Projects: /task projects
• Create Project: /task project-create <project_name>
• Move to Project: /task move-to-project <index> <project>
• Move to Inbox: /task move-to-inbox <index>
• Add Tags: /task tag-add <index> <tags>
• Ignore Project: /task ignore_project <project>
• Unignore Project: /task unignore_project <project>
• List Ignored Projects: /task ignored_projects

Architecture

main.py                  # Discord bot logic (backend-agnostic)
backends/
├── __init__.py           # create_backend() factory
├── base.py               # TaskBackend ABC + TaskItem/ProjectItem/TagItem dataclasses
├── todoist_backend.py    # TodoistBackend implementation
└── tududi_backend.py    # TududiBackend implementation (REST API)

The TaskBackend abstract base class defines the interface that all task backends must implement. main.py interacts only with the TaskBackend interface, never with backend-specific APIs directly.

Prerequisites

• Python 3.13+
• uv (Package Manager)

Setup

1. Clone the repository

   git clone <repository-url>
   cd task_discord_bot
   

2. Install dependencies

   uv sync
   

3. Configuration

   Create a .env file in the root directory and add the following variables:

   Using Todoist (default)

   # Discord Configuration
   DISCORD_TOKEN=your_discord_bot_token
   GUILD_ID=your_discord_server_id  # Optional: For instant command sync
   
   # Backend Selection
   TASK_BACKEND=todoist
   
   # Todoist Configuration
   TODOIST_API_TOKEN=your_todoist_api_token
   

   Todoist API Token: Get your API Token from Todoist Settings > Integrations > Developer.

   Using Tududi

   # Discord Configuration
   DISCORD_TOKEN=your_discord_bot_token
   GUILD_ID=your_discord_server_id  # Optional: For instant command sync
   
   # Backend Selection
   TASK_BACKEND=tududi
   
   # Tududi Configuration
   TUDUDI_URL=http://localhost:3002
   TUDUDI_API_TOKEN=your_tududi_api_token
   

   Tududi API Token: Generate an API token from Tududi Settings > API Tokens.

   Optional Configuration (works with either backend):

   ALLOWED_CHANNEL_IDS=channel_id_1,channel_id_2  # Comma-separated channel IDs
   ALLOWED_ROLE_IDS=role_id_1,role_id_2            # Comma-separated role IDs
   

   Ignored Projects:

   • A file named ignored_projects.json will be automatically created when you use the /task ignore_project command.

Tududi Limitations

• Tag creation: The /task tag-add command will show an error if a new tag needs to be created. Tududi auto-creates tags when they are attached to tasks, but does not have a standalone tag creation API.

Usage

Run the bot using the following command:

uv run main.py

Once the bot is online, use the /task help command in your Discord server to see available commands.

Systemd Service

To run the bot as a system service using systemd, follow these steps.

1. Create the service file

   Create a file at /etc/systemd/system/task-discord-bot.service:

   [Unit]
   Description=Task Discord Bot
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=your_username
   WorkingDirectory=/path/to/task_discord_bot
   ExecStart=/usr/local/bin/uv run main.py
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   Replace your_username with your actual username and /path/to/task_discord_bot with the actual path to the bot directory.

2. Enable and start the service

   sudo systemctl enable task-discord-bot
   sudo systemctl start task-discord-bot
   

3. Manage the service

   • Restart the service:

   sudo systemctl restart task-discord-bot
   

   • Stop the service:

   sudo systemctl stop task-discord-bot
   

   • Check service status:

   sudo systemctl status task-discord-bot
   

4. View logs

   To view the service logs:

   sudo journalctl -u task-discord-bot -f
   

   Use -f to follow the logs in real-time, or omit it to view recent logs.

Adding a New Backend

1. Create a new file backends/<name>_backend.py
2. Implement the TaskBackend ABC from backends/base.py
3. Add the backend type to create_backend() in backends/__init__.py
4. Add required environment variables to .env
5. Update README.md and AGENTS.md

Dependencies

• discord.py>=2.3.0 - Discord API wrapper
• python-dotenv>=1.0.0 - Environment variable loader
• todoist-api-python>=3.2.1 - Todoist API client (for Todoist backend)
• httpx>=0.27.0 - Async HTTP client (for Tududi backend)