Get Telegram notifications when Cursor AI finishes tasks. Send follow-up instructions from your phone.
npm install cursor-cuckGet Telegram notifications when Cursor AI finishes tasks. Send follow-up instructions from your phone without touching your computer.
Perfect for long vibe-coding sessions where you step away while Cursor works.
> cursor cuck likes to watch...
``bash`
npx cursor-cuck
Run from any project directory. First time runs a setup wizard for Telegram, then auto-enables the project.
`bash`
npx cursor-cuck disable
---
`
┌─────────────────┐ ┌─────────────────┐
│ You (Telegram) │──────────────────────────────│ Cursor AI │
└────────┬────────┘ └────────┬────────┘
│ │
│ 1. Send message │
▼ │
┌─────────────────┐ │
│ Telegram Bot │ │
└────────┬────────┘ │
│ 2. Write + paste into Cursor │
▼ │
┌─────────────────────────────────┐ │
│ project/.cursor-cuck/ │ │
│ cursor_prompt.txt ◀─────────┼───────────────────────┘
│ cursor_status.txt ──────────┼──▶ 3. AI writes status
└─────────────────────────────────┘
│
│ 4. Watcher detects change
▼
┌─────────────────┐
│ Watcher │
└────────┬────────┘
│ 5. Send notification
▼
┌─────────────────┐
│ You (Telegram) │ "✅ Done! Ready for next instruction"
└─────────────────┘
`bash`
npx cursor-cuck
That's it! The setup wizard will guide you through:
1. Creating a Telegram bot via @BotFather
2. Getting your chat ID
3. Auto-enabling the current project directory
The wizard runs automatically on first launch. Subsequent runs just start the services.
`bash`
npx cursor-cuck # Start services (runs setup wizard if needed)
npx cursor-cuck enable # Enable notifications for current directory
npx cursor-cuck disable # Disable notifications for current directory
npx cursor-cuck setup # Re-run setup wizard (reconfigure Telegram)
npx cursor-cuck status # Show configuration status
npx cursor-cuck help # Show help
Keep the terminal open while working (or run in tmux/background).
---
| Command | Description |
| ---------------- | ----------------------------------------------- |
| /new | Open new agent chat and send prompt |/plan
| | Open new agent in plan mode and send prompt |/build
| | Approve and execute a plan (triggers Cmd+Enter) |/status
| | View status from all cucked projects |/projects
| | List all registered projects |/clear
| | Clear all prompt files |/focus
| | Focus Cursor and paste prompt |/auto
| | Toggle auto-focus (default: ON) |/help
| | Show all commands |
Send any text message to send an instruction to Cursor.
Approval phrases: Sending "build it", "go ahead", "yes", "do it", "proceed", "approved", "lgtm", "looks good", or "ship it" automatically triggers the build (same as /build).
---
When you cuck a project, a rule is added that tells Cursor AI to:
`bash`
echo -e "done\nSummary of what was completed." > .cursor-cuck/cursor_status.txt
`bashMultiple choice (creates buttons in Telegram)
echo -e "question\nWhat color theme?\n1: Light mode\n2: Dark mode\n3: System default" > .cursor-cuck/cursor_status.txt
$3
-
- Task complete (you'll get "✅ Done!")
- question - AI needs input (you'll get interactive buttons or free-text prompt)
- error - Something went wrong
- clarification_needed - AI needs more info
- working - AI is working (you'll get "🔄 Working on it...")
- plan_ready - A plan is ready for approval (you'll get "📋 Plan Ready")---
Plan Mode Integration
Cursor Cuck automatically watches for Cursor plan files and notifies you when plans are ready for approval.
$3
- Project plans:
.cursor/plans/*.plan.md in each registered project
- Global plans: ~/.cursor/plans/*.plan.md
- Project-specific global plans: $3
1. Start a task with
or use plan mode in Cursor
2. AI creates a plan and saves it as a .plan.md file
3. Watcher detects the new plan file
4. You get a Telegram notification: "📋 Plan Ready: "
5. Reply /build or say "build it" to approve
6. Cursor receives Cmd+Enter and executes the plan$3
`
/plan add user authentication
You'll receive:
📋 [my-project] Plan Ready: add user authenticationThis plan adds JWT-based authentication with login/logout...
Reply /build or "build it" to approve.
---
Interactive Questions
When the AI needs input, it can ask questions that appear as interactive buttons in Telegram.
$3
The AI writes:
bash
echo -e "question\nWhat database should we use?\n1: PostgreSQL\n2: MySQL\n3: SQLite" > .cursor-cuck/cursor_status.txt
`You receive a message with clickable buttons. Tap your choice and the answer is automatically sent back to Cursor.
$3
For open-ended questions:
bash
echo -e "question\nWhat should the API endpoint be called?" > .cursor-cuck/cursor_status.txt
`You receive a prompt and can reply with any text.
---
Running in Background
bash
tmux new -s cursor-cuck
npx cursor-cuck
Press Ctrl+B, then D to detach
`Reattach later:
---
What Gets Created
In your project:
your-project/
├── .cursor-cuck/
│ ├── cursor_prompt.txt # Instructions from Telegram
│ └── cursor_status.txt # Status updates from AI
└── .cursor/rules/
└── telegram-notification.mdc # AI protocol rule
Global config (auto-created):
---
Troubleshooting
$3
- Check credentials:
- Re-run setup:
- Send to test the bot$3
- Check services are running:
npx cursor-cuck
- Verify project is registered: in Telegram
- Start a new chat session in Cursor (rules load at session start)
- Check .cursor-cuck/cursor_status.txt in your project$3
- Grant Accessibility permissions: System Settings → Privacy & Security → Accessibility → Add Terminal/iTerm
- Make sure Cursor is open with the chat input focused
$3
- Ensure
.cursor/rules/telegram-notification.mdc exists in the project
- Run npx cursor-cuck enable` in the project directory---
MIT