Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• main.py
• config.py
• totally_reset_cursor.py
• reset_machine_manual.py
• bypass_token_limit.py
• cursor_acc_info.py
• scripts/install.sh
• build.py
• locales/en.json

The cursor-free-vip project is a Python-based command-line toolkit designed to interact with and modify the Cursor application. Its primary function is to alter Cursor's local data and source files to reset trial-related identifiers and patch application behavior, effectively bypassing certain "Pro" feature limitations. The architecture is modular, with a main entry point that dispatches tasks to specialized scripts. It supports multiple operating systems (Windows, macOS, Linux) by abstracting file paths and system-specific commands.

The system relies on direct manipulation of Cursor's configuration files (e.g., storage.json, state.vscdb), patching its internal JavaScript files (main.js, workbench.desktop.main.js), and modifying system-level machine identifiers. Configuration is managed centrally, and the user interface is internationalized using JSON-based language files.

Core Components

The application is composed of several key Python scripts and configuration files that work together to provide its functionality.

Component	File(s)	Description
Main Entrypoint	main.py	Provides a CLI menu for the user to select an action. It initializes the configuration, handles language selection, and calls other scripts to perform the chosen tasks.
Configuration	config.py	Manages the config.ini file, providing default paths for Cursor's files across different OSes and other operational settings. It uses configparser for file I/O.
Reset Logic	totally_reset_cursor.py, reset_machine_manual.py	Contain the core logic for resetting machine IDs and patching files. The MachineIDResetter class is central to this process.
JS Patching	totally_reset_cursor.py, bypass_token_limit.py	Include functions (modify_workbench_js, modify_main_js) that perform string and regex replacements on Cursor's JavaScript source files.
Internationalization	main.py, locales/*.json	The Translator class in main.py loads language strings from JSON files in the locales directory to provide a multi-language UI.
Installation	scripts/install.sh, scripts/install.ps1	Shell and PowerShell scripts that automate downloading the latest release from GitHub and executing it.
Build System	build.py	Uses PyInstaller to package the Python application into a single, distributable executable for Windows, macOS, and Linux.

Sources: main.py, config.py, totally_reset_cursor.py, scripts/install.sh, build.py

Application Startup Flow

The following diagram illustrates the high-level startup and operation flow, starting from the user running the main script.

Sources: main.py:650-773

Configuration Management

Configuration is handled by the config.py module, which creates and manages a config.ini file located in the user's documents directory (.cursor-free-vip/config.ini). This file stores paths to Cursor's application and data files, browser settings, and other operational parameters.

Configuration Structure

The config.ini file is organized into sections. The system defines default values and creates the file if it doesn't exist.

Section	Key	Description
Browser	default_browser, chrome_path, etc.	Paths to various web browsers and their drivers.
Timing	page_load_wait, input_wait, etc.	Defines wait times for browser automation tasks to mimic human behavior.
Utils	enabled_update_check, enabled_account_info	Toggles for features like the automatic update check.
WindowsPaths	storage_path, sqlite_path, cursor_path	OS-specific paths for Cursor files on Windows.
MacPaths	storage_path, sqlite_path, cursor_path	OS-specific paths for Cursor files on macOS.
LinuxPaths	storage_path, sqlite_path, cursor_path	OS-specific paths for Cursor files on Linux.

Sources: config.py:25-207

Path Discovery

A critical function of the architecture is locating Cursor's files, which vary by OS. Functions like get_cursor_paths, get_cursor_machine_id_path, and get_workbench_cursor_path use a combination of default locations and the config.ini file to find necessary files. For Linux, the scripts also search common installation paths and extracted AppImage directories.

Sources: totally_reset_cursor.py:50-204, config.py:28-207

Machine ID Reset and Patching

The core feature of the tool is the ability to reset Cursor's state to bypass trial limitations. This is a multi-step process involving file modification, new ID generation, and system-level changes.

MachineIDResetter Class

The MachineIDResetter class, found in totally_reset_cursor.py and reset_machine_manual.py, orchestrates the reset process.

Sources: totally_reset_cursor.py:613-890

Reset and Patching Sequence

The following sequence diagram details the interactions between different components during a full reset.

Sources: totally_reset_cursor.py:800-858, main.py:749-752

JavaScript File Patching

The application directly modifies Cursor's source code to change its behavior. This is done by reading the JavaScript files, performing replacements, and writing the content back.

Key modifications include:

File	Original Code Pattern (Simplified)	Replacement Goal
workbench.desktop.main.js	title:"Upgrade to Pro"	Changes the "Upgrade to Pro" button to a link to the project's GitHub.
workbench.desktop.main.js	<div>Pro Trial	Changes the "Pro Trial" badge to simply "Pro".
workbench.desktop.main.js	getEffectiveTokenLimit(e){...return 2e5;	Increases the token limit for AI interactions.
main.js	async getMachineId(){return...??...}	Modifies the machine ID retrieval logic to bypass certain checks.

Sources: totally_reset_cursor.py:421-460, 501-514, bypass_token_limit.py:108-142

Internationalization (i18n)

The application supports multiple languages through a simple i18n system managed by the Translator class in main.py.

• Language Files: Translations are stored in JSON files within the locales/ directory (e.g., en.json, zh_cn.json).
• Translator Class: On startup, this class detects the system language or loads the language specified in config.ini. It loads all available .json files into memory.
• get(key, **kwargs) Method: Retrieves a translated string using a dot-separated key (e.g., translator.get('reset.title')). It supports placeholder replacement and falls back to English if a translation is missing.
• Arabic Support: The class includes special handling for Arabic text to ensure correct right-to-left rendering in terminals that support it, using the arabic_reshaper and bidi libraries.

Sources: main.py:92-353, locales/en.json, locales/zh_cn.json

Installation and Distribution

The project provides automated installation scripts and a build process to create distributable executables.

• Build Process (build.py): This script uses PyInstaller to bundle the entire Python application, including all dependencies and locale files, into a single executable file. It generates different binaries for Windows (.exe), macOS, and Linux. The output file is named with the version and OS, e.g., CursorFreeVIP_1.0.0_windows.exe.
  Sources: [build.py]

• Installation Scripts (install.sh, install.ps1): These scripts provide a user-friendly way to install the application. They perform the following steps:

  1. Check the latest release version from the GitHub API.
  2. Detect the user's OS and architecture.
  3. Construct the correct download URL for the corresponding binary.
  4. Download the executable to the user's Downloads folder.
  5. Make the binary executable and run it.

Sources: scripts/install.sh, scripts/install.ps1