Make your agent verify its code

How to set up a verification loop to ensure your agent reanalyzes the code it writes or modifies and fixes the detected issues.

This guide walks you through setting up Sonar Vortex's agentic analysis features to ensure your agent verifies the code it writes or modifies.

Using these features requires a SonarQube Cloud Team (annual) or Enterprise plan, plus a separate subscription to the Sonar Agent Essentials product.

Several setups are available. Choose the one that best fits your workflow:

• Claude Code with SonarQube CLI
• Codex CLI
• GitHub Copilot
• Cursor
• Antigravity
• SonarQube MCP Server

General prerequisites

Before proceeding, ensure you meet the following prerequisites.

SonarQube Cloud admin settings

Agentic analysis is enabled in your SonarQube Cloud organization's admin settings.

Project settings

Ensure that your project is:

• Connected to SonarQube Cloud.
• Analyzed in your CI pipeline on a long-lived branch.

Warning: Make sure your project is analyzed in SonarQube Cloud at least once after the agentic analysis service is enabled for the organization.

Claude Code

Set up agentic analysis with Claude Code.

Use the SonarQube CLI and the SonarQube plugin for Claude Code to enable agentic analysis in your Claude sessions. Once configured, Claude automatically runs SonarQube’s remote analysis after edits and surfaces findings directly in the chat. Also trigger agentic analysis on-demand with the SonarQube CLI.

Option 1: Install with the SonarQube plugin

Prerequisites specific to this setup

Make sure you have Claude Code installed on your machine.

Step 1: Install the SonarQube plugin in Claude Code

Inside a Claude Code session:

1. Run /plugin in Claude Code, open the Discover tab, and install sonarqube from the official Claude plugin marketplace.
2. Reload SonarQube’s skills and hooks in Claude:

   • Either restart Claude Code, or
   • Run /reload-plugins if your version supports it.

After reload, you should see skills such as:

• /sonarqube:sonar-integrate
• /sonarqube:sonar-analyze

These commands use the CLI and the SonarQube MCP server that you configure in the next step.

Step 2: Run the integration skill

From a Claude session opened in your project folder, run the SonarQube integration skill and specify your SonarQube Cloud project key:

/sonarqube:sonar-integrate

The skill does the following:

• Checks and updates the SonarQube CLI and authenticates to it.
• Wires Claude Code via sonar integrate claude . This command:

  • Registers the SonarQube MCP server for Claude Code.
  • Installs secrets-scanning hooks.
  • Installs agentic analysis hooks for Claude (SQAA).

At the end of the flow, you should see a summary similar to:

SonarQube integration is ready. MCP + hooks: registered globally via sonar integrate claude Secrets scanning: hooks installed Authentication: token stored in system keychain Restart Claude Code if the SonarQube MCP tools don't appear immediately. You can safely rerun /sonarqube:sonar-integrate later to refresh CLI and wiring if needed.

Step 3: Check that the agentic analysis hook is active

After you're done integrating, restart Claude to initialize the agentic analysis hook. You should see a line that confirms the agentic analysis is configured:

SessionStart:startup says: SonarQube plugin initialised.
       sonarqube-cli: ✓ found
       SonarQube hooks: ✓ Secrets Detection, Agentic Analysis

Step 4: Test the setup

Once setup is complete, trigger agentic analysis by asking Claude to edit a file in your project. For example, from a Claude Code session opened in your repo:

Open src/module.js and generate a basic class.

In a successful setup, you'll see in the Claude transcript or logs:

• A tool call that edits the file (for example, applying a patch or write operation).
• A follow-up hook that sends the changed file to SonarQube and reports any new issues.

Option 2: Install with the SonarQube CLI

Use this option to configure Claude Code directly from your terminal. This is useful when you're automating installations with scripts.

Prerequisites specific to this setup

Make sure you have:

• Claude Code installed on your machine.
• SonarQube CLI installed and authenticated.

Step 1: Run the integration command

From your project folder, run:

sonar integrate claude --project <YourProjectKey>

This command configures Claude Code for the current project. It does the following:

• Registers the SonarQube integration for Claude Code.
• Installs the required hooks for agentic analysis.
• Binds the integration to the project key you provide.

Step 2: Restart and check that the agentic analysis hook is active

After restart, you should see a line that confirms agentic analysis is configured:

SessionStart:startup says: SonarQube plugin initialised.
       sonarqube-cli: ✓ found
       SonarQube hooks: ✓ Secrets Detection, Agentic Analysis

Step 3: Test the setup

Ask Claude to edit a file in your project. For example:

Open src/module.js and generate a basic class.

Codex CLI

Set up agentic analysis with Codex CLI and the SonarQube plugin.

Prerequisites specific to this setup

Make sure you have OpenAI Codex installed on your machine.

Step 1: Install the SonarQube plugin

From your shell, register the SonarSource plugin marketplace:

codex plugin marketplace add SonarSource/sonarqube-agent-plugins

Then start a Codex session, run /plugins, search for sonarqube, and install it.

For more information, see Codex CLI.

Step 2: Run the integration skill

From a Codex session opened in your project folder, run the SonarQube integration skill:

$sonar-integrate

The skill installs the SonarQube CLI if needed, authenticates it, and runs sonar integrate codex. This installs a hook that runs agentic analysis after Codex edits files.

Step 3: Restart Codex

Restart Codex so the integration is loaded for the current project.

Step 4: Test the setup

Ask Codex to edit a file in your project. After Codex applies the patch, it should run agentic analysis and surface any new findings. This requires SonarQube Cloud and the agentic analysis entitlement on your organization.

GitHub Copilot

Set up agentic analysis with GitHub Copilot CLI and the SonarQube plugin.

Prerequisites specific to this setup

Make sure you have GitHub Copilot CLI installed on your machine.

Step 1: Install the SonarQube plugin

From your shell, run:

copilot plugin install sonarqube@awesome-copilot

For more information, see GitHub Copilot.

Step 2: Run the integration skill

From a Copilot CLI session opened in your project folder, run the SonarQube integration skill:

/sonar-integrate

The skill installs the SonarQube CLI if needed, authenticates it, and runs sonar integrate copilot. This installs instructions that tell Copilot to run sonar analyze agentic on modified files before ending the turn. Findings are returned in the turn response rather than injected mid-conversation.

Step 3: Restart GitHub Copilot CLI

Restart GitHub Copilot CLI so the integration is loaded for the current project.

Step 4: Test the setup

Ask Copilot's agent to edit a file in your project. At the end of the turn, before sending its final response, Copilot should run agentic analysis on modified files and surface any new findings. This requires SonarQube Cloud and the agentic analysis entitlement on your organization.

Cursor

Set up agentic analysis with Cursor's agent and the SonarQube plugin.

Prerequisites specific to this setup

Make sure you have:

• Cursor installed on your machine.
• SonarQube CLI installed and authenticated.

Step 1: Install the SonarQube plugin

In Cursor's chat, run:

/add-plugin sonarqube

For more information, see Cursor.

Step 2: Authenticate

In your terminal, run:

sonar auth login

Step 3: Run the integration command

From your project folder, run:

sonar integrate cursor --project <YourProjectKey>

This command installs an always-applied rule in .cursor/rules/ that tells Cursor to run sonar analyze agentic on the git change set at the end of a turn. Cursor uses the same instructions-based pattern as GitHub Copilot: findings are returned in the turn response rather than injected mid-conversation.

Step 4: Restart Cursor

Restart Cursor so the integration is loaded for the current project.

Step 5: Test the setup

Ask Cursor's agent to edit a file in your project. At the end of the turn, before sending its final response, Cursor should run agentic analysis on the git change set and surface any new findings. This requires SonarQube Cloud and the agentic analysis entitlement on your organization.

Antigravity

Set up agentic analysis with Antigravity and the SonarQube plugin.

Prerequisites specific to this setup

Make sure you have Antigravity installed on your machine.

Step 1: Install the SonarQube plugin

From your shell, run:

agy plugin install https://github.com/SonarSource/sonarqube-agent-plugins

For more information, see Antigravity.

Step 2: Run the integration skill

From an Antigravity session opened in your project folder, run:

/sonarqube:sonar-integrate

The skill installs the SonarQube CLI if needed, authenticates it, and runs sonar integrate antigravity. This installs instructions that tell Antigravity to run sonar analyze agentic on modified files before ending the turn. Antigravity uses the same instructions-based pattern as GitHub Copilot: findings are returned in the turn response rather than injected mid-conversation.

Step 3: Restart Antigravity

Restart Antigravity so the integration is loaded for the current project.

Step 4: Test the setup

Ask Antigravity to edit a file in your project. Before ending the turn, Antigravity should run agentic analysis and surface any new findings. This requires SonarQube Cloud and the agentic analysis entitlement on your organization.

SonarQube MCP Server integration

This integration configures the SonarQube MCP Server to expose the agentic analysis MCP tools to your AI agent.

Note: If you plan to use agentic analysis together with context augmentation, you must use a self-hosted SonarQube MCP Server. The SonarQube-hosted MCP servers, SonarQube Cloud-hosted and SonarQube Server-hosted, don't support context augmentation tools.

Integration steps

Step 1: Export the SonarQube token environment variable

Export the SONARQUBE_TOKEN Common variables with a valid Personal Access Token (PAT) for your project.

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{<YourUserToken>}"

Step 2: Add or edit your MCP configuration file

MCP settings files are located at the following paths:

• .cursor/mcp.json for Cursor IDE
• .mcp.json for Claude Code
• ~/.gemini/config/mcp_config.json for Antigravity
• .codex/config.toml for Codex

  • use a TOML config instead of JSON
• .vscode/mcp.json for Copilot in Visual Studio Code

Note: Replace the placeholders above with appropriate values:

• Paths must be absolute: Relative paths like ./ or ../ are not accepted.

  • ⚠️ The path format is critical.
• Windows users:

  • Use forward slashes. Example: C:/Users/john/projects/myapp
  • Don't use back slashes. Example: C:\\Users\\john\\projects\\myapp

The SONARQUBE_TOOLSETS value determines which MCP toolsets are enabled. The configuration below enables the analysis and projects toolsets required for agentic analysis.

{
  "mcpServers": {
    "sonarqube-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "sonarsource/sonarqube-mcp"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "<YourOrganizationKey>",
        "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
        "SONARQUBE_TOOLSETS": "analysis,projects"
      }
    }
  }
}

Note: Optional configurations:

• Enable context augmentation: To also enable context augmentation, change SONARQUBE_TOOLSETS to "cag,projects,analysis".
• Include default SonarQube MCP tools: To include the default SonarQube MCP tools in addition to the Agentic Workflow tools, change the SONARQUBE_TOOLSETS value to: "analysis,issues,projects,quality-gates,rules,duplications,measures,security-hotspots,dependency-risks,coverage,cag".
• Read-only volume mounting of the project workspace: The project workspace can be mounted in read-only mode by specifying ro instead of rw. Some tools may work in degraded mode.

Step 3: Configure agent operational constraints (recommended)

Tool usage can be inconsistent depending on available tools, context, and agent behavior. To ensure the agent follows the Guide-and-Verify workflow consistently, explicitly guide your AI agent to use the agentic analysis tools appropriately.

Add the directive to your agent's system prompt or instructions file.

Example directive:

Note: The example below covers the full Guide-and-Verify workflow. If you are only using agentic analysis without context augmentation, you can remove the GUIDE Phase section.

# SonarQube Agentic Workflow - Usage Directive (MUST FOLLOW)

**Always use the Guide-and-Verify workflow** for writing and modifying code.

## GUIDE Phase - Before Writing or Editing Code

**Before writing or editing code** you MUST:
1. Call `get_guidelines` for project context and coding standards
2. Locate existing code with `search_by_signature_patterns` or `search_by_body_patterns`
3. Read implementation with `get_source_code`

**When changing architecture or dependencies** you MUST:
- Check `get_current_architecture` and `get_intended_architecture`
- Analyze impact using:
  - `get_upstream_call_flow` / `get_downstream_call_flow` - trace method calls
  - `get_references` - find all usages
  - `get_type_hierarchy` - check inheritance

**Before adding or updating a third-party dependency** you MUST:
- Call `check_dependency` with the package URL (purl) to check for vulnerabilities, malware, and license compliance

## VERIFY Phase - After Writing or Editing Code

You must strictly follow this Analyze-Then-Commit workflow for every code modification. No code is considered complete until it has passed the following SonarQube validation loop:

1. **Read Phase:** After any modification or before commit, use the `Read` tool to load the current state of all relevant source files.
2. **Analysis Phase:** For every new or modified file, you must call `run_advanced_code_analysis` using:
   - `filePath`: The project-relative path to the file (e.g., `src/main/java/MyClass.java`)
   - `branchName`: The active development branch
   - `fileScope`: `["MAIN"]` or `["TEST"]` depending on the code type
3. **Evaluation & Remediation:**
   - **Rule Lookup:** For every issue flagged, call `show_rule` with the specific rule key (e.g., `java:S1874`)
   - **Mandatory Fixes:** You are prohibited from committing code with **CRITICAL** or **HIGH** issues. Implement fixes based on the rule's rationale and recommended guidance immediately.
4. **Verification:** After applying fixes, re-run the analysis to ensure issues are resolved and no regressions were introduced.

Step 4: Restart your agent

Restart your agent and make sure that your MCP configuration is taken into account and applied correctly.

Step 5: Verify your setup

1. Ask your agent "What is Guide and Verify?" You should see a description of the SonarQube Agentic workflow as configured in step 3.

Example response

 "Guide & Verify" is a workflow defined in your project's CLAUDE.md file for writing and modifying code. It has two phases:
                                                                                                                                                                                                                                                 
  GUIDE Phase (before writing code):                                                                                                                                                                                                             
  - Fetch project guidelines and coding standards via get_guidelines                                                                                                                                                                             
  - Locate existing code using search tools                                                                                                                                                                                                      
  - Read the relevant implementation via get_source_code                                                                                                                                                                                       
  - For architectural changes: check current/intended architecture, trace call flows, find usages, inspect type hierarchies

  VERIFY Phase (after writing code):
  1. Read — reload all modified source files
  2. Analyze — run run_advanced_code_analysis on each changed file against the active branch
  3. Evaluate & Fix — look up flagged rules with show_rule, and mandatory fix any CRITICAL or HIGH severity issues before committing
  4. Re-verify — re-run analysis to confirm fixes and check for regressions

  In short, it's a SonarQube-backed quality gate that requires you to understand existing code before touching it and validate every change with static analysis before considering it done.

1. Ask your agent "Verify the file path/to/file.java." You should see it invoke the run_advanced_analysis tool (it might ask for confirmation). You should see a report of which issues are currently present in the file, broken down by severity.

Example response

Here is a summary of the 21 issues found:                                                                                                                                                                                                      
                                                                                                                                                                                                                                                 
  ---                                                                                                                                                                                                                                            
  Analysis Results                                                                                                                                                                                                                               
                                                                                                                                                                                                                                                 
  CRITICAL / HIGH — None
                                                                                                                                                                                                                                                 
  No blocking issues were found. The file is safe to commit as-is from a severity standpoint.                                                                                                                                                    
                                                                                                                                                                                                                                                 
  ---                                                                                                                                                                                                                                            
  Medium Issues                                                                                                                                                                                                                                  

  java:S107 — Too many constructor parameters (line 137)
  The private OrderSequence(...) constructor has 14 parameters, exceeding the limit of 7. This is a common pattern for immutable value objects using the "wither" pattern, but SonarQube flags it nonetheless. Refactoring would require
  introducing a builder, which is a non-trivial API change.

  java:S3358 — Nested ternary (line 720)
  ref == null ? List.of("") : List.of(ref.getName())
  Inside an already-ternary expression. Should be extracted into a variable or helper method.

  ---
  Low / Info Issues

  java:S1133 — Deprecated code not yet removed (lines 66, 256, 269)
  The type field and the getType() / withType() methods are annotated @Deprecated with a scheduled removal at 8.0. SonarQube reminds you to eventually remove them.

  java:S1123 — Missing @deprecated Javadoc tag (line 66)
  The type field is annotated with @Deprecated but its Javadoc comment does not include a @deprecated tag explaining the migration path.

  java:S1874 — Use of deprecated type field (lines 124, 154, 173, 193, 213, 233, 351, 389, 449, 485, 523, 560, 600, 637, 673) — 15 occurrences
  Every internal usage of the deprecated type field triggers this rule. These will all be resolved once type is removed in 8.0.

  ---
  Summary

  ┌───────────────┬───────┬───────────────────────┐
  │   Severity    │ Count │        Action         │
  ├───────────────┼───────┼───────────────────────┤
  │ CRITICAL/HIGH │ 0     │ None required         │
  ├───────────────┼───────┼───────────────────────┤
  │ Medium        │ 2     │ Optional improvement  │
  ├───────────────┼───────┼───────────────────────┤
  │ Low/Info      │ 19    │ Track for 8.0 cleanup │
  └───────────────┴───────┴───────────────────────┘

  The file is clean from a blocking-issue perspective. The medium-severity nested ternary at line 720 is the only quick improvement worth considering now. Everything else is tracked for the 8.0 deprecation removal cycle.

Direct SonarQube CLI calls

Use the SonarQube CLI when you want to trigger agentic analysis directly from the command line.

Prerequisites

You've installed SonarQube CLI and authenticated to SonarQube Cloud. See Quickstart guide for more information.

Run the analysis

To trigger agentic analysis with SonarQube CLI, use the sonar analyze agentic SonarQube CLI command from your project's folder:

sonar analyze agentic --file <PathToFile> --project <YourProjectKey> --branch <BranchName>

Parameters

• --file : Project-relative or absolute path to a file you want to analyze. Repeatable: pass --file more than once to analyze several files in a single run. Omit it to analyze your local change set.
• --depth (optional): Analysis depth, either STANDARD (each file analyzed on its own) or DEEP (adds cross-file taint analysis). Defaults to STANDARD for a single --file, and DEEP for multiple files or a change set.
• --project : Explicit project key if the CLI cannot infer it from the current directory or your integration.
• --branch (optional): Branch name whose CI context should be used. Defaults to the current branch if not specified.

For the full option list, see sonar analyze agentic in the SonarQube CLI documentation.

Example: Analyze a TypeScript file on the default branch

sonar analyze agentic --file src/app.ts

This triggers agentic analysis on src/app.ts using the latest CI analysis context for the linked project and branch.

Note: Agentic analysis uses the same rules and quality profiles as your CI analysis.

API calls

To run agentic analysis without integrating with the SonarQube CLI or SonarQube MCP Server, call the agentic analysis API directly.

Calling the agentic analysis API

To trigger an agentic analysis through an API call, send a POST request to https://api.sonarcloud.io/a3s-analysis/analyses.

Provide the following parameters in your request:

Parameters

projectKey (key, required) The key of your project (go to your project > Information to find it). branchName (string, required) Branch name used to retrieve the latest analysis context. filePath (string, required) Project-relative path of the file to analyze (e.g., "src/main/java/MyClass.java"). fileContent (string, required) The original content of the file to analyze. fileScope (string, optional) Defines in which scope the file originates from (main or test code): "MAIN" or "TEST". Default is "MAIN".

Example with curl

Here is an example of an API call using curl:

curl -X 'POST' \
  'https://api.sonarcloud.io/a3s-analysis/analyses' \
  -u '<YourSonarQubeCloudPersonalAccessToken>:' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationKey": "<YourOrganizationKey>",
    "projectKey": "<YourProjectKey>",
    "branchName": "main",
    "filePath": "<FilePath>",
    "fileContent": "<FileContent>",
    "fileScope": "MAIN"
  }'