Claude Code JetBrains: what to check before you trust the connection

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#

The Claude Code JetBrains integration connects a Claude Code process to the IDE context you already have open. It improves context sharing, navigation, diagnostics, and diff review; it does not move the agent into JetBrains, grant unlimited repository access, or make generated changes safe by default.

Claude Code is an agentic coding tool that can inspect a codebase, propose changes, edit files, and run approved commands. JetBrains remains the editor and inspection surface; Claude Code remains the agent process.

| What engineers often assume | What the connection actually provides | |---|---| | The JetBrains plugin contains the agent | The plugin bridges JetBrains to a separately running Claude Code session | | The active editor is the complete task context | Editor state is useful context, but repository instructions and explicit prompts still matter | | A displayed diff proves the change is correct | The diff proves only what changed | | IDE diagnostics replace repository validation | Diagnostics cover configured IDE analysis, not every build, test, generated-file, or CI invariant | | Once connected, every terminal session uses the IDE | The relevant Claude Code session must establish the connection |

That boundary matters in a real repository. A clean-looking edit can still violate an architectural rule, change generated output incorrectly, or skip a validation command that exists only in CI.

Treat the integration as a higher-bandwidth control surface—not a trust transfer. The official Claude Code documentation explains the supported product behavior; your repository must define what counts as an acceptable change.

Photo by cottonbro studio on Pexels.

The wiring#

The reliable setup is simple: install the official integration, start Claude Code from the JetBrains project’s integrated terminal, connect that session to the IDE, and verify the repository root before assigning work. Starting elsewhere and hoping the plugin discovers the intended project is the wrong operating model.

1. Install the official Claude Code plugin in JetBrains.

   Use JetBrains’ plugin settings and confirm that the installed plugin is the official Claude Code integration. Do not treat a similarly named third-party plugin as equivalent.

2. Open the actual repository as the JetBrains project.

   For a monorepo, open the root whose instructions, build files, and version-control boundary should govern the task. Opening one package while running the agent at the monorepo root creates an ambiguous review surface.

3. Start Claude Code in the integrated terminal.

cd /absolute/path/to/repository
claude

The important configuration is the working directory. It should be explicit, reproducible, and aligned with the project open in JetBrains.

4. Connect the running session to JetBrains.

/ide

Select the intended JetBrains instance or project when prompted. If the correct target is not listed, stop here; choosing a plausible-looking target creates a connection that appears healthy while exposing the wrong editor context.

5. Give the agent the repository contract before the implementation request.

Before editing, identify the repository root, applicable instruction files,
validation commands, generated-file boundaries, and the smallest change set.
Do not modify files until you have summarized those constraints.

6. Make the first task deliberately narrow.

Inspect the currently relevant code and propose a minimal patch.
Show the files you expect to change and the validation you will run.
Wait for approval before editing.

This is where the connection becomes an operating practice rather than a convenience. PairFoundry’s Agent Operating Kit is the direct next step if you need reusable repository contracts and handoff patterns; the foundations track covers the underlying workflow without requiring a pack.

The two things that break it#

Most failed setups reduce to two faults: Claude Code cannot see a compatible JetBrains connection, or the IDE and agent are attached to different repository contexts. Fix discovery first, then prove root alignment; reinstalling everything before distinguishing those cases usually wastes time and preserves the actual mistake.

“No available IDEs detected”#

This means the Claude Code session cannot discover a usable IDE connection. It is not evidence that the repository is unsupported, and repeatedly issuing /ide will not repair a plugin that is absent, disabled, or unavailable to that process.

Fix it in this order:

1. Confirm the official plugin is installed and enabled.
2. Restart JetBrains after installation or enablement.
3. Open the repository in JetBrains.
4. Start a fresh Claude Code session from that project’s integrated terminal.
5. Run /ide again and select the exact project.

If Claude Code works in an external terminal but not the integrated terminal, compare how claude is resolved:

command -v claude

A missing result means the integrated shell does not inherit the same executable path. Fix the shell environment used by JetBrains; do not create a random duplicate installation merely to silence the error. Return to the official documentation if the supported connection flow itself has changed.

It connects, but the context or diffs are wrong#

This is more dangerous because nothing visibly “fails.” The agent may run from one directory while JetBrains displays another project, producing irrelevant context, incomplete diffs, or edits outside the reviewer’s expected scope.

Check both roots explicitly:

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

Then compare the reported root with the project open in JetBrains. If they differ, exit the session, change to the intended root, start Claude Code again, and reconnect with /ide.

Do not solve this by telling the agent to “remember” the correct directory. Process working directory and IDE project identity are wiring, not prompt preferences. The broader Wiring It In collection covers this distinction across agent workflows.

Photo by Christina Morillo on Pexels.

Verifying it works#

A valid connection must pass three checks: context reaches the intended Claude Code session, edits appear in the expected JetBrains project, and repository validation succeeds independently of the IDE. A connected indicator or successful /ide response proves transport, not correctness, scope, or readiness to merge.

Use a reversible acceptance check:

1. Open a distinctive symbol or small method in JetBrains.
2. Ask Claude Code to identify the relevant file and explain the selected code without editing.
3. Request one trivial, reviewable change.
4. Confirm the diff appears against the expected file.
5. Inspect repository state independently.

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

Then run the repository’s documented formatter, tests, type checks, or build commands. Do not invent generic substitutes: a passing IDE inspection does not prove that the project’s real validation path passed.

Also test negative boundaries. Ask the agent which files it must not modify, whether generated artifacts are present, and what validation it cannot perform. A trustworthy workflow makes missing coverage visible.

The Claude Code overview describes the agent’s capabilities, but capability is not an acceptance criterion. Your repository’s invariants remain authoritative.

Team considerations#

A second developer will usually fail on hidden local assumptions: a different project root, shell environment, plugin state, instruction set, or validation path. Team adoption is ready only when another engineer can reproduce the connection and acceptance checks from repository-controlled guidance rather than copying one person’s machine.

Commit the workflow contract where contributors will find it. It should state:

• Which directory is the supported agent root.
• Which repository instructions apply.
• Which files are generated or restricted.
• Which commands must pass before handoff.
• Which changes require human approval.
• How to disconnect, discard an unwanted patch, and restart cleanly.

Do not commit personal executable paths, IDE-specific local state, credentials, or assumptions about one developer’s JetBrains installation. Keep machine setup separate from repository invariants.

A practical handoff record is short:

Scope:
Files changed:
Invariant protected:
Validation run:
Validation not run:
Open risks:

For a broader standardized rollout, compare the three available approaches on PairFoundry’s packs overview. The key decision is not whether every developer prefers the same agent; it is whether Claude Code, Codex, Cursor, or another tool must obey the same repository contract.

Photo by Lukas Blazek on Pexels.

Related reading#

• Claude Code Xcode — a setup that survives a second developer
• Claude Code browser extension: what to check before you trust the connection

FAQ#

When should I avoid the Claude Code JetBrains connection?#

Avoid it when the repository root is unclear, validation depends on unavailable systems, or the task touches sensitive or generated files without documented boundaries. The integration increases context bandwidth, so ambiguous scope becomes more dangerous—not less—and a terminal-only, read-only inspection is the safer starting point.

Is this different from the official JetBrains Claude Code setup?#

No replacement setup is being proposed. The official plugin and /ide connection remain the supported mechanism; the added steps are acceptance controls around root alignment, repository instructions, validation, and handoff—areas that product connectivity alone cannot define for your codebase.

What should every teammate configure locally?#

Each developer needs the official integration, a working Claude Code executable in the JetBrains terminal environment, and the correct project open. Repository root, restricted paths, and validation commands should not be personal configuration; record those as shared project guidance.

How do I back out when the connection edits the wrong files?#

Stop further agent actions, inspect git status and the full diff, then revert only the unwanted changes using your normal version-control workflow. Do not run a broad destructive reset when unrelated work is present; restart Claude Code from the correct root and reconnect before continuing.

Can a team mix jetbrains claude code with other coding agents?#

Yes, provided the repository contract is agent-neutral. Standardize scope, prohibited files, approval points, validation commands, and handoff evidence; do not standardize around one plugin’s connected indicator, because that says nothing about whether another developer can safely review or continue the change.