BACKGROUND Mode

Why We Need ⚫ BACKGROUND Mode

The BACKGROUND mode is for massive, time-consuming tasks that you want to run across your entire codebase without blocking your workflow.

It's the "set it and forget it" mode.

It performs large-scale operations asynchronously, allowing you to continue coding, switching branches, or even closing files while it works.

🚀 It's ideal for:

• Codebase Migrations:
  "Convert the entire /src directory from JavaScript to TypeScript."
• Fixing All Lint Errors:
  Automatically resolve all formatting or style issues reported by a linter across the whole project.
• Generating Documentation:
  "Add JSDoc-style docstrings to every function in the project."
• Large-Scale API Updates:
  "Find every instance of api.oldMethod() and replace it with api.newMethod(), adapting the parameters as needed."

⚙️ How It Works

1️⃣ Prompt:
You give the AI a massive, project-wide task and select the BACKGROUND mode.

2️⃣ Job Creation:
The AI creates a background job. You'll see a progress indicator in the Cursor UI, but your editor remains fully responsive.

3️⃣ Asynchronous Execution: The AI systematically works through your files, applying changes as needed.
👉 You can continue your work uninterrupted.

4️⃣ Completion & Review:
Once the task is complete, it will notify you.
All the changes will be staged in your source control panel (e.g., Git), ready for you to review, test, and commit.

💻 Example: Converting to TypeScript

1. Activate BACKGROUND mode.
2. The AI will start a background process.
   👉 You are free to work on other parts of the codebase.
3. The AI will methodically:

Prompt:

"Go through all .js and .jsx files in the src/components directory. Rename them to .ts and .tsx respectively and add basic TypeScript types where possible."

• Rename files
• Infer and add types for props, state, and function parameters
• Change PropTypes to TypeScript interfaces or types

5. Once finished, you'll receive a notification.
   Your Git panel will show dozens of modified files, which you can now review before committing.

🎥 Working with the BACKGROUND Mode example

Because the mode has so many pitfalls and other stuff, the video would be too long to extensively explain what it does, so for this you can watch a very great video from https://www.youtube.com/@briancasel.

The video itself: