Claude Code

Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context features for Claude Code with the SonarQube CLI.

sonar integrate claude configures the SonarQube CLI to work alongside Claude Code. In an interactive terminal, the command prompts you to install each component:

• Secrets-detection hooks: a UserPromptSubmit hook that scans the prompt you send to Claude, and a PreToolUse hook that runs before Claude reads or writes files. Together they block any operation that would expose a secret.
• The SonarQube MCP Server, which lets Claude fetch projects, issues, and rules directly.
• Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): one prompt that installs Vortex analysis and Vortex context together. Accepting it adds:

  • A shared Vortex analysis PostToolUse hook that runs fast STANDARD analysis after each edit or write and forwards Bash, PowerShell, Monitor, and Read tool results to Vortex context when those hooks are available
  • A PostToolUseFailure hook that forwards failed Bash, PowerShell, Monitor, and Read tool calls to Vortex context when those hooks are available
  • End-of-turn Vortex analysis instructions in CLAUDE.md that tell Claude to run DEEP analysis on every file it modified in one command (multi --file or git change set)
  • SessionStart (startup and clear) and SubagentStart hooks that inject Vortex context when a session starts, letting Claude use project guidelines, architecture, semantic navigation, and dependency context

Pass --non-interactive to accept every offered component without prompts (see Non-interactive install).

Prerequisites

• The SonarQube CLI is installed and authenticated.
• Claude Code is installed.
• You're working inside a project directory, which lets the CLI auto-detect the SonarQube project for the preflight summary.

Install

Install once for this machine:

sonar integrate claude

The command writes hooks and config to ~/.claude/ and applies to every Claude Code session on this machine. See Project versus global scope.

Note: If you integrated Claude Code before Vortex context hooks were added, update to SonarQube CLI 1.8.0 or later, then run sonar integrate claude again to install them. Re-running also replaces a leftover Vortex context skill file (SKILL.md) from an earlier CLI version with the session-start hooks.

What the command does

The integrator runs in three phases:

1. Discovery and validation. It locates your project's config using the project key auto-detection chain and verifies the token.
2. Health check and repair. It calls SonarQube to confirm the token, organization, and project are valid. If the token is broken and you're running interactively, it offers to refresh it.
3. Installation. For each component (secrets hooks, MCP server, and Vortex when eligible), the CLI either prompts you to install it, skips it with an explanation, or accepts it automatically in non-interactive mode. Before writing files, it shows a What will be installed summary of accepted features. In interactive mode, press Enter to confirm. Then it installs accepted components into ~/.claude/.

   Common skip reasons include:

   • Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).

Options

Option	Description
--non-interactive	Non-interactive mode (no prompts).
--global, -g	Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope.

Where files are installed

Location	Hook and config
User home	~/.claude/ (hooks, settings, MCP config, and CLAUDE.md Vortex analysis instructions)
Shared binaries	~/.sonar/sonarqube-cli/bin/ (auxiliary binaries for secrets detection and Vortex context)

State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.

Restart Claude Code

Claude reads its hook and MCP configuration at startup. Restart Claude Code for the integration to take effect.

Vortex analysis and Vortex context

When you run sonar integrate claude against a SonarQube Cloud project, Vortex installs these Claude Code touchpoints:

• A single PostToolUse hook handles both Vortex analysis and Vortex context. After each edit or write, it runs fast STANDARD analysis and surfaces findings inline. After Bash, PowerShell, Monitor, or Read tool calls, it forwards results to Vortex context when those hooks are available. The CLI auto-detects the current git branch for each analysis when --branch is not passed.
• A PostToolUseFailure hook forwards failed Bash, PowerShell, Monitor, and Read tool calls to Vortex context when those hooks are installed.
• Instructions in CLAUDE.md require a mandatory end-of-turn DEEP run—one command covering every file Claude modified that turn (repeat --file for each path, or fall back to the git change set with --depth DEEP). Those instructions go in ~/.claude/CLAUDE.md. Branch context and project key are auto-detected: agents do not need to pass --branch or --project. If analysis reports that no project is configured, the instructions tell the agent to stay silent for the rest of the session instead of repeating a skip notice.
• SessionStart (startup and clear) and SubagentStart hooks inject Vortex context when a session starts, letting Claude use project guidelines, architecture, semantic navigation, and dependency context.

For overviews of these features, see Vortex analysis and Vortex context.

Verify it works

Test the secrets hook

1. Create a file in your project with a fake-looking but secret-shaped value:

   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";

2. Ask Claude to read it: "Read secrets.js."
3. Claude Code should block the read and explain that the file contains a secret.

Once you've confirmed the hook is active, delete the test file.

Test the MCP server

In Claude Code, ask: "Use the SonarQube MCP server to list my open projects." Claude should call SonarQube and return your project list. If it does not, run sonar auth status to confirm the underlying token is healthy and restart Claude.

Test Vortex analysis

In Claude Code, ask: "Run sonar analyze --staged and summarize new issues." Claude should invoke the CLI and report findings. This requires a Sonar Vortex subscription.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

sonar integrate claude --non-interactive

In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal; it installs every component that is not explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is configured correctly.

Uninstall

Run sonar integrate claude again in an interactive terminal. For each installed feature, the CLI asks Keep?: answer No, confirm Proceed with removal?, and the CLI removes hooks, instructions, and state for that feature. Vortex is removed as one unit (Vortex analysis and context hooks, CLAUDE.md instructions, and session-start hooks). See integrations/README.md for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the hook files written under ~/.claude/.
2. Remove the SonarQube MCP server entry from your Claude configuration.
3. Remove the integration entry from ~/.sonar/sonarqube-cli/state.json (under integrations.installed).

See Uninstalling for the full removal procedure.

Related pages

• Secrets detection

• Analyzing local changes

• State and storage