Long-running Telegram bot that forwards messages to a Cursor SDK local agent. Each allowed user can drive coding tasks against a target git repository on the same machine.
No public webhook — the bot uses Telegram long polling.
- Python 3.11+
- A Cursor account with an API key
- A Telegram bot token from @BotFather
git clone https://github.com/starline/CursorTgBot.git
cd your-project # repo the agent should edit
/path/to/CursorTgBot/run.shOn first start the script creates a venv, copies .env, and asks only for:
- Telegram bot token
- Cursor API key
- Repo path (default: the directory you launched from)
Everything else has defaults (CURSOR_MODEL=auto, BOT_DATA_DIR=./data, forum mode off).
Then open a DM with the bot and send any message — the first user is allowlisted automatically (id written to .env). Restart is not required.
Keep the process running (tmux, systemd, …). The agent needs network access to Cursor and write access to the target repo.
| Variable | Default | When to set |
|---|---|---|
REPO_CWD |
launch directory | Bot lives elsewhere / you always start from the bot folder |
ALLOWED_USER_IDS |
first DM auto-claims | Lock to specific users up front |
ALLOWED_CHAT_IDS |
any chat | Restrict to a group |
FORUM_MODE / FORUM_CHAT_ID |
off | One Telegram topic per /task |
CURSOR_MODEL |
auto |
Pin a model id |
BOT_DATA_DIR |
./data |
Custom session DB path |
In a group, send /info to get the chat id for ALLOWED_CHAT_IDS / FORUM_CHAT_ID.
Same launch and the same repo as the Telegram bot. Telegram token is not required.
tgBottgBot is on PATH (~/.local/bin). It uses the directory you launched from. The session is kept across restarts. /new drops it. --workspace PATH picks another directory.
tgBot -p "fix the failing test" # one shot, then exit
tgBot --new # start a fresh sessionType a task the way you would message the bot. The Старт button at the bottom (or F2, or /start) launches the Telegram bot. Стоп / F3 / /stop stops it. /settings edits the token, API key, repository, model, and autostart.
./run.sh is still the Telegram bot. The CLI does not poll Telegram.
- Start a chat with your bot.
- Send
/task <what you want done>to start an agent run. - Use
/ask <follow-up>(or plain text) for follow-ups in the same session.
Enable with FORUM_MODE=1 and set FORUM_CHAT_ID (or a single ALLOWED_CHAT_IDS entry). The bot must be a group admin with permission to manage topics.
| Action | Behaviour |
|---|---|
/task … |
Creates a new forum topic (name = start of the prompt) and runs the agent there |
Text or /ask … inside a topic |
Follow-up on that topic’s agent session |
| Text in General | Ignored (use /task) |
Session key = (chat_id, thread_id) → one Cursor agent session per topic.
| Command | Action |
|---|---|
/task <text> |
New task (new topic if forum mode is on) |
/ask <text> |
Follow-up in the current topic/chat |
/backlog |
Active backlog tasks (proposed / ready / doing) from REPO_CWD |
/backlog deferred |
Deferred backlog tasks |
/info |
Chat/group id, forum flags, thread id |
/status |
Idle / running / queue |
/cancel |
Cancel the current run |
/diff |
git status + git diff --stat in REPO_CWD |
/model |
Show the model. /model <id> saves it and uses it on the next run |
/new |
Drop the agent session for this topic/chat |
Photos, files, and voice notes are saved and passed to the agent with the caption. A reply includes the quoted message. While a run is in progress the status line shows the current tool, and the answer arrives as a new message with buttons: patch file, commit, reset session. /status names the active topic and the queue. One run at a time; a waiting topic is told when its turn starts.
| /phpunit [args] | Runs bash ./scripts/phpunit.sh … in REPO_CWD (if present) |
| /phpstan [args] | Runs bash ./scripts/phpstan.sh … in REPO_CWD (if present) |
Only one agent run is active at a time (global queue). The agent will not commit or push unless you ask for that in the prompt.
Agent replies are wrapped with Telegram-specific formatting in bot/prompt.py (no markdown tables; backlog lists as plain-text blocks). Short «дай список задач» / /backlog use HTML from bot/backlog_view.py. Target-repo Cursor rules (e.g. HugSalesSolo) keep the IDE table format and should not duplicate Telegram styles.
- Only allowlisted users can use the bot (first DM auto-claims if the list was empty).
- Optionally restrict chats with
ALLOWED_CHAT_IDS. - The local Cursor SDK runs tools without IDE approval prompts — treat this bot like shell access to
REPO_CWD. - Never commit
.env. Keep the repo private if your deployment details are sensitive, or rotate keys if they leak.
CursorTgBot/
├── bot/ # Telegram handlers + Cursor agent runner
├── cli/ # Terminal UI
├── data/ # Local session store (gitignored)
├── .env.example
├── requirements.txt
├── run.sh # Telegram bot launcher
├── tgBot # Terminal agent (`tgBot` on PATH)
└── cli.sh # Same launcher as tgBot