Skip to content

README.md

Latest commit

 

History

History
154 lines (109 loc) · 4.65 KB

README.md

File metadata and controls

154 lines (109 loc) · 4.65 KB

Cursor Credits Checker

PyPI Version Python Versions License

Version 0.2.0 - A clean, command-line tool to check your remaining "Fast" (GPT-4) request credits for your Cursor account directly from your terminal.

Features

  • 🚀 Auto-Detection: Automatically detects your Cursor installation - no configuration needed!
  • 📊 Usage Statistics: Shows your up-to-the-minute Fast (GPT-4) request usage with percentages.
  • 🔐 Secure Authentication: Automatically extracts authentication tokens from Cursor's local database.
  • 🌍 Cross-Platform: Works seamlessly on Windows, macOS, and Linux.
  • 🎨 Clean Output: Color-coded, emoji-enhanced display for a pleasant user experience.
  • ⚡ Fast & Reliable: Direct API integration with proper session token handling.
  • 🛠️ Zero Configuration: Works out-of-the-box with standard Cursor installations.

Installation

You can install the tool directly from PyPI.

Prerequisites:

  • Python 3.13+
  • pip or uv for installation.
# Using uv (recommended)
uv pip install cursor-credits

# Or using pip
pip install cursor-credits

Quick Start

Simply install and run - no configuration needed!

# Install
uv pip install cursor-credits

# Run
cursor-credits

Usage

Basic Usage

cursor-credits

Options

cursor-credits --help          # Show help
cursor-credits --version       # Show version
cursor-credits -v             # Verbose output with debug info

Example Output

Normal output:

👤 User ID: user_01JYA111KEE9Q4PE54ZA6LR4SG
⭐ Fast: 46/500 (9.2%)
📝 Slow: Not available

With verbose flag:

cursor-credits -v
DEBUG: Found Cursor data at standard location
DEBUG: Token found in SQLite database
DEBUG: Created session token for user ID: user_01JYA111KEE9Q4PE54ZA6LR4SG
DEBUG: Successfully retrieved usage information
👤 User ID: user_01JYA111KEE9Q4PE54ZA6LR4SG
⭐ Fast: 46/500 (9.2%)
📝 Slow: Not available

Error cases:

❌ Error: Could not find Cursor authentication token.
Please make sure:
1. Cursor is installed and you're logged in
2. Cursor application has been opened at least once

Requirements

  • Python 3.13+
  • Cursor AI editor installed and configured
  • Internet connection for API requests

Project Structure

src/cursor_credits/
├── __init__.py     # Package initialization and version info
├── api.py          # Handles communication with the Cursor API
├── auth.py         # Manages token extraction from storage
├── cli.py          # Command-line interface entry point
├── display.py      # User-facing output formatting
├── main.py         # Core application logic
└── paths.py        # Cross-platform path discovery
tests/
├── __init__.py     # Test package initialization
└── test_main.py    # Main functionality tests

How It Works

The tool works by:

  1. Auto-Detection: Automatically detects your Cursor installation location based on your operating system
  2. Token Extraction: Extracts JWT authentication tokens from Cursor's SQLite database (state.vscdb)
  3. Token Processing: Converts JWT tokens into proper session tokens for API authentication
  4. API Requests: Makes authenticated requests to Cursor's usage API to fetch current usage statistics
  5. Display: Shows your Fast (GPT-4) request usage with clean, color-coded output

The tool only reads data and never modifies any files or account settings.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

  1. Clone the repository
  2. Install dependencies: uv pip install -e .[dev]
  3. Run tests: uv run pytest
  4. Run linting: uv run ruff check

Changelog

See CHANGELOG.md for a detailed history of changes.

Disclaimer

This is an unofficial, third-party tool and is not affiliated with, endorsed, or supported by Cursor. It is intended for personal use only. The tool only reads local data and makes read-only requests to public APIs; it does not modify any of your files or account data. Use at your own risk.

License

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