Cursor VS Code: the wiring, and the two things that break it

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

Cursor does not run “inside” VS Code. It is a separate editor built on the VS Code codebase, so the two applications can open the same repository and use similar settings, extensions, tasks, and shortcuts. They do not automatically share runtime state, extension state, terminals, or agent instructions.

That distinction matters. “Cursor VS Code integration” usually means one of three things:

| Assumption | What actually happens | |---|---| | Cursor is a VS Code extension | Cursor is a separate application. | | Importing settings keeps both editors synchronized | Import is a copy, not a permanent link. | | The agent sees the same environment as the terminal | Agent commands may run in a different shell context. |

The useful integration surface is the repository itself. Put formatting, validation, tasks, and project instructions under version control; treat editor-local state as disposable.

Cursor’s agent is powered by a large language model, a system that generates output from context rather than enforcing repository invariants. Rules can guide it, but only scripts and tests can decide whether its changes are acceptable. Cursor’s official documentation explains the product features; it does not remove the need for repository-level enforcement.

Photo by cottonbro studio on Pexels.

The wiring#

The reliable setup has four layers: shared editor settings, recommended extensions, Cursor-specific instructions, and one executable verification path. If any requirement exists only in a developer’s global settings or prompt history, the repository is not wired—it merely works on one machine.

1. Make repository settings authoritative#

Start with a tracked .vscode/settings.json. Cursor can consume VS Code-style workspace settings because of its VS Code foundation.

{
  "files.eol": "\n",
  "editor.detectIndentation": false,
  "editor.insertSpaces": true,
  "editor.tabSize": 2,
  "editor.formatOnSave": false,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}

These values are examples, not universal style choices. Replace them with the repository’s actual conventions. The important decision is disabling editor-dependent formatting when the repository already has a canonical formatter command; two competing formatters create noisy diffs.

Do not rely on Cursor’s one-time settings import as configuration management. Importing is useful for initial comfort, but the tracked workspace file is what a second developer can inspect and reproduce. Use the Cursor documentation to distinguish imported preferences from repository configuration.

2. Recommend extensions without making them the verifier#

Add .vscode/extensions.json so both editors expose the same expected tooling:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}

Change those identifiers to match the repository. Recommendations are not installation guarantees, and an extension is not a build dependency. A developer may decline it, run remotely, or use another editor.

The repository must still format, lint, type-check, and test through its own package or build system. That principle also applies when another agent operates outside Cursor. Claude Code’s official documentation describes a terminal-based agent workflow, which makes repository-owned commands the common interface between editor agents and CLI agents.

3. Give Cursor narrow repository instructions#

Create .cursor/rules/repository.mdc:

---
description: Repository-wide implementation constraints
alwaysApply: true
---

Before editing, identify the existing module boundary and the nearest tests.

Do not replace repository scripts with editor-only commands.

Preserve public interfaces unless the task explicitly requires a breaking change.

Run the repository verification task before declaring work complete.

If verification cannot run, report the exact command and failure instead of claiming success.

Keep this file short. It should contain durable constraints, not a second architecture handbook. An agent needs operational boundaries: what it must preserve, what it must run, and what it must disclose.

This is also where teams overestimate prompts. A rule can tell an agent to run validation, but it cannot make a broken validator pass. If the repository needs a stronger operating model, the PairFoundry Agent Operating Kit is the relevant next step; the other available packs are listed in the PairFoundry pack overview.

4. Expose one canonical verification task#

Add .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "verify",
      "type": "shell",
      "command": "npm test",
      "group": {
        "kind": "test",
        "isDefault": true
      },
      "problemMatcher": []
    }
  ]
}

Replace npm test with the repository’s real verification command. It should call the same checks used outside the editor, not an abbreviated “developer-friendly” subset that can pass while CI fails.

The task is an adapter, not the source of truth. VS Code, Cursor, Claude Code, Codex, and a human terminal should converge on the same underlying command. For more wiring patterns, use the Wiring It In collection.

The two things that break it#

Two failures account for most “Cursor works but VS Code does not” reports: configuration split and execution-environment split. Both can look like an AI problem, but neither is fixed by changing models or adding a longer prompt.

1. Configuration split#

The visible error is often There is no formatter for … files installed, an unavailable command, or a file that reformats differently when opened in the other editor. The cause is that one application has an extension or user setting the other does not.

Fix it in this order:

1. Move stable settings into .vscode/settings.json.
2. Put expected extensions in .vscode/extensions.json.
3. Make the repository formatter authoritative.
4. Reopen the repository and inspect workspace settings in both editors.
5. Remove conflicting user-level overrides.

Do not “fix” the problem by committing every personal preference. Fonts, themes, panel placement, and keybindings are not repository invariants. Cursor’s configuration guidance lives in the official Cursor documentation, but the team must decide which settings deserve source control.

2. Execution-environment split#

The visible error is commonly command not found, a missing module, or a tool reporting a different runtime than the developer’s normal terminal. The agent or editor task is running with a different PATH, working directory, shell initialization, or environment variables.

For a macOS repository standardized on a login Zsh shell, the workspace setting can be explicit:

{
  "terminal.integrated.profiles.osx": {
    "zsh-login": {
      "path": "/bin/zsh",
      "args": ["-l"]
    }
  },
  "terminal.integrated.defaultProfile.osx": "zsh-login"
}

Do not paste that into a cross-platform repository without adding the corresponding supported profiles. Better still, make the verification script locate project-local tools through the package manager instead of assuming global executables.

This failure also affects terminal-based agents, so compare their documented execution model with Claude Code’s documentation. The correct fix is a deterministic command environment, not telling the agent to “try again.”

Photo by panumas nikhomkhai on Pexels.

Verifying it works#

A successful chat response proves nothing. Verification means both editors and any CLI agent can start from a fresh process, run the same repository command, observe the same deliberate failure, and leave no unexplained diff.

Use this sequence:

1. Close both editors so inherited environment state is gone.
2. Open the repository separately in VS Code and Cursor.
3. Run the verify task in each.
4. Introduce a small, intentional test or lint failure.
5. Confirm both executions fail for the same reason.
6. Revert that change and confirm both pass.
7. Inspect git diff for formatter or line-ending churn.
8. Ask the agent to state the exact command it ran and its result.

The intentional failure is essential. A task that always exits successfully can look perfectly wired while checking nothing. If you need the underlying agent concepts before adopting a packaged workflow, follow the free PairFoundry foundations track.

Team considerations#

The second developer will expose every dependency hidden in the first developer’s machine. A team-ready setup therefore minimizes global tools, documents the canonical command, tracks only durable settings, and treats Cursor rules as one adapter—not the repository’s sole source of truth.

Before rollout, confirm that:

• A clean checkout contains the workspace settings and tasks.
• Required tools are declared by the project’s package or build system.
• Verification does not depend on a globally installed executable.
• Cursor-specific instructions point toward executable checks.
• VS Code users can work without installing Cursor.
• CLI agents can run the same validation command.
• Platform-specific terminal configuration is explicit.

Do not duplicate detailed invariants across Cursor rules, agent files, CI configuration, and onboarding prose. Put enforceable behavior in scripts and tests; let each tool-specific instruction reference that behavior. Prompt text drifts silently, while a failing command is visible.

Photo by Christina Morillo on Pexels.

Related reading#

• Obsidian MCP server — a setup that survives a second developer
• Claude Code IntelliJ — a setup that survives a second developer

FAQ#

How to use Cursor in VS Code?#

You do not install Cursor into VS Code. Open the same repository in the separate Cursor application, share tracked .vscode settings and tasks, and keep validation in repository scripts. Use Cursor-specific rules only for agent behavior that VS Code itself does not need.

Is Cursor still better than VS Code?#

Cursor is better when integrated agent workflows are central to the work. VS Code remains the cleaner choice when you want the underlying editor ecosystem without Cursor’s agent layer. The wrong comparison is feature count; the useful question is whether repository safeguards remain effective in either editor.

Can I use VS Code instead of Cursor?#

Yes. A correctly wired repository does not require Cursor to format, build, test, or review changes. You lose Cursor-specific agent behavior, but you should not lose the ability to produce valid code. If switching editors breaks validation, the repository was depending on local editor state.

Is Cursor VS Code free?#

Cursor and VS Code are separate products with separate terms and product offerings. Check the official Cursor documentation for Cursor’s current options. Do not assume that VS Code’s availability or licensing automatically applies to Cursor merely because Cursor uses the VS Code codebase.

Is cursor better than VS Code?#

Cursor is the stronger choice for developers who want an agent deeply integrated into editing and repository context. VS Code is sufficient when agent work happens through tools such as Claude Code or Codex. In both cases, tests, scripts, and tracked configuration—not the editor—must enforce correctness.