Cursor

Orientation

Cursor is an AI-first code editor built on VS Code, designed to keep developers in flow by integrating code generation, refactoring, and contextual assistance directly in the editor window. It matters when you want to avoid context-switching between your editor and separate AI tools, or when you need to edit code based on surrounding context without leaving your keystroke rhythm. This reference page covers the practical aspects of installing, configuring, and using Cursor day-to-day, with concrete commands, configuration patterns, and the failure modes you’ll actually encounter.

Daily Use

Inline completion and quick edit

• Cmd+K opens the inline completion panel. Place your cursor where you want a change, type a description, and Cursor sends the request to your configured LLM. The response appears in a panel where you can accept, reject, or refine the suggestion.
• Cmd+L opens the chat interface. This is a free-form conversation with the model, not tied to the current editor state unless you reference a file or symbol.
• Both panels respect your model selection in the settings. If you have multiple API keys configured, use the dropdown in the panel header to switch providers mid-session.

The Composer

• Cmd+I opens the Composer, a multi-line editor designed for larger tasks: refactoring a function across several files, generating test suites, or implementing a feature from scratch.
• Type your request at the top. Cursor displays a preview of changes in the panel on the right. You can accept individual edits, reject them, or modify the request and re-run.
• The Composer maintains a session-level context. If you start a new Composer thread, the prior context is not carried forward unless you explicitly reference it.

File and symbol referencing

• Type / in either the chat or Composer prompt to bring up a file picker. You can select files, folders, or symbols (functions, classes, constants) to include in the context.
• Reference a file by path (e.g., /src/lib/utils.ts). Cursor will include its contents in the prompt sent to the LLM.
• You can also reference the current file implicitly by keeping the cursor within it; the editor automatically includes the surrounding region in the context window.

Configuration

API key and model setup

Cursor does not ship with a built-in LLM. You must provide your own API key from a supported provider (OpenAI, Anthropic, Google, etc.). Configuration follows these patterns:

• Settings UI: Open the Command Palette (Cmd+Shift+P) and run “Cursor: Open Settings”. In the settings panel, navigate to the “API” section. Here you can add a new API key, select a default model, and configure timeout/retries.
• Environment variables: Alternatively, set CURSOR_API_KEY in your shell environment. The application reads this variable on startup if no key is stored in the settings UI.
• Model selection: The default model depends on your subscription tier. You can override the default per-session using the model dropdown in any panel. Available models are those associated with your API key’s provider account.

The .cursorrules file

Cursor reads a .cursorrules file from your project root on startup. This is a plain text file with no prescribed schema—its contents are entirely up to you. Some users employ it to set style guidelines, preferred naming conventions, or context the model should assume. For example, a .cursorrules file might contain notes about project-specific APIs or constraints the model should honor when generating code. Cursor processes this file at initialization; there is no runtime reloading mechanism, so a change requires restarting the editor.

> Note: Do not confuse .cursorrules with VS Code’s settings.json. They are separate mechanisms. Cursor’s .cursorrules is specific to the agent’s behavior; VS Code’s settings.json controls editor preferences like tab size or font ligatures.

Common Patterns

Refactoring a function

1. Place your cursor inside the function you want to change.
2. Press Cmd+K. The inline panel opens with the function’s current signature pre-filled.
3. Type your desired change (e.g., “convert this synchronous function to async and add error handling for network timeouts”).
4. Cursor proposes edits in the panel. Review each change; accept with Cmd+Enter or reject with Esc.
5. If the proposal spans multiple lines or files, you’ll see a preview in the Composer-style panel on the right. You can accept or reject granular changes.

Generating tests for existing code

1. Open the Composer (Cmd+I).
2. Type a request such as “Generate Jest tests for the parseUser function in src/utils.ts, following the existing test patterns in __tests__/.”
3. Cursor includes the target file and relevant test files in the context. It generates a draft test file in the panel.
4. Review the output. You can accept the whole file, individual test cases, or request revisions.

Multi-file edits with the Composer

1. Select a region of code spanning multiple files (or hold Shift and click multiple cursors).
2. Open the Composer (Cmd+I).
3. Describe the transformation you want across the selected region.
4. Cursor proposes a diff. If the selection is too broad, the model may produce unexpected changes—trim the selection or be more specific in your prompt.

Sharp Edges

Context window limits

Cursor’s context window is finite. Submitting a request that references too many files, overly large files, or very broad prompts can trigger a “context too large” error. The model will truncate the earliest content or return an error, depending on the provider. If you hit this, trim your selection or break the request into smaller steps.

Model switching and session state

Switching models mid-session does not always preserve prior context. If you change the model in the panel dropdown, the new model starts with a fresh context window. Prior conversation history may be discarded. If you need to maintain continuity, restart the session or use the / reference to re-introduce key files.

Silent authentication failures

If your API key expires, becomes rate-limited, or is otherwise invalid, Cursor may silently fail to return a suggestion. The panel might show a generic “Request failed” message without indicating the HTTP 401 or 429 status. Check the VS Code output panel (View > Output, select “Cursor” from the dropdown) for raw API responses. This is the fastest way to diagnose auth issues.

Selection drift in the Composer

When using the Composer with a broad selection (e.g., an entire module file), the model may apply edits to functions or variables you did not intend to change. This is especially likely when the request is vague (“refactor this file for performance”). Prefer smaller, well-scoped selections and specific prompts.

Network dependency

All LLM interactions require outbound connectivity. If you work in an air-gapped environment, Cursor will not function for AI operations. There is no offline mode for generation or chat. Some basic editor features (syntax highlighting, navigation) work offline, but any request to an LLM requires network access.

When Things Go Wrong

Error message	Likely cause	Recommended action
Error: Request failed with status 401	Invalid or missing API key	Open settings, verify/renew your API key, or set the CURSOR_API_KEY environment variable
Error: Request failed with status 429	Rate limit exceeded	Wait and retry, or switch to a model with a higher rate limit if your plan supports it
Error: Context too large	Selection or reference set exceeds token budget	Trim the file references, remove large blocks, or split the request into multiple steps
Error: Tool not available	Requested operation requires a higher subscription tier	Check your plan’s feature matrix; some operations (e.g., certain model tiers) are tier-gated
Error: Unexpected token in response	Provider API response format changed	This is rare. Restart Cursor; if persistent, contact support with the raw output from the VS Code output panel

Getting Unstuck

• Press Esc at any time to cancel a running generation or clear the current panel.
• Use / in chat or the Composer to reference specific files, symbols, or folders. This re-anchors the context and often resolves confusion the model has about which code you’re referring to.
• If the model seems to “forget” the conversation context, start a new session (Cmd+Shift+P → “Cursor: New Session”). This resets the context window but preserves your API key and model settings.
• Inspect the VS Code output panel (View > Output, select “Cursor”) for raw HTTP responses, request IDs, and error details. This is the most reliable way to debug issues that aren’t surface-level.
• Reset your local state by deleting the ~/.cursor config directory (on macOS, this is ~/Library/Application Support/Cursor). This removes cached API keys, session history, and stored preferences. You’ll need to re-enter your API key after deletion.

This page was rewritten on 11 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.