Cursor Cuck

Get 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...

Cuck a Project

npx cursor-cuck

Run from any project directory. First time runs a setup wizard for Telegram, then auto-enables the project.

Uncuck a Project

npx cursor-cuck disable

How It Works

┌─────────────────┐                              ┌─────────────────┐
│  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"
└─────────────────┘

Quick Start

One Command Setup

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.

CLI Commands

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).

Telegram Commands

| Command | Description | | ---------------- | ----------------------------------------------- | | /new <prompt> | Open new agent chat and send prompt | | /plan <prompt> | 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).

How the AI Protocol Works

When you cuck a project, a rule is added that tells Cursor AI to:

When Finishing a Task

echo -e "done\nSummary of what was completed." > .cursor-cuck/cursor_status.txt

When Asking a Question

# Multiple 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

# Free-text question
echo -e "question\nWhat should the component be called?" > .cursor-cuck/cursor_status.txt

Status Values

• done - 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.

What Gets Watched

• Project plans: .cursor/plans/*.plan.md in each registered project
• Global plans: ~/.cursor/plans/*.plan.md
• Project-specific global plans: ~/.cursor/projects/**/*.plan.md

Workflow

1. Start a task with /plan <prompt> 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

Examples

/plan add user authentication

You'll receive:

📋 [my-project] Plan Ready: add user authentication

This 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.

Multiple Choice Questions

The AI writes:

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.

Free-Text Questions

For open-ended questions:

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

tmux new -s cursor-cuck
npx cursor-cuck
# Press Ctrl+B, then D to detach

Reattach later: tmux attach -t cursor-cuck

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): ~/.cursor-cuck/config.json

Troubleshooting

Bot not responding

• Check credentials: npx cursor-cuck status
• Re-run setup: npx cursor-cuck setup
• Send /help to test the bot

No notifications when AI finishes

• Check services are running: npx cursor-cuck
• Verify project is registered: /projects in Telegram
• Start a new chat session in Cursor (rules load at session start)
• Check .cursor-cuck/cursor_status.txt in your project

AppleScript not focusing Cursor

• Grant Accessibility permissions: System Settings → Privacy & Security → Accessibility → Add Terminal/iTerm
• Make sure Cursor is open with the chat input focused

AI not following the protocol

• Ensure .cursor/rules/telegram-notification.mdc exists in the project
• Run npx cursor-cuck enable in the project directory
• Start a new Cursor chat session
• The AI should write "done" when finished and use "question" when it needs input

License

MIT