Claude Code

Install secrets-detection hooks, the SonarQube MCP server, SonarQube Agentic Analysis, and Context Augmentation for Claude Code in one command.

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 so Claude can fetch projects, issues, and rules directly.

• An Agentic Analysis hook (SonarQube Cloud only, project-level installs only, when your organization is entitled): a PostToolUse hook that wires the CLI into Claude's tool-use cycle so Agentic Analysis runs on your changes.

• A Context Augmentation skill (SonarQube Cloud only, project-level installs only, when enabled for your organization) so Claude can retrieve project guidelines, architecture, semantic navigation, and dependency context through the CLI integration.

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 (or you're installing globally with --global).

Install

Run inside the project you want to integrate, with the project key:

sonar integrate claude --project <YourProjectKey>

Or install once for your whole machine:

sonar integrate claude --global

Note: In an interactive terminal, if you omit both --global and --project, the CLI asks whether to install for this project or globally before continuing. See Project versus global scope.

Note: You can run this in either order: install per-machine first (--global) and then per-project, or the other way around. When a global hook is detected during a project install, the per-project secrets hook is skipped to avoid duplicate scans.

Note: Agentic Analysis is project-scoped. It's skipped when you run sonar integrate claude --global; rerun the command without --global from a project directory to install the Agentic Analysis hook for that project.

Note: Context Augmentation is project-scoped. It's skipped when you run sonar integrate claude --global; rerun the command without --global from a project directory to install the Context Augmentation skill there.

To configure Claude Code without Context Augmentation, pass --skip-context:

sonar integrate claude --project <YourProjectKey> --skip-context

What the command does

The integrator runs in three phases:

1. Discovery and validation. It locates your project's config (sonar-project.properties, .sonarlint/connectedMode.json, the git origin remote when the repository is bound on SonarQube, or the explicit --project flag) 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, Agentic Analysis hook, and Context Augmentation when eligible), the CLI either prompts you to install it, skips it with an explanation, or installs it automatically in non-interactive mode. Accepted components are written into either the project directory or your home directory, depending on --global.

   Common skip reasons include:

   • A global secrets hook is already configured (the project-level hook is skipped to avoid duplicate scans).

   • Agentic Analysis isn't available on your connection (SonarQube Server), your organization isn't entitled, or you used --global (it's project-scoped).

   • Context Augmentation isn't entitled, you passed --skip-context, or you used --global.

Where files are installed

Scope	Hook & config location
--global	~/.claude/ (hooks, settings, MCP config)
Project (default)	Inside the repo's .claude/ directory
Shared binaries	~/.sonar/sonarqube-cli/bin/ (auxiliary binaries for secrets detection and Context Augmentation)

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.

Agentic Analysis and Context Augmentation

When you run sonar integrate claude against a SonarQube Cloud project, the command also installs a PostToolUse hook so Claude Code can use SonarQube Cloud's Agentic Analysis. After integration, Claude Code verifies code changes against SonarQube Cloud after edits, with no further setup required.

For overviews of these features, see Agentic Analysis and Context Augmentation.

For detailed setup and operational directives, see Make your agent verify its code.

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 doesn't, run sonar auth status to confirm the underlying token is healthy and restart Claude.

Test Agentic Analysis (SonarQube Cloud only)

In Claude Code, ask: "Run sonar analyze --staged and summarize new issues." Claude should invoke the CLI and report findings. This requires SonarQube Cloud and the Agentic Analysis entitlement on your organization.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

sonar integrate claude --global --non-interactive

In non-interactive mode the CLI doesn't prompt for scope selection, feature selection, or token repair; scope defaults to project when you omit --global, and it installs every component that isn't 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 wired up.

Uninstall

The CLI has no dedicated uninstall command for integrations yet. To remove the Claude integration:

1. Delete the hook files written under ~/.claude/ (global) or .claude/ (project).

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 scanning

• Analyzing local changes

• GitHub Copilot

• State and storage

• Claude Code