cursor-resumer

Cursor Resumer

A Python script that automatically detects and clicks the "resume the conversation" button when Cursor AI reaches its 25 tool call limit.

Overview

This script runs in the background and monitors your Cursor AI editor for the message:

"Note: By default, we stop the agent after 25 tool calls. You can resume the conversation."

When detected, it automatically clicks the blue "resume" link to continue the AI agent's work without manual intervention.

Important: Visibility Requirements

For the script to work properly, one of the following conditions must be met:

• Option 1: Cursor app is the active window and the chat is visible
• Option 2: Cursor's chat tab is visible alongside other apps (split screen, floating window, etc.) and scrolled to show the latest messages

The script needs to be able to see the "resume" button on screen to click it.

Features

• Smart Detection: Uses OCR and color detection to find the resume button
• Precise Clicking: Only clicks on blue "resume" text, not random blue elements
• Background Operation: Runs quietly without bringing Cursor to front until needed
• Minimal Output: Only shows successful clicks in quiet mode
• No Disk Usage: Doesn't save screenshots by default to preserve disk space

Prerequisites

• macOS (uses macOS-specific screenshot and window management)
• Python 3.7+
• Tesseract OCR installed via Homebrew
• Cursor AI editor

Installation

Prerequisites

First, install Tesseract OCR:

brew install tesseract

Option 1: Install from pip

For standard installation:

pip install cursor-resumer

Note for macOS users with Python 3.11+: If you encounter an "externally-managed-environment" error, use one of these methods:

Method A: Virtual Environment (Recommended)

python3 -m venv cursor-env
source cursor-env/bin/activate
pip install cursor-resumer

Method B: pipx (Isolated Installation)

brew install pipx
pipx install cursor-resumer

Method C: Force Installation (Not Recommended)

pip install --break-system-packages cursor-resumer
# OR
pip install --user cursor-resumer

Option 2: Install from source

# Clone the repository
git clone https://github.com/khaterdev/cursor-resumer
cd cursor-resumer

# Install in development mode
pip install -e .

Option 3: Manual installation with virtual environment

# Clone the repository
git clone https://github.com/khaterdev/cursor-resumer
cd cursor-resumer

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On macOS/Linux

# Install the package
pip install .

Usage

Basic Usage

After installation, you can run the script from anywhere:

cursor-resumer

Or if running from source:

python -m cursor_resumer

The script will start monitoring:

Cursor Resumer Monitor Started
Running in background mode - Cursor won't be brought to front until resume is found
Checking every 1 second
Press Ctrl+C to stop

Continue using your computer normally. When Cursor hits the 25 tool limit, the script will automatically click resume:

Clicked resume button! (Total: 1)

Stop the script with Ctrl+C

Command Line Options

# Show help
cursor-resumer --help

# Run in verbose mode (shows all detection attempts)
cursor-resumer --verbose

# Enable debug screenshots (saves images to debug_screenshots/)
cursor-resumer --debug

# Run in quiet mode (default)
cursor-resumer --quiet

Configuration

You can modify these settings in the source code (cursor_resumer/main.py):

CHECK_INTERVAL = 1  # How often to check (seconds)
MIN_CLICK_INTERVAL = 10  # Minimum seconds between clicks
VERBOSE = False  # Show detailed logging
DEBUG_SAVE_SCREENSHOTS = False  # Save screenshots for debugging
BACKGROUND_MODE = True  # Run quietly in background

How It Works

• Window Detection: Finds the Cursor window position and size
• Screenshot Capture: Takes screenshots of the Cursor window (not the entire screen)
• Text Detection: Uses multiple methods to find the resume button:
  • OCR to find "25 tool calls" message and nearby "resume" text
  • Color detection to find blue link text
  • Pattern matching for text layout
• Smart Clicking: Only activates Cursor and clicks when resume is found

Troubleshooting

"externally-managed-environment" Error

This error occurs on macOS with Python 3.11+ due to system Python protection. Solutions:

• Use virtual environment (recommended):

  python3 -m venv venv
  source venv/bin/activate
  pip install cursor-resumer
  

• Use pipx:

  brew install pipx
  pipx install cursor-resumer
  

• Force install (not recommended):

  pip install --break-system-packages cursor-resumer
  

"Tesseract is not installed!"

Install Tesseract OCR:

brew install tesseract

Script doesn't detect the resume button

• Make sure Cursor window is visible (not minimized)
• Try running with --verbose to see what's being detected
• Enable debug screenshots with --debug to see what the script sees

Permission errors

Grant Terminal/IDE accessibility permissions:

• System Preferences → Security & Privacy → Privacy
• Select Accessibility
• Add Terminal (or your IDE) to the list

Script clicks wrong things

The script only clicks on blue text containing "resume". If it's clicking incorrectly:

• Check that your Cursor theme shows links in blue
• Adjust the blue color ranges in the script if needed

Virtual Environment Management

Activate virtual environment

source venv/bin/activate

Deactivate virtual environment

deactivate

Recreate virtual environment

rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Development

Project Structure

cursor-resumer/
├── cursor_resumer/
│   ├── __init__.py    # Package initialization
│   └── main.py        # Main script
├── setup.py           # Package setup file
├── pyproject.toml     # Modern Python packaging config
├── requirements.txt   # Python dependencies
├── README.md         # This file
├── LICENSE           # MIT License
└── venv/             # Virtual environment (not in git)

Debug Mode

Run with debug screenshots enabled:

cursor-resumer --debug

This creates a debug_screenshots/ folder with images showing:

• Original screenshots
• Detected blue regions
• OCR results

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Feel free to submit issues or pull requests if you find bugs or have improvements!