> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/integrations/claude-code.md). # Claude Code `sonar integrate claude` configures the SonarQube CLI to work alongside [Claude Code](https://claude.com/product/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**](https://docs.sonarsource.com/sonarqube-mcp-server/) so Claude can fetch projects, issues, and rules directly. * **A** [**Sonar Vortex agentic analysis**](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md) **hook** (SonarQube Cloud only, project-level installs only, when your organization is entitled): a `PostToolUse` hook that runs fast `STANDARD` agentic analysis after each edit or write. * **Sonar Vortex agentic analysis instructions** (SonarQube Cloud only, project-level installs only, when your organization is entitled): an end-of-turn protocol in `CLAUDE.md` that tells Claude to run `DEEP` analysis on every file it modified in one command (multi `--file` or git change set). * **A** [**Sonar Vortex context augmentation**](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md) **skill** (SonarQube Cloud only, project-level installs only, when your organization is entitled on an eligible SonarQube Cloud plan) 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](#non-interactive-install)). ## Prerequisites * [The SonarQube CLI is installed and authenticated](/sonarqube-cli/quickstart-guide.md). * [Claude Code](https://docs.claude.com/en/docs/claude-code/setup) 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: ```bash sonar integrate claude --project ``` Or install once for your whole machine: ```bash 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](/sonarqube-cli/integrations/integrations.md#project-versus-global-scope). > **Note:** Run the commands 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`: ```bash sonar integrate claude --project --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, agentic analysis instructions, and context augmentation 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](/sonarqube-cli/integrations/integrations.md#install-confirmation) summary of accepted features. In interactive mode, press Enter to confirm. Then it installs accepted components 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 available for your organization (requires an eligible SonarQube Cloud plan), 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 and `CLAUDE.md` (agentic analysis instructions) | | 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](/sonarqube-cli/administration/state-and-storage.md). ## Restart Claude Code Claude reads its hook and MCP configuration at startup. Restart Claude Code for the integration to take effect. ## Sonar Vortex: agentic analysis and context augmentation features When you run `sonar integrate claude` against a SonarQube Cloud project, the command installs two agentic analysis touchpoints: * A `PostToolUse` hook runs fast `STANDARD` analysis after each edit or write and surfaces findings inline. * 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`). For overviews of these features, see [Sonar Vortex agentic analysis](/agent-centric-development-cycle/verify/sonar-vortex-agentic-analysis.md) and [Sonar Vortex context augmentation](/agent-centric-development-cycle/guide/sonar-vortex-context-augmentation.md). ## Verify it works ### Test the secrets hook 1. Create a file in your project with a fake-looking but secret-shaped value: ```javascript // 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: ```bash sonar integrate claude --global --non-interactive ``` In non-interactive mode the CLI doesn't prompt for scope selection, feature selection, install confirmation, token repair, or feature removal; scope defaults to project when you omit `--global`, and it installs every component that isn't explicitly skipped. When you authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Run [`sonar auth status`](/sonarqube-cli/using-sonarqube-cli/commands.md#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. See [integrations/README.md](/sonarqube-cli/integrations/integrations.md#removing-installed-features) for the full flow. For a manual cleanup or non-interactive environments: 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](/sonarqube-cli/administration/uninstall.md) for the full removal procedure. ## Related pages * [Secrets detection](/sonarqube-cli/analysis/secrets-detection.md) * [Analyzing local changes](/sonarqube-cli/analysis/analyzing-local-changes.md) * [GitHub Copilot CLI](/sonarqube-cli/integrations/github-copilot-cli.md) * [State and storage](/sonarqube-cli/administration/state-and-storage.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-cli/integrations/claude-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.