Demo

Full video: docs/assets/demo.mp4

Why TaskBot

Small teams already make their decisions in Telegram groups: "can you fix the login bug by Friday?", "I'll take the
release notes". Those messages scroll away and nobody tracks them.

TaskBot sits in the group and turns those messages into real tasks. It picks out the title, type, assignee and due
date with AI, posts a task card you can act on right in the chat, and keeps a Kanban/list board in a Telegram Mini App
in sync with it. Each Telegram group is its own workspace. Nobody needs a new account: Telegram is the login.

Features

In the chat

• /new turns text, a replied-to message, a whole thread (/new all) or the last N messages (/new 10) into one or more tasks
• Interactive task cards: move to the next status, assign, and change status, type or priority from the card
• /sub adds subtasks to a task; /list, /mytasks and /done cover quick daily use
• Undo for tasks created by mistake (10 minutes)
• Forum-topic aware: task events go to a dedicated "Task events" topic (or one you choose with /settopic)
• Interactive /help guide with topic pages

AI assistant

• Extracts tasks from free text, detecting type, assignee and due date, and can split one message into several tasks
• /ai and /update take plain-language requests: reassign, change status or priority, set due dates, explain a task, group tasks into epics, split a task into subtasks, or answer "what's left for me?"
• Understands Vietnamese and English and replies in the user's language
• Pluggable providers: Gemini, OpenAI, or any OpenAI-compatible endpoint (OpenRouter, Groq, vLLM, Ollama, ...)
• Works without an AI key too: /new falls back to creating a basic task

Mini App board

• Kanban board (drag-and-drop between statuses) and a paginated, sortable list view
• Group by status or by assignee; filter by type, assignee or "just mine"
• Task detail page with editable fields, subtasks and progress, source chat messages and an activity timeline
• Epics page with progress, colors, close/reopen
• "Ask AI" chat panel, the same assistant as /ai
• Runs inside Telegram (fullscreen supported) or in a normal browser via the Telegram Login Widget
• Two-way sync: changes in the app update the task card in the group, and the other way round

Integrations (MCP)

• Remote MCP server at /mcp so Claude Code, Cursor and other MCP clients can list, create and update tasks and epics
• ask_taskbot lets your agent talk to TaskBot's AI in plain words; structured tools are there for precise edits
• Per-user access tokens, scoped to one group or all your groups, which you manage from the Mini App
• Agent changes show up in the group as (via Claude Code) / (via Cursor)

Automation

• DM notifications when you're assigned or your task changes status
• Due-date reminders by DM (the day before the task is due, from 9:00 group time)
• Daily group digest at 9:00 in the group's timezone

How it works

flowchart LR
    subgraph Telegram
        G[Group chats & DMs]
        MA[Mini App<br/>React + Vite]
    end

    subgraph Bot["apps/bot (one Node process)"]
        TG[Telegraf bot<br/>commands, cards, callbacks]
        API[Express REST API<br/>/api]
        MCP[MCP server<br/>/mcp]
        JOBS[Bull jobs<br/>reminders, digest]
    end

    AGENTS[Claude Code / Cursor<br/>MCP clients]
    AI[(AI provider<br/>Gemini / OpenAI-compatible)]
    DB[(MongoDB)]
    R[(Redis)]

    G <-- "webhook or polling" --> TG
    MA <-- "initData auth" --> API
    AGENTS <-- "Bearer token" --> MCP
    TG --> AI
    API --> AI
    MCP --> AI
    TG --> DB
    API --> DB
    MCP --> DB
    TG --> R
    JOBS --> R
    JOBS --> DB
    JOBS -- "DMs, digests" --> G

• Multi-tenancy: every query is scoped by groupId (one Telegram group = one workspace).
• Mini App auth: Telegram initData is validated server-side with @telegram-apps/init-data-node (HMAC against the bot token). There is no separate auth system.
• Bidirectional sync: task changes made in the Mini App edit the task card in the group chat, and the other way round.
• Scheduled jobs (Bull): both jobs run hourly and decide per group, in the group's timezone, whether to send.

Command highlights

Full reference: docs/commands.md.

Connect Claude Code / Cursor (MCP)

The bot serves a remote MCP server at /mcp. Send /mcp to the bot in a private chat to get a token, then:

claude mcp add --transport http taskbot <url> --header "Authorization: Bearer <token>"

Now ask your agent things like "create a task to fix login for @an, due Friday" or "what's overdue in Team Alpha?".
Cursor setup, token scopes, the tool reference and limits are in docs/mcp.md.

Tech stack

Get started

You need Node.js ≥ 20, pnpm 10, Docker (for MongoDB and Redis) and a bot token from @BotFather.

git clone https://github.com/tun2g/taskbot.git && cd taskbot
pnpm install
docker compose -f docker-compose.dev.yml up -d   # MongoDB + Redis
cp apps/bot/.env.example apps/bot/.env           # set BOT_TOKEN
cp apps/web/.env.example apps/web/.env
pnpm dev                                         # bot on :3000, Mini App on :5173

Then see the guides below, starting with Getting started and Configuration.

Documentation

Contributing

Contributions are welcome. Bug reports, feature ideas and pull requests all help.

1. Fork the repo and create a branch from main.
2. Make your change, and add or update tests in apps/bot/src/__tests__ where it makes sense.
3. Make sure pnpm check-types and cd apps/bot && pnpm test pass.
4. Commit using Conventional Commits (feat:, fix:, docs:, ...). Run pnpm commit for a guided prompt.
5. Open a pull request describing what changed and why.

License

MIT

Acknowledgements

Built with Telegraf, Telegram Mini Apps SDK,
TanStack, Model Context Protocol and
Turborepo.