JetBrains AI Assistant and CLAUDE.md/AGENTS.md: Integration Guide for IntelliJ, PyCharm, and WebStorm (2026)

JetBrains AI Assistant is the single plugin that powers AI features across IntelliJ IDEA, PyCharm, WebStorm, and the rest of the JetBrains IDE family — and as of 2026 it hosts two separate agents that read two separate configuration files: Junie, JetBrains’ own coding agent, reads AGENTS.md; Claude Agent, the Anthropic-built agent bundled into AI Assistant, reads CLAUDE.md. Neither of those is the same thing as JetBrains’ native Project Rules, a third, JetBrains-only convention that only affects AI Assistant’s chat mode.

If that sounds like three systems doing similar jobs, it is. This guide untangles which file goes where, verifies each claim against JetBrains’ own documentation, and walks through setup on IntelliJ IDEA, PyCharm, and WebStorm — which, because they share the same plugin architecture, are configured identically.

The Short Answer

Three Systems, Not One

The confusion around JetBrains and instruction files comes from conflating three genuinely different things that all live inside the same AI Assistant plugin:

1. Claude Agent is a third-party coding agent by Anthropic, made available for use inside AI Assistant’s chat interface. JetBrains’ own documentation states plainly: “Claude Agent reads instructions from the CLAUDE.md file in the root project directory.” This is the same file format used by the standalone Claude Code CLI — if your team already maintains a CLAUDE.md, the JetBrains-hosted Claude Agent reads it without modification. (JetBrains — Claude Agent)

2. Junie is JetBrains’ own autonomous coding agent. As of the June 2026 GA release, Junie is no longer a fully separate plugin — it is selectable as an agent inside AI Assistant’s chat, alongside Claude Agent, while also remaining available as a standalone plugin and CLI. Per JetBrains’ documentation: “Junie reads instructions from the AGENTS.md file in the root project directory, so you can keep them under version control and reuse them across the project.” (JetBrains — Junie Agent)

3. Project Rules are AI Assistant’s own native customization layer, unrelated to either file above. They live in .aiassistant/rules/*.md, are created and toggled from the IDE Settings UI, and only affect AI Assistant’s chat mode — not Junie’s or Claude Agent’s autonomous execution. JetBrains’ documentation describes these as helping “AI Assistant better understand your code, preferred tools, and coding conventions,” which is a materially different scope from a portable, cross-tool AGENTS.md. (JetBrains — Configure Project Rules)

The practical takeaway: CLAUDE.md and AGENTS.md are not competing with each other inside JetBrains — they belong to different agents. Project Rules compete with neither; they’re a JetBrains-only layer on top.

Step-by-Step Setup (IntelliJ IDEA, PyCharm, WebStorm)

IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, RubyMine, and Rider all share the same underlying IntelliJ Platform, so AI Assistant and Junie install and behave identically across all of them. The steps below apply verbatim to any of these IDEs.

Edition requirement: Junie requires a paid IDE edition — IntelliJ IDEA Ultimate, PyCharm Professional, and equivalents. WebStorm, GoLand, and the other specialized IDEs are paid-only by default, so this is a non-issue there. If you’re on IntelliJ IDEA Community or PyCharm Community, upgrade or trial Ultimate/Professional first.

Step 1: Install the AI Assistant plugin

1. Open Settings → Plugins.
2. Go to the Marketplace tab and search for “JetBrains AI Assistant.”
3. Click Install, then restart the IDE if prompted.

AI Assistant ships bundled in recent IDE releases, so on a current install you may already have it — check Settings → Plugins → Installed first.

Step 2: Authenticate

Open Settings → Tools → AI Assistant (or click the AI icon in the toolbar) and choose one of the supported activation paths:

• JetBrains AI subscription — the default path if your organization already pays for JetBrains AI.
• Bring your own API key — for Claude Agent, an Anthropic API key; Junie’s GA announcement confirms BYOK also works with OpenAI, Google, and other providers.
• Anthropic Console — a direct provider-level authentication path specific to Claude Agent.

Step 3: Select an agent in AI Chat

Open the AI Chat tool window and use the agent/model selector dropdown. This is where the CLAUDE.md vs AGENTS.md decision actually happens:

• Select Claude Agent to get CLAUDE.md-driven behavior.
• Select Junie to get AGENTS.md-driven behavior.

Step 4: Add the instruction file to your project root

For Claude Agent:

touch CLAUDE.md

For Junie:

touch AGENTS.md

Both go in the repository root — the same location Claude Code CLI, Cursor, and other tools already expect, so a project that supports multiple AI tools can share one AGENTS.md and, if using Claude Agent, an additional CLAUDE.md.

Step 5: Verify

Open AI Chat with the relevant agent selected and ask a question your instruction file uniquely answers — e.g., “What’s the test command for this project?” If the agent responds with your project’s actual command rather than a generic guess, the file is being read.

Configuration File Examples

Example: CLAUDE.md for a JetBrains + Claude Agent project

# CLAUDE.md

## Commands

\`\`\`bash
./gradlew build          # Full build
./gradlew test           # Unit tests
./gradlew ktlintCheck    # Kotlin lint
\`\`\`

## Code Style

- Kotlin, explicit API mode enabled on the `core` module
- No `!!` — use safe calls or `requireNotNull` with a message
- Constructor injection only; no field injection

## IDE Notes

- Run configurations live in `.idea/runConfigurations/` — do not hand-edit; regenerate via Gradle sync
- The debugger's "Evaluate Expression" tool is preferred over print-debugging for reviewing agent-proposed changes

Example: AGENTS.md for a JetBrains + Junie project

# AGENTS.md

## Commands

\`\`\`bash
npm run dev        # WebStorm-integrated dev server, port 5173
npm run test        # Vitest
npm run build        # Production build
\`\`\`

## Architecture

- `src/features/` — feature-scoped modules, one folder per feature
- `src/lib/api/` — all network calls; no `fetch()` outside this folder

## Constraints

- Do not modify `src/generated/` — it is regenerated from the OpenAPI schema via `npm run codegen`

Example: AI Assistant Project Rule (.aiassistant/rules/style.md)

# General Code Review Guidelines

## Naming
- Use clear, descriptive names for variables, functions, and classes
- Avoid single-letter names except for loop indices

## Style
- Keep line length reasonable (100–120 characters)
- Include comments for complex logic or important decisions

After creating the file, JetBrains’ documentation notes you then “switch to the created rule file in the editor and select the Rule type” from five options: Always (applied to every chat session automatically), Manually (invoked in chat with @rule: or #rule:), By model decision (applied when the model judges it relevant, based on an Instruction field you provide), By file patterns (applied when editing files matching a glob like *.kt or src/**), or Off.

Junie’s File Discovery Order

Junie’s own CLI documentation — which also governs the IDE-integrated agent when running deeper tasks — specifies this lookup order:

1. .junie/AGENTS.md in the project root
2. AGENTS.md in the project root
3. .junie/guidelines.md or the .junie/guidelines/ folder (legacy format, still supported for backward compatibility)

Junie additionally supports a global guidelines file at ~/.junie/AGENTS.md (or %USERPROFILE%\.junie\AGENTS.md on Windows) for personal or organization-wide preferences that apply across all your projects. When both global and project-level guidelines exist, Junie includes both in context — marked separately — with project-level guidelines taking precedence whenever the two conflict. Identical content between the two is deduplicated automatically. (Junie — Guidelines and Memory)

Claude Agent’s documentation does not describe an equivalent nearest-ancestor or monorepo-scoping mechanism — it specifies a single root-level CLAUDE.md.

JetBrains vs Claude Code, Cursor, and VS Code

The structural difference worth internalizing: Claude Code, Cursor, and (increasingly) JetBrains’ Junie all converge on AGENTS.md as the portable, cross-tool layer. CLAUDE.md and .aiassistant/rules/ are the two JetBrains-adjacent exceptions — one because it’s Claude-specific by design, the other because it was never meant to leave the IDE.

Common Pitfalls

• Wrong agent selected. The single most common failure mode: a team writes a careful CLAUDE.md, then has Junie selected in AI Chat by default and wonders why none of it is being applied. Check the agent dropdown before debugging the file itself.
• File placed in a module, not the repo root. In multi-module IntelliJ/Gradle or Maven projects, CLAUDE.md and AGENTS.md belong at the Git repository root — the same root Claude Code CLI or Cursor would expect — not inside an individual module directory, unless you are specifically relying on Junie CLI’s nearest-ancestor behavior with .junie/AGENTS.md.
• Assuming Project Rules replace AGENTS.md. Project Rules are real and useful for AI Assistant’s chat mode, but they do not transfer to Junie, Claude Agent, or any other tool. Don’t put cross-tool standards there.
• Community edition surprises. Junie silently isn’t available on IntelliJ IDEA Community or PyCharm Community — if the agent selector doesn’t show Junie, check your IDE edition before checking your config file.

FAQ

Does JetBrains AI Assistant read CLAUDE.md?

Yes, when the Claude Agent is selected inside AI Assistant’s chat. JetBrains’ documentation states Claude Agent “reads instructions from the CLAUDE.md file in the root project directory.” Junie, the other agent option, does not read CLAUDE.md — it reads AGENTS.md.

Does JetBrains AI Assistant read AGENTS.md?

Yes, through Junie. JetBrains documents this directly: Junie “reads instructions from the AGENTS.md file in the root project directory.” The standalone Junie CLI extends this with a more detailed lookup order (.junie/AGENTS.md, then root AGENTS.md, then legacy .junie/guidelines.md).

What’s the difference between Junie and Claude Agent in JetBrains IDEs?

Junie is JetBrains’ own coding agent, reads AGENTS.md, and is included with a JetBrains AI subscription (or BYOK with multiple providers). Claude Agent is Anthropic’s Claude Code agent made available inside AI Assistant, reads CLAUDE.md, and authenticates via JetBrains AI subscription, an Anthropic API key, or Anthropic Console. Both are selected from the same AI Chat agent dropdown.

What are JetBrains Project Rules, and how do they differ from AGENTS.md/CLAUDE.md?

Project Rules are a JetBrains-native format stored in .aiassistant/rules/*.md, configured through the IDE with five activation types (Always, Manually, By model decision, By file patterns, Off). They only affect AI Assistant’s chat mode — not Junie’s or Claude Agent’s autonomous execution — and they don’t travel to other AI tools the way AGENTS.md does.

Do IntelliJ IDEA, PyCharm, and WebStorm all support the same configuration files?

Yes. AI Assistant, Junie, and Claude Agent behave identically across the entire JetBrains IDE family (IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, RubyMine, RustRover, Rider) because they share the same IntelliJ Platform plugin architecture. The only variable is IDE edition: Junie requires Ultimate/Professional-tier editions and is unavailable on IntelliJ IDEA Community or PyCharm Community.

Do I need a JetBrains AI subscription to use CLAUDE.md with Claude Agent?

Not necessarily. A JetBrains AI subscription is one path, but Claude Agent also supports authenticating directly with an Anthropic API key or through Anthropic Console, independent of a JetBrains subscription.

Can I use both AGENTS.md and CLAUDE.md in the same JetBrains project?

Yes, and this is the recommended setup for teams whose developers switch between Junie and Claude Agent, or between JetBrains IDEs and other tools like Claude Code CLI or Cursor. Keep cross-tool, project-wide standards in AGENTS.md (which Junie, Cursor, and Claude Code all read), and use CLAUDE.md for anything specific to Claude’s agent behavior.

Related Articles

• CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md: Complete Syntax Reference (2026)
• GitHub Copilot Workspace and AGENTS.md: Does Copilot Workspace Read Your Config Files? (2026)
• AGENTS.md in Cursor: Complete Setup Guide (2026)

Secrets Management for JetBrains Projects

CLAUDE.md, AGENTS.md, and .aiassistant/rules/*.md files are all designed to be committed and shared across a team — which means none of them are safe places for API keys, database URLs, or service tokens, even when they’re just referenced as example values. It’s an easy mistake in an IDE-level workflow: a project rule mentions a staging endpoint, someone pastes a real key in “just for testing,” and it ships in the next commit alongside the rule update.

1Password CLI’s op run injects secrets into the environment at runtime instead, so your CLAUDE.md and AGENTS.md files can describe how a project authenticates without ever containing the credentials themselves — safe to commit, safe to share with Junie or Claude Agent, and safe to hand to any teammate who opens the project in IntelliJ IDEA, PyCharm, or WebStorm.