https://github.com/jonathanvanschenck/taskwarrior-telegram-bot
A telegram bot for all your taskwarrior needs
https://github.com/jonathanvanschenck/taskwarrior-telegram-bot
taskwarrior taskwarrior2 taskwarrior3 telegraf telegram
Last synced: about 1 month ago
JSON representation
A telegram bot for all your taskwarrior needs
- Host: GitHub
- URL: https://github.com/jonathanvanschenck/taskwarrior-telegram-bot
- Owner: jonathanvanschenck
- License: isc
- Created: 2026-02-11T17:30:22.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-02-12T06:05:58.000Z (about 2 months ago)
- Last Synced: 2026-02-12T11:32:26.715Z (about 2 months ago)
- Topics: taskwarrior, taskwarrior2, taskwarrior3, telegraf, telegram
- Language: JavaScript
- Homepage:
- Size: 39.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Taskwarrior Telegram Bot
A Telegram bot that provides a chat interface to [Taskwarrior](https://taskwarrior.org/), the command-line task management tool.
[](https://github.com/jonathanvanschenck/taskwarrior-telegram-bot/releases)
[](LICENSE)
## Note from the author
I really just made this for myself, to get push notifications and easy task creation on mobile, but hopefully you will find it useful too!
This bot is still in early development and may have bugs or incomplete features. Use at your own risk, and feel free to contribute or report issues! Additionally, many features are still being worked on, so breaking changes may occur in the future.
Additionally, I primarily use Taskwarrior 3, but I hope to maintain some compatibility with Taskwarrior 2 as well. If you encounter any issues specific to one version, please let me know.
## Features
| Command | Description |
|---|---|
| `/start` | Register with the bot and receive a welcome message |
| `/stop` | Unregister from the bot and stop receiving messages |
| `/help` | Show available commands |
| `/version` | Show bot and Taskwarrior versions |
| `/list [filter]` | List tasks (with optional filter) |
| `/info ` | Show detailed task info |
| `/add ` | Add a new task |
| `/modify ` | Modify an existing task |
| `/annotate ` | Add an annotation to a task |
| `/begin ` | Start a task |
| `/end ` | Stop a task |
| `/done ` | Mark a task as done |
| `/delete ` | Delete a task |
## Setup
### Environment Variables
| Variable | Required | Description |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | Yes | Telegram bot API token |
| `TELEGRAM_CHAT_ID` | No | Restrict bot to a specific chat. This is *highly* suggested, otherwise anyone can edit your tasks |
| `TELEGRAM_USER_ID` | No | Restrict bot to a specific user |
| `DB_DATA` | No | Path to directory for sqlite database, default is `$HOME/.ttb` (you can use ':memory:' to run in RAM, or set to empty string to turn the db off completely) |
| `TW_BIN` | No | Path to `task` binary, default is `task` |
| `TW_TASKRC` | No | Path to `.taskrc`, default is `$HOME/.task` |
| `TW_TASKDATA` | No | Path to task data directory, default is `$HOME/.taskrc` |
| `CRON_DATA` | No | Path to the diretory for the cron files (`*.json`) defualt is `$HOME/.ttb` |
### Telegram Setup
1. Create a new bot using [@BotFather](https://t.me/BotFather) and get the API token.
2. (Highly recommended) Get your user ID using a bot like [@JsonDumpBot](https://t.me/JsonDumpBot).
3. Set your environment variables, including `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and/or `TELEGRAM_USER_ID` to restrict access to the bot.
4. Create a chat with your bot (or use an existing group chat) and send the `/start` command to register with the bot.
### Cron
The bot can run scheduled commands using (Vixie) cron scheduling. To enable this feature, put a `cron.json` (well, any json file, actually) in the `CRON_DATA` directory with the following format:
```js
[
{
"schedule": "*/5 * * * * *", // <- Vixie cron format with seconds field
"command": {
"type": "list", // <- any method of the Taskwarrior class can be used here
"args": ["project:Work +mytag"] // <- array of arguments to pass to the method
}
}
]
```
### Docker
Pre-built images are available on GHCR for both Taskwarrior 2 and 3, on `amd64` and `arm64`:
```bash
# Taskwarrior 2
docker run -d \
-e TELEGRAM_BOT_TOKEN=your-token \
-e TELEGRAM_CHAT_ID=your-chat-id \
-e DB_DATA=/data/ttb \
-e CRON_DATA=/data/ttb \
-e TW_TASKRC=/data/taskrc \
-e TW_TASKDATA=/data/taskdata \
-v /path/to/taskdata:/data/taskdata \
-v /path/to/taskrc:/data/taskrc \
-v /path/to/backup:/data/ttb \
ghcr.io/jonathanvanschenck/taskwarrior-telegram-bot:tw2-latest
# Taskwarrior 3
docker run -d \
-e TELEGRAM_BOT_TOKEN=your-token \
-e TELEGRAM_CHAT_ID=your-chat-id \
-e DB_DATA=/data/ttb \
-e CRON_DATA=/data/ttb \
-e TW_TASKRC=/data/taskrc \
-e TW_TASKDATA=/data/taskdata \
-v /path/to/taskdata:/data/taskdata \
-v /path/to/taskrc:/data/taskrc \
-v /path/to/backup:/data/ttb \
ghcr.io/jonathanvanschenck/taskwarrior-telegram-bot:tw3-latest
```
### Docker Compose
```yaml
services:
bot:
image: ghcr.io/jonathanvanschenck/taskwarrior-telegram-bot:tw3-latest
volumes:
- /path/to/taskdata:/data/taskdata
- /path/to/taskrc:/data/taskrc
- ./cron:/data/ttb # <- put your cron json files in this directory
- ./backup:/data/db # <- this is where the sqlite db will be stored, if you choose to use it
environment:
- CRON_DATA=/data/ttb
- DB_DATA=/data/db
- TW_TASKDATA=/data/taskdata
- TW_TASKRC=/data/taskrc
- TELEGRAM_BOT_TOKEN=your-token
- TELEGRAM_CHAT_ID=your-chat-id
```
## Development
### Local Run
```bash
cp example.env .env # then fill in your bot token
npm install
node index.js
```
### Dev Compose
```bash
# Taskwarrior 2
npm run build:dev:tw2
npm run start:dev:tw2
# Taskwarrior 3
npm run build:dev:tw3
npm run start:dev:tw3
```
## License
[ISC](LICENSE)