{"id":30288568,"url":"https://github.com/hormold/cursor-telegram-bot","last_synced_at":"2025-08-16T22:37:54.348Z","repository":{"id":304579641,"uuid":"1019203045","full_name":"Hormold/cursor-telegram-bot","owner":"Hormold","description":"A powerful Telegram bot for managing Cursor AI Background Composers with intelligent task management and real-time monitoring.","archived":false,"fork":false,"pushed_at":"2025-07-14T02:13:08.000Z","size":60,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-14T02:58:03.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hormold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-07-14T00:46:42.000Z","updated_at":"2025-07-14T02:13:12.000Z","dependencies_parsed_at":"2025-07-14T02:58:07.278Z","dependency_job_id":"6cdfbfd6-a270-426e-8cad-d7f3eedb946d","html_url":"https://github.com/Hormold/cursor-telegram-bot","commit_stats":null,"previous_names":["hormold/cursor-telegram-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Hormold/cursor-telegram-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hormold%2Fcursor-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hormold%2Fcursor-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hormold%2Fcursor-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hormold%2Fcursor-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hormold","download_url":"https://codeload.github.com/Hormold/cursor-telegram-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hormold%2Fcursor-telegram-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270781214,"owners_count":24643808,"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-08-16T02:00:11.002Z","response_time":91,"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":[],"created_at":"2025-08-16T22:37:53.788Z","updated_at":"2025-08-16T22:37:54.332Z","avatar_url":"https://github.com/Hormold.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cursor AI Telegram Bot\n\nA powerful Telegram bot for managing Cursor AI Background Composers with intelligent task management and real-time monitoring.\n\n## ✨ Features\n\n- 🤖 **AI Task Management**: Start, monitor, and manage Cursor AI coding tasks\n- 🔐 **Secure Authentication**: Cookie-based authentication with validation\n- 📊 **Real-time Monitoring**: Automatic task progress tracking and notifications\n- 💬 **Interactive Interface**: Telegram buttons for external links and actions\n- 🛡️ **Security**: Repository and user access control via environment variables\n- 📱 **User-friendly**: Simple commands with rich status information\n\n### Quick Setup:\n\n1. **Create Telegram Bot**: Message [@BotFather](https://t.me/BotFather) → `/newbot`\n2. **Get your User ID**: Message [@userinfobot](https://t.me/userinfobot) \n3. **Deploy**: Click Railway button, add your `BOT_TOKEN` and `OPENROUTER_API_KEY`\n4. **Volume**: Railway will auto-create volume for `/app/data` (SQLite database storage)\n5. **Setup Cursor cookies**: Send your `WorkosCursorSessionToken` to the bot\n\n## 🛠️ Local Development\n\n### 1. Installation\n\n```bash\ngit clone https://github.com/hormold/cursor-telegram-bot\ncd cursor-telegram-bot\npnpm install\n```\n\n### 2. Configuration\n\nCreate `.env` file:\n\n```env\n# Required\nBOT_TOKEN=your_telegram_bot_token_here\nOPENROUTER_API_KEY=your_openrouter_api_key_here\n\n# Optional: OpenRouter model (default: openai/gpt-4.1)\nOPENROUTER_MODEL=openai/gpt-4.1\n\n# Optional: Repository access control\nALLOWED_REPOS=https://github.com/user/repo1,https://github.com/user/repo2\n\n# Optional: User access control (get your ID from @userinfobot)\nALLOWED_USERS=123456,789012\n```\n\n### 3. Setup Cursor API Cookies\n\n1. Go to [https://cursor.com/agents](https://cursor.com/agents)\n2. Open Developer Tools (F12)\n3. Go to Network tab\n4. Refresh the page\n5. Find any request to cursor.com\n6. Copy the entire Cookie header value\n7. Send it to the bot. YOU NEED ONLY WorkosCursorSessionToken cookie value. Send it in format WorkosCursorSessionToken=...\n\n### 4. Run the Bot\n\n```bash\npnpm run build\npnpm start\n```\n\n## 🎮 Bot Commands\n\n| Command | Description |\n|---------|-------------|\n| `/start` | Welcome message and setup guide |\n| `/tasks` | View your active tasks |\n| `/cookies` | Get cookie setup instructions |\n| `/help` | Show available commands |\n\n## 🔧 Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BOT_TOKEN` | Yes | Telegram bot token from @BotFather |\n| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for AI functionality |\n| `OPENROUTER_MODEL` | No | OpenRouter model (default: 'openai/gpt-4.1') |\n| `ALLOWED_REPOS` | No | Comma-separated list of allowed repository URLs |\n| `ALLOWED_USERS` | No | Comma-separated list of allowed Telegram user IDs |\n| `DB_PATH` | No | Database file path (defaults to 'bot.db', Railway: '/app/data/bot.db') |\n\n## 🛡️ Security\n\n- **No Cookie Exposure**: The bot never exposes actual cookie values\n- **Repository/User Control**: Optional repository and user access control via environment variables\n- **Authentication Validation**: Cookies are validated before every operation\n- **Operation Tracking**: All actions are logged for audit purposes\n\n## 📖 Usage Examples\n\n### Starting a Task\n\n```\nUser: Add authentication to my React app\nBot: ✅ Task started successfully!\n     🔗 [Open in Cursor] (button)\n```\n\n### Checking Task Status\n\n```\nUser: /tasks\nBot: 📊 Active Tasks (2):\n     \n     🔄 Task: \"Add authentication system\"\n     📍 Repository: user/react-app\n     ⏱️ Status: RUNNING\n     🔗 [Open in Cursor] (button)\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Telegram Bot  │───▶│   AI Agent      │───▶│   Cursor API    │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n                                │\n                       ┌─────────────────┐\n                       │    Database     │\n                       └─────────────────┘\n```\n\n## 🔄 Task Lifecycle\n\n1. **Start**: Create background composer task in repository\n2. **Monitor**: Real-time status tracking and updates\n3. **Notify**: Automatic notifications on completion/failure\n4. **Manage**: Stop or cancel running tasks as needed\n\n## 🧪 Development\n\n### Build\n\n```bash\npnpm run build\n```\n\n### Watch Mode\n\n```bash\npnpm run dev\n```\n\n### Database Schema\n\nThe bot uses SQLite with the following main tables:\n- `users` - User management\n- `chats` - Chat configuration\n- `tasks` - Task tracking and status\n- `messages` - Conversation history\n- `config` - Bot configuration\n\n## 📝 API Integration\n\nThe bot integrates with:\n- **Cursor API**: For background composer management\n- **OpenRouter API**: For AI-powered interactions\n- **Telegram Bot API**: For messaging and user interface\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n\n## �📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Cursor AI](https://cursor.com) for the amazing AI coding assistant\n- [Grammy](https://grammy.dev) for the Telegram bot framework\n- [OpenRouter](https://openrouter.ai) for AI API access\n- [Railway](https://railway.app) for seamless deployment\n\n---\n\n**Ready to supercharge your Cursor AI workflow with intelligent automation!** 🚀 ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhormold%2Fcursor-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhormold%2Fcursor-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhormold%2Fcursor-telegram-bot/lists"}