https://github.com/hormold/cursor-telegram-bot
A powerful Telegram bot for managing Cursor AI Background Composers with intelligent task management and real-time monitoring.
https://github.com/hormold/cursor-telegram-bot
Last synced: 10 months ago
JSON representation
A powerful Telegram bot for managing Cursor AI Background Composers with intelligent task management and real-time monitoring.
- Host: GitHub
- URL: https://github.com/hormold/cursor-telegram-bot
- Owner: Hormold
- Created: 2025-07-14T00:46:42.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-14T02:13:08.000Z (11 months ago)
- Last Synced: 2025-07-14T02:58:03.954Z (11 months ago)
- Language: TypeScript
- Homepage:
- Size: 58.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Cursor AI Telegram Bot
A powerful Telegram bot for managing Cursor AI Background Composers with intelligent task management and real-time monitoring.
## โจ Features
- ๐ค **AI Task Management**: Start, monitor, and manage Cursor AI coding tasks
- ๐ **Secure Authentication**: Cookie-based authentication with validation
- ๐ **Real-time Monitoring**: Automatic task progress tracking and notifications
- ๐ฌ **Interactive Interface**: Telegram buttons for external links and actions
- ๐ก๏ธ **Security**: Repository and user access control via environment variables
- ๐ฑ **User-friendly**: Simple commands with rich status information
### Quick Setup:
1. **Create Telegram Bot**: Message [@BotFather](https://t.me/BotFather) โ `/newbot`
2. **Get your User ID**: Message [@userinfobot](https://t.me/userinfobot)
3. **Deploy**: Click Railway button, add your `BOT_TOKEN` and `OPENROUTER_API_KEY`
4. **Volume**: Railway will auto-create volume for `/app/data` (SQLite database storage)
5. **Setup Cursor cookies**: Send your `WorkosCursorSessionToken` to the bot
## ๐ ๏ธ Local Development
### 1. Installation
```bash
git clone https://github.com/hormold/cursor-telegram-bot
cd cursor-telegram-bot
pnpm install
```
### 2. Configuration
Create `.env` file:
```env
# Required
BOT_TOKEN=your_telegram_bot_token_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
# Optional: OpenRouter model (default: openai/gpt-4.1)
OPENROUTER_MODEL=openai/gpt-4.1
# Optional: Repository access control
ALLOWED_REPOS=https://github.com/user/repo1,https://github.com/user/repo2
# Optional: User access control (get your ID from @userinfobot)
ALLOWED_USERS=123456,789012
```
### 3. Setup Cursor API Cookies
1. Go to [https://cursor.com/agents](https://cursor.com/agents)
2. Open Developer Tools (F12)
3. Go to Network tab
4. Refresh the page
5. Find any request to cursor.com
6. Copy the entire Cookie header value
7. Send it to the bot. YOU NEED ONLY WorkosCursorSessionToken cookie value. Send it in format WorkosCursorSessionToken=...
### 4. Run the Bot
```bash
pnpm run build
pnpm start
```
## ๐ฎ Bot Commands
| Command | Description |
|---------|-------------|
| `/start` | Welcome message and setup guide |
| `/tasks` | View your active tasks |
| `/cookies` | Get cookie setup instructions |
| `/help` | Show available commands |
## ๐ง Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `BOT_TOKEN` | Yes | Telegram bot token from @BotFather |
| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for AI functionality |
| `OPENROUTER_MODEL` | No | OpenRouter model (default: 'openai/gpt-4.1') |
| `ALLOWED_REPOS` | No | Comma-separated list of allowed repository URLs |
| `ALLOWED_USERS` | No | Comma-separated list of allowed Telegram user IDs |
| `DB_PATH` | No | Database file path (defaults to 'bot.db', Railway: '/app/data/bot.db') |
## ๐ก๏ธ Security
- **No Cookie Exposure**: The bot never exposes actual cookie values
- **Repository/User Control**: Optional repository and user access control via environment variables
- **Authentication Validation**: Cookies are validated before every operation
- **Operation Tracking**: All actions are logged for audit purposes
## ๐ Usage Examples
### Starting a Task
```
User: Add authentication to my React app
Bot: โ
Task started successfully!
๐ [Open in Cursor] (button)
```
### Checking Task Status
```
User: /tasks
Bot: ๐ Active Tasks (2):
๐ Task: "Add authentication system"
๐ Repository: user/react-app
โฑ๏ธ Status: RUNNING
๐ [Open in Cursor] (button)
```
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Telegram Bot โโโโโถโ AI Agent โโโโโถโ Cursor API โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโ
โ Database โ
โโโโโโโโโโโโโโโโโโโ
```
## ๐ Task Lifecycle
1. **Start**: Create background composer task in repository
2. **Monitor**: Real-time status tracking and updates
3. **Notify**: Automatic notifications on completion/failure
4. **Manage**: Stop or cancel running tasks as needed
## ๐งช Development
### Build
```bash
pnpm run build
```
### Watch Mode
```bash
pnpm run dev
```
### Database Schema
The bot uses SQLite with the following main tables:
- `users` - User management
- `chats` - Chat configuration
- `tasks` - Task tracking and status
- `messages` - Conversation history
- `config` - Bot configuration
## ๐ API Integration
The bot integrates with:
- **Cursor API**: For background composer management
- **OpenRouter API**: For AI-powered interactions
- **Telegram Bot API**: For messaging and user interface
## ๐ค Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
## ๏ฟฝ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- [Cursor AI](https://cursor.com) for the amazing AI coding assistant
- [Grammy](https://grammy.dev) for the Telegram bot framework
- [OpenRouter](https://openrouter.ai) for AI API access
- [Railway](https://railway.app) for seamless deployment
---
**Ready to supercharge your Cursor AI workflow with intelligent automation!** ๐