TL;DR
- Cursor is an AI-first code editor built on VS Code, with inline generation, chat mode, and multi-file editing.
- Install in 2 minutes (
brew install --cask cursoror download from cursor.com).- Key workflows: Tab for completions,
@for chat,Cmd+L(macOS) to edit multiple files at once.- Gotchas: Some VS Code extensions don’t work; AI can hallucinate—always review code.
1. Installation and Setup
Install Cursor
Cursor supports Windows, macOS (Apple Silicon/Intel), and Linux (x86_64/ARM).
Option A: GUI Install (Recommended)
- Download the installer for your OS:
- Run the installer and open Cursor.
Option B: CLI Install (macOS/Linux)
# macOS (Homebrew)
brew install --cask cursor
# Linux (Snap)
sudo snap install cursor --edge
Expected output:
cursor was successfully installed!
- Launch Cursor and sign in with GitHub, GitLab, or Google.
First-Run Setup
- Select a theme (Cursor uses VS Code themes by default).
- Enable AI features:
- Click "Enable AI" in the welcome prompt.
- Choose between:
- Hosted model (default, free tier: 50 requests/day).
- Self-hosted (requires API keys for OpenAI/Anthropic/Ollama).
- Install VS Code extensions (optional):
- Cursor supports 90% of VS Code extensions. Install them via the Extensions sidebar (
Cmd+Shift+X).
- Cursor supports 90% of VS Code extensions. Install them via the Extensions sidebar (
Gotcha: Some extensions (e.g., certain debuggers) may not work. Check the compatibility list.
Verify Installation
Run this in the Cursor terminal to check the version:
cursor --version
Expected output (as of March 2026):
Cursor 0.12.0
2. Tab Completion and Inline Suggestions
Cursor’s AI autocomplete works like GitHub Copilot but with deeper context awareness.
Basic Usage
- Start typing code. Cursor will suggest completions inline (gray text).
- Press Tab to accept a suggestion.
- Press Esc to dismiss.
Example: Python Function
Type this in a Python file:
def calculate_ta
Cursor will suggest:
def calculate_tax(subtotal, tax_rate):
"""Calculate the total tax amount."""
return subtotal * tax_rate
Press Tab to accept.
Multi-Line Completions
Cursor can generate entire blocks of code. Example:
- Type a docstring or comment describing what you want:
# Write a function to fetch user data from an API and cache it - Press Tab. Cursor may generate:
import requests from functools import lru_cache @lru_cache(maxsize=128) def fetch_user_data(user_id): response = requests.get(f"https://api.example.com/users/{user_id}") response.raise_for_status() return response.json()
Pro Tip: Use
# TODO:or# Fix:to guide the AI.
Force a Suggestion
If Cursor isn’t suggesting anything:
- Press
Cmd+K(macOS) orCtrl+K(Windows/Linux) to trigger a suggestion. - Or type
//(any language) and describe what you need.
Common Issues
| Problem | Fix |
|---|---|
| No suggestions appearing | Check if AI is enabled (Cmd+Shift+P > "Cursor: Enable AI"). |
| Slow suggestions | Disable AI for large files (cursor.lite mode in settings). |
| Wrong language detected | Manually set the language in the bottom-right status bar. |
3. Chat Mode vs Composer Mode
Cursor offers two AI interaction modes:
| Mode | Use Case | How to Trigger | Example |
|---|---|---|---|
| Chat | Ask questions, debug, explain code | @ in the editor or Cmd+L | @explain this regex |
| Composer | Edit multiple files at once | Cmd+L (macOS) or Ctrl+L | "Refactor all API calls to use async" |
Chat Mode (@)
Use inline chat to ask questions without leaving the editor.
- Type
@in your code:@how do I optimize this SQL query? SELECT * FROM users WHERE status = 'active'; - Cursor will reply with suggestions inline:
# Try adding an index on `status` and limiting columns: SELECT id, name, email FROM users WHERE status = 'active' LIMIT 1000;
Pro Tip: Use
@docto generate docstrings or@testto create unit tests.
Composer Mode (Cmd+L)
Edit multiple files at once with natural language.
- Press
Cmd+L(macOS) orCtrl+L(Windows/Linux). - Describe your edit:
Update all API base URLs from "api.old.com" to "api.new.com" in JavaScript and Python files - Cursor will show a preview of changes across files. Press Enter to apply.
Example Output:
Files to be modified: - src/api/client.js (2 changes) - backend/services.py (1 change)
4. Cursor Rules (.cursorrules)
.cursorrules lets you define custom AI behaviors for your project.
Create a .cursorrules File
- Add a file named
.cursorrulesto your project root. - Define rules in YAML format.
Example: Enforce Code Style
# .cursorrules
rules:
- name: "Python Type Hints"
description: "Always add type hints to Python functions"
language: "python"
pattern: "def (\\w+)\\(.*\\):"
action: "Add type hints to parameters and return value"
severity: "high"
- name: "No Console Logs"
description: "Replace console.log with proper logging"
language: "javascript"
pattern: "console\\.log\\(.*\\)"
action: "Replace with logger.info()"
severity: "medium"
Predefined Rules
Cursor ships with default rules for common patterns. View them with:
cursor rules list
Expected output:
1. "Add Error Handling" (Python, JavaScript) 2. "Optimize SQL Queries" (SQL) 3. "Add Docstrings" (Python)
Disable Rules
To ignore a rule for a file, add this comment:
# cursor: disable=No Console Logs
console.log("This won't trigger a warning")
5. Model Selection and API Keys
Cursor supports:
- Hosted models (default, free tier).
- Self-hosted models (OpenAI, Anthropic, or local LLMs via Ollama).
Switch Models
- Open Settings (
Cmd+,). - Navigate to AI > Model.
- Choose from:
cursor-gpt-4.5(default, hosted).openai-gpt-4(requires OpenAI API key).anthropic-claude-3(requires Anthropic API key).ollama-local(for local models likecodellama).
Add API Keys
- Get your API key from:
- Add it to Cursor:
cursor config set openai.api_key "sk-..." - Verify:
cursor config get openai.api_keyExpected output:
sk-...
Use Local Models (Ollama)
- Install Ollama:
brew install ollama - Pull a model (e.g.,
codellama):ollama pull codellama:13b - Configure Cursor to use Ollama:
cursor config set ai.model "ollama-codellama"
Gotcha: Local models are slower but keep data on-device.
6. Multi-File Editing Workflows
Cursor’s Composer Mode (Cmd+L) excels at cross-file edits.
Example: Refactor a Database Schema
- Press
Cmd+Land describe the change:Update all database models to use the new 'users_v2' table. Replace 'users.id' with 'users_v2.user_id' in Python and SQL files. - Cursor will preview changes across files. Press Enter to apply.
Example: Add Logging
- Press
Cmd+Land type:Add debug logging to all functions in src/utils.py and src/api.py. Use the format: logger.debug("Entering function_name") - Review and apply.
Gotchas
| Issue | Fix |
|---|---|
| Too many files modified | Narrow your request (e.g., "only in the backend/ directory"). |
| Incorrect changes | Use --strict mode: cursor edit --strict "your request". |
| Slow performance | Limit to 10–20 files at once. |
7. Tips for Maximizing Productivity
Keyboard Shortcuts
| Action | macOS | Windows/Linux |
|---|---|---|
| Accept suggestion | Tab | Tab |
| Open AI chat | @ | @ |
| Composer mode | Cmd+L | Ctrl+L |
| Explain code | Cmd+Shift+E | Ctrl+Shift+E |
| Generate tests | Cmd+Shift+T | Ctrl+Shift+T |
Custom Snippets
Add AI-aware snippets to .vscode/cursor-snippets.json:
{
"Python Class": {
"prefix": "pclass",
"body": [
"class ${1:ClassName}:",
" \"\"\"${2:Docstring}\"\"\"",
" def __init__(self, ${3:args}):",
" ${4}",
"",
" @classmethod",
" def from_dict(cls, data: dict):",
" \"\"\"Create instance from dict.\"\"\"",
" return cls(${5})"
],
"description": "Python class with type hints and from_dict"
}
}
Trigger with
pclass+ Tab.
Collaboration
- Real-time pair programming: Click "Share" in the top-right to invite teammates.
- Conflict resolution: Use
cursor git lockto prevent overwrites.
What's Next?
- Try Composer Mode: Press
Cmd+Land refactor a small feature in your codebase. - Set up
.cursorrules: Add 2–3 rules for your team’s coding standards. - Experiment with local models: Install Ollama and test
codellamafor offline use.
For teams scaling AI workflows, Hyperion Consulting helps implement tools like Cursor with custom rules and model fine-tuning.
