[JetBrains AI/Claude Agent] "The agent could not connect" and "Claude native binary not found for darwin-arm64" (macOS Apple Silicon)

Problem

In every Claude session inside the JetBrains AI/ACP integration, the UI shows:

The agent could not connect

In addition, the agent reports:

Claude native binary not found for darwin-arm64. Reinstall @anthropic-ai/claude-agent-sdk without --omit=optional, or set CLAUDE_CODE_EXECUTABLE.

Cause

The Claude ACP runtime is missing (or the IDE cannot locate) the Apple Silicon native binary (darwin-arm64). This prevents the agent process from starting, which surfaces as “The agent could not connect.”

In some environments, explicitly setting CLAUDE_CODE_EXECUTABLE to the claude binary path makes the IDE able to launch the agent.

Resolution

Follow the steps below in order (macOS, Apple Silicon):

1. Close the IDE.

2. Clear downloaded ACP runtimes:

   • Reopen the IDE.
   • Press Shift twice.
   • Run Clear Downloaded ACP Runtimes.

3. Restart the IDE.

4. Reinstall/update the Claude agent:

   • Go to Settings/Preferences → Tools → AI Assistant → Agents.
   • Reinstall or update Claude Agent.
   • On first launch, wait ~20 seconds for the runtime to download.
   • Click Reconnect and start a new session.

5. If the error persists, apply the workaround to explicitly point the IDE to the claude executable:

   • Launch the IDE with an environment variable set, e.g.:

     CLAUDE_CODE_EXECUTABLE=/path/to/claude idea
     

   • Or persist it for zsh (example):

     echo "export CLAUDE_CODE_EXECUTABLE=\"$(command -v claude)\"" >> ~/.zshrc
     

6. If it still fails, try clearing the Claude ACP cache folder (reported workaround):

   • In ~/Library/Caches/JetBrains/IntelliJIdea2026.2/acp-agents/claude-acp/, rename the version folders and retry launching the agent.

7. If none of the above resolves the issue:

   • Collect logs immediately after reproducing the failure: Help → Collect Logs and Diagnostic Data.
   • Provide IDE name/version (e.g., IntelliJ IDEA 2026.2.3) and the collected logs to JetBrains support and create issue on YouTrack