Claude Code VS Code, including the failure mode nobody documents

On this page#

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

What the integration actually does#

Claude Code in VS Code is a CLI agent connected to editor context—not an agent that lives inside the editor or silently understands your entire repository. The integration gives Claude Code access to the active selection, open files, diagnostics, and native diff views while its process still runs in a terminal with that terminal’s permissions and working directory.

That distinction matters because the editor and agent have separate sources of truth:

| Developers often assume | What actually happens | |---|---| | The open VS Code folder defines the agent’s repository | The terminal’s current working directory defines its starting scope | | An open file is automatically included in every prompt | Editor context can be available, but relevance still has to be established | | VS Code permissions control file access | The Claude Code process inherits terminal and operating-system permissions | | A visible diff proves the right worktree changed | The diff only represents files changed in the process’s actual filesystem | | The extension replaces the CLI | The editor integration complements the CLI |

Claude Code is Anthropic’s agentic coding tool: it can inspect a codebase, edit files, run commands, and work through multi-step changes. VS Code adds a better interaction surface, especially for selections and diffs. It does not erase repository boundaries, shell state, containers, remote hosts, or Git worktrees.

My position is simple: use the integration for navigation and review, but treat the terminal process as the authority. If you cannot identify its working directory, repository root, and execution environment, you do not have a trustworthy setup.

Photo by cottonbro studio on Pexels.

The wiring#

A reliable setup aligns four things: the VS Code workspace, integrated terminal, Claude Code process, and Git root. Wire those explicitly instead of trusting whichever directory or remote window happened to be open. The following setup is intentionally small because hidden automation makes failures harder to diagnose.

1. Open the repository root#

The VS Code workspace should represent the repository you intend the agent to modify. If you routinely open a parent directory containing several repositories, use a workspace file instead of asking the agent to infer which one matters.

{
  "folders": [
    {
      "name": "application",
      "path": "."
    }
  ]
}

Save that as a .code-workspace file at the repository root and open it deliberately. For a monorepo, the root should be the directory containing the shared Git boundary and project-wide instructions—not whichever package currently has your attention.

The official Claude Code documentation should remain the authority for installation and supported editor behavior. Repository wiring belongs to your team because only your team knows which directory, worktree, and invariants are authoritative.

2. Make new terminals start in the workspace#

The agent should begin in the same root that VS Code displays. Add this workspace setting:

{
  "terminal.integrated.cwd": "${workspaceFolder}"
}

Before starting Claude Code, verify the boundary:

pwd
git rev-parse --show-toplevel
git status --short

The first two paths should describe the same repository. The third command establishes a baseline so pre-existing changes are not mistaken for agent edits.

Now start Claude Code from that terminal:

claude

If the editor connection is not established automatically, use the Claude Code /ide command from the running session:

/ide

That explicit connection step is preferable when multiple VS Code windows are open. It forces you to notice which editor instance the session can actually see.

3. Put repository rules in versioned instructions#

VS Code settings should control editor behavior; repository instructions should control agent behavior. Keep durable constraints in the repository’s CLAUDE.md, where the team can review them like code.

# Repository constraints

- Preserve public API compatibility.
- Do not modify generated files directly.
- Run the narrowest relevant test before the full suite.
- Never rewrite an existing migration.
- Report any invariant that blocks the requested change.

Do not turn this file into a style guide dump. Include rules whose violation would make a technically working patch unacceptable.

If you need a stronger operating model for repository constraints, review the PairFoundry Agent Operating Kit. The point is not more prompting; it is making scope, validation, and handoff repeatable.

4. Define verification commands beside the rules#

Every instruction should point to an executable check where one exists. A generic template is enough:

## Verification

1. Run the test command for the changed package.
2. Run the repository type-check command.
3. Inspect `git diff --check`.
4. Review the final diff before reporting completion.

Replace descriptive placeholders with the repository’s real commands. Do not invent a universal npm test or equivalent: the correct command is whatever the repository already uses.

For broader setup patterns, use the Wiring It In collection. The other available implementation packs are summarized on the PairFoundry packs overview.

Photo by Lukas Blazek on Pexels.

The two things that break it#

Most broken setups reduce to one of two boundaries: the editor and agent are running in different execution environments, or they are attached to different repository roots. Reinstalling the extension may temporarily hide either problem, but it does not fix the underlying mismatch.

Failure 1: No available IDEs detected#

This error means the Claude Code process cannot discover a compatible VS Code instance in its own environment. The common cause is a boundary mismatch: VS Code is local while Claude Code runs over SSH, inside a container, or in a different subsystem—or the reverse.

Fix it in this order:

1. Identify whether the VS Code window is local, remote, or container-backed.
2. Open its integrated terminal.
3. Start claude inside that exact terminal.
4. Run /ide again.
5. Close unrelated VS Code windows if the target remains ambiguous.

The undocumented-looking failure mode is not “the extension is flaky.” It is namespace separation. A local editor and a remote process can display the same filenames while referring to different filesystems, sockets, permissions, or Git states. The integration cannot safely bridge an execution boundary merely because the paths look alike.

Anthropic’s Claude Code overview explains the tool’s agentic capabilities, but teams still need to define which environment owns execution. That decision cannot be delegated to editor discovery.

Failure 2: claude: command not found#

This error means the integrated shell cannot resolve the Claude Code executable. If the command works in an external terminal, VS Code probably inherited a different PATH, shell startup mode, user account, or remote environment.

Diagnose without guessing:

command -v claude
printf '%s\n' "$SHELL"
printf '%s\n' "$PATH"

Run those checks in both terminals and compare the results. Then fix the shell initialization or installation location that creates the difference, restart VS Code, and confirm command -v claude resolves inside the integrated terminal.

Do not solve this with a hard-coded machine-specific executable path in committed workspace settings. That configuration will fail for the second developer and conceal the actual environment contract.

Verifying it works#

A connected status indicator is insufficient. Verification must prove context flow, filesystem targeting, and diff visibility without risking a meaningful code change. Test all three before trusting the integration with a repository invariant.

Use this sequence:

1. Open a harmless tracked file and select a distinctive function or paragraph.
2. Ask Claude Code to explain only the selected material and identify its file.
3. Ask it to report the repository root before making changes.
4. Request a reversible one-line edit in a disposable branch or worktree.
5. Confirm the edit appears in VS Code’s diff view.
6. Run:

git status --short
git diff --check
git diff

7. Revert the verification edit through your normal Git workflow.

This catches a deceptive partial success: editor context can work while commands execute in the wrong directory, or filesystem edits can work while VS Code displays another worktree. A trustworthy setup requires both paths to converge.

If these checks expose gaps in your agent fundamentals, use PairFoundry’s free Foundations learning track before standardizing the workflow across a team.

Photo by Digital Buggu on Pexels.

Team considerations#

The second developer will inherit repository files, not your terminal state, installed executable, open window, or remote connection. A team-ready setup therefore versions only portable rules and documents every machine-local prerequisite separately.

Commit:

• CLAUDE.md with repository invariants and verification expectations.
• Portable .vscode/settings.json values such as the workspace terminal directory.
• A .code-workspace file when repository boundaries are otherwise ambiguous.
• Documentation naming the expected local, remote, or container execution model.

Do not commit:

• Absolute executable paths.
• Tokens, credentials, or personal environment variables.
• Assumptions about a developer’s shell profile.
• Generated editor state.
• Instructions that silently bypass tests or permission controls.

The handoff test is blunt: another developer should be able to open the documented workspace, start Claude Code, run /ide, identify the same Git root, and execute the same validation path. If that requires oral history, the integration is not team-ready.

Related reading#

• Claude Code marketplace: the wiring, and the two things that break it
• Getting Claude Code GitHub actions right the first time

FAQ#

Should Claude Code run locally when VS Code is connected to a remote repository?#

Run Claude Code in the environment that owns the repository files and executes its commands. For a remote or container-backed VS Code window, that normally means using the integrated terminal in that same environment. Splitting the editor and agent across environments creates discovery, path, and permission mismatches.

How is this different from simply following the official setup?#

The official setup establishes supported installation and editor integration. This workflow adds repository-level controls the vendor cannot define for you: the authoritative root, execution environment, invariants, verification commands, and handoff contract. Use the official documentation for product behavior and version your project-specific rules.

What should we do when the integration starts changing the wrong worktree?#

Stop the session before issuing more instructions. Check pwd, git rev-parse --show-toplevel, git status --short, and the path shown by VS Code. Reopen the intended workspace, create a fresh integrated terminal there, restart Claude Code, and reconnect with /ide.

When should a team avoid the VS Code integration?#

Avoid standardizing it when developers cannot run the editor and agent in the same trusted environment, repository validation is undefined, or sensitive commands rely on broad ambient credentials. Fix those operational boundaries first. An editor connection is convenience, not a substitute for access control or an executable acceptance process.

Can we roll back to terminal-only Claude Code?#

Yes. Close or disconnect the IDE integration and continue using Claude Code from the correct repository terminal, following the same versioned instructions and verification commands. Terminal-only use loses editor selections and native diff convenience, but it preserves the core agent workflow described in the Claude Code overview.