{"id":30895697,"url":"https://github.com/ilyasyoy/tasks-assistant-telegram-bot","last_synced_at":"2025-09-08T22:09:57.051Z","repository":{"id":312604546,"uuid":"1040397828","full_name":"IlyasYOY/tasks-assistant-telegram-bot","owner":"IlyasYOY","description":"A small Telegram bot that lets you manage a personal task list with the help of an LLM (OpenAI‑compatible API).  You type a plain‑text message, the bot sends the current list + your new input to the model, receives an updated list and stores it.","archived":false,"fork":false,"pushed_at":"2025-08-31T19:30:05.000Z","size":76,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T21:24:45.638Z","etag":null,"topics":["golang","telegram","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IlyasYOY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-18T23:19:38.000Z","updated_at":"2025-08-31T19:30:09.000Z","dependencies_parsed_at":"2025-08-31T21:25:08.913Z","dependency_job_id":"6450f50a-0be2-4f93-ae66-0655a194c5f4","html_url":"https://github.com/IlyasYOY/tasks-assistant-telegram-bot","commit_stats":null,"previous_names":["ilyasyoy/tasks-assistant-telegram-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/IlyasYOY/tasks-assistant-telegram-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IlyasYOY%2Ftasks-assistant-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IlyasYOY%2Ftasks-assistant-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IlyasYOY%2Ftasks-assistant-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IlyasYOY%2Ftasks-assistant-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IlyasYOY","download_url":"https://codeload.github.com/IlyasYOY/tasks-assistant-telegram-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IlyasYOY%2Ftasks-assistant-telegram-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231520,"owners_count":25245659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","telegram","vibe-coding"],"created_at":"2025-09-08T22:09:54.483Z","updated_at":"2025-09-08T22:09:57.041Z","avatar_url":"https://github.com/IlyasYOY.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tasks Assistant Telegram Bot  \n\n\u003e [!important] Disclaimer!\n\u003e A purely vibecoded project – it’s shared for fun and is **not** intended to\n\u003e be maintained or supported.\n\nA small Telegram bot that lets you manage a personal task list with the help of\nan LLM (OpenAI‑compatible API).  You type a plain‑text message, the bot sends\nthe current list + your new input to the model, receives an updated list and\nstores it.  \n\n## Table of Contents  \n\n1. [Overview](#overview)  \n2. [Features](#features)  \n3. [Prerequisites](#prerequisites)  \n4. [Installation \u0026 Building](#installation--building)  \n5. [Configuration](#configuration)  \n6. [Running the Bot](#running-the-bot)  \n7. [Commands \u0026 Usage](#commands--usage)  \n8. [Database \u0026 Migrations](#database--migrations)  \n9. [Logging \u0026 Graceful Shutdown](#logging--graceful-shutdown)  \n10. [Troubleshooting](#troubleshooting)  \n11. [License](#license)  \n\n## Overview  \n\nThe **Tasks Assistant** bot is a thin wrapper around the Telegram Bot API and\nan OpenAI‑compatible chat model.  \n\n* **Stateless UI** – Users interact only via plain text messages.  \n* **LLM‑driven** – The bot builds a prompt that contains the previous task list\n  (if any) and the new user input, sends it to the model, and stores the\n  model’s response as the new list.  \n* **SQLite persistence** – The full task list is stored per‑user in a tiny\n  SQLite database, making the bot portable and easy to run locally.  \n\n## Features  \n\n| ✅ | Feature |\n|---|---------|\n| ✅ | `/start` – friendly greeting |\n| ✅ | `/help` – usage information |\n| ✅ | Plain‑text messages → new task (LLM‑generated list) |\n| ✅ | Per‑user task storage in SQLite |\n| ✅ | Configurable allowed user IDs (whitelisting) |\n| ✅ | Graceful shutdown on SIGINT / SIGTERM |\n| ✅ | Automatic database migrations with **goose** |\n| ✅ | OpenAI‑compatible client (custom base URL, API key, model) |\n| ✅ | Unknown command handling (`❓ I don't understand…`) |\n| ✅ | Simple, testable code – each handler implements a small interface |\n\n## Prerequisites  \n\n* **Go** ≥ .22 (module aware)  \n* **SQLite driver** – already vendored via `modernc.org/sqlite` (no external binary needed)  \n* **OpenAI‑compatible API** – endpoint, key and model name (e.g., `gpt-4o-mini`)  \n\n## Installation \u0026 Building  \n\nYou can either install the binary directly from the repository or build it locally.\n\n```bash\n# Install the latest released version (go will download, compile and place the binary in $GOPATH/bin)\ngo install github.com/IlyasYOY/tasks-assistant-tg-bot@latest\n```\n\nOr clone and build:\n\n```bash\ngit clone https://github.com/IlyasYOY/tasks-assistant-tg-bot.git\ncd tasks-assistant-tg-bot\ngo build -o tasks-assistant ./cmd/bot\n```\n\nThe resulting executable (`tasks-assistant` or `tasks-assistant.exe`) is ready\nto run.\n\n## Configuration  \n\nAll configuration is driven by environment variables.  \nCreate a `.env` file (or export variables in your shell) with the following keys:\n\n| Variable | Description | Required? |\n|----------|-------------|-----------|\n| `TASKS_ASSISTANT_TG_BOT_TELEGRAM_TOKEN` | Bot token obtained from BotFather | **Yes** |\n| `TASKS_ASSISTANT_TG_BOT_OPEN_API_BASE_PATH` | Base URL of the OpenAI‑compatible API (e.g., `https://api.openai.com/v1`) | No (defaults to OpenAI public endpoint) |\n| `TASKS_ASSISTANT_TG_BOT_OPEN_API_API_KEY` | API key for the LLM service | **Yes** |\n| `TASKS_ASSISTANT_TG_BOT_OPEN_API_MODEL` | Model name to use (e.g., `gpt-4o-mini`) | **Yes** |\n| `TASKS_ASSISTANT_TG_BOT_ALLOWED_USER_IDS` | Comma‑separated list of Telegram user IDs allowed to talk to the bot. If empty, **all** users are accepted. | No |\n| `TASKS_ASSISTANT_TG_BOT_SQL_DSN` | SQLite DSN. `file::memory:?cache=shared` is used by default (in‑memory DB). Provide a file path for persistent storage, e.g., `tasks.db`. | No |\n\nExample `.env`:\n\n```dotenv\nTASKS_ASSISTANT_TG_BOT_TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\nTASKS_ASSISTANT_TG_BOT_OPEN_API_BASE_PATH=https://api.openai.com/v1\nTASKS_ASSISTANT_TG_BOT_OPEN_API_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX\nTASKS_ASSISTANT_TG_BOT_OPEN_API_MODEL=gpt-4o-mini\nTASKS_ASSISTANT_TG_BOT_ALLOWED_USER_IDS=123456789,987654321\nTASKS_ASSISTANT_TG_BOT_SQL_DSN=./tasks.db\n```\n\nLoad the file before running:\n\n```bash\nexport $(grep -v '^#' .env | xargs)\n```\n\n---  \n\n## Running the Bot  \n\n```bash\n# If you installed via `go install`\ntasks-assistant\n\n# Or run the binary you built\n./tasks-assistant\n```\n\nThe bot will:\n\n1. Load configuration.  \n2. Open (or create) the SQLite DB.  \n3. Apply any pending migrations (`goose up`).  \n4. Start long‑polling Telegram for updates.  \n5. Gracefully shut down on `SIGINT`/`SIGTERM`.  \n\nYou should see log output similar to:\n\n```\n2025/08/18 12:34:56 Bot authorized as MyTasksBot\n2025/08/18 12:34:56 Database migrations applied successfully\n2025/08/18 12:34:56 Listening for updates…\n```\n\n---  \n\n## Commands \u0026 Usage  \n\n| Command | Description |\n|---------|-------------|\n| `/start` | Greets the user and explains the bot’s purpose. |\n| `/help`  | Shows a short usage guide (the same text you’re reading now). |\n| *plain text* | Anything that is **not** a slash command is treated as a new task. The bot will: \u003cbr\u003e1️⃣ Append the message to the existing list (if any) \u003cbr\u003e2️⃣ Send the combined prompt to the LLM \u003cbr\u003e3️⃣ Store the model’s response as the new list \u003cbr\u003e4️⃣ Reply with the updated list. |\n| Unknown command (e.g., `/foo`) | Bot replies with a friendly “I don’t understand” message. |\n\n**Sample interaction**\n\n```\nUser: /start\nBot: 👋 Hello! I'm *Tasks Assistant* – I can help you manage your tasks using AI.\n     Just send me any text and I’ll treat it as a new task. I’ll always reply with the current task list.\n\nUser: Buy milk\nBot: # Tasks\n\n1. Buy milk\n\nUser: Call about the project\nBot: # Tasks\n\n1. Buy milk\n2. Call Alice about the project\n```\n\n(The exact formatting depends on the LLM’s response.)\n\n## Database \u0026 Migrations  \n\n* **Schema** – `user_tasks` table (`user_id INTEGER PRIMARY KEY, tasks TEXT`).  \n* **Migrations** – Stored in `internal/store/migrations`. The bot runs `store.Migrate(db, \"./internal/store/migrations\")` on start, so you never need to invoke Goose manually.  \n* **Persistence** – By default the bot uses an in‑memory DB (lost on restart). Set `TASKS_ASSISTANT_TG_BOT_SQL_DSN` to a file path (e.g., `tasks.db`) for durable storage.  \n\n## Logging \u0026 Graceful Shutdown  \n\n* All errors are logged with context (`log.Printf`).  \n* The bot runs a dedicated goroutine that processes updates; any handler error is logged but does not crash the process.  \n* On `SIGINT`/`SIGTERM` the main routine stops receiving updates, closes the DB and exits cleanly.  \n\n## Troubleshooting  \n\n| Symptom | Likely Cause | Fix |\n|---------|--------------|-----|\n| Bot does not start, “missing Telegram token” | `TASKS_ASSISTANT_TG_BOT_TELEGRAM_TOKEN` not set or empty | Export the variable or add it to `.env`. |\n| “AI request failed” messages | Invalid API key, wrong base URL, or model name | Verify `OPEN_API_KEY`, `OPEN_API_BASE_PATH`, `OPEN_API_MODEL`. |\n| No tasks are persisted after restart | Using the default in‑memory DSN | Set `TASKS_ASSISTANT_TG_BOT_SQL_DSN` to a file path. |\n| Bot replies “I don’t understand …” for a command you added | Command not registered in `handler.New` | Add the new handler to the `cmdMap` when constructing the `Handler`. |\n| “unauthorized user” errors | `AllowedUserIDs` does not contain your Telegram user ID | Add your ID to `TASKS_ASSISTANT_TG_BOT_ALLOWED_USER_IDS` or leave the variable empty to allow everyone. |\n\n## License  \n\nMIT License – see the `LICENSE` file in the repository.  \n\n---  \n\n*Happy task‑keeping!*  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filyasyoy%2Ftasks-assistant-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filyasyoy%2Ftasks-assistant-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filyasyoy%2Ftasks-assistant-telegram-bot/lists"}