Sonar Vortex: context augmentation

Sonar Vortex's context augmentation features inject deep, repository-aware context into your AI agent's workflow, guiding code changes with architectural awareness and project-specific coding guidelin

Sonar Vortex's context augmentation features give your AI agent deep, project-specific context before it writes or edits code, so its output follows your repository's standards instead of being generic. Using these features requires a SonarQube Cloud Team (annual) or Enterprise plan, plus a separate subscription to the Sonar Agent Essentials product.

Overview

Context augmentation is the Guide phase of the Agent Centric Development Cycle. Agents can access these features through the SonarQube CLI-installed skill, or through a locally running SonarQube MCP Server that connects to SonarQube Cloud.

Core capabilities

• Architectural awareness: Helps agents navigate complex class hierarchies, trace upstream/downstream call flows, and understand execution paths.
• Intelligent guidelines: Automatically injects relevant coding rules, quality standards, and security requirements based on your project's history and the current task.
• Semantic navigation: Moves beyond simple text matching to retrieve code based on its actual meaning and structure using Abstract Syntax Trees (AST), semantics, and control flow information.
• Third-party dependency guidance: Helps agents assess the health and safety of third-party dependencies before they're introduced or updated.

Tool categories

Context augmentation provides four capability categories. For supported agents, the recommended setups are the SonarQube agent plugin and the SonarQube CLI, which install an agent skill that uses the local context augmentation tool. To expose the same capabilities as MCP tools, configure a locally running SonarQube MCP Server that connects to SonarQube Cloud. Each category currently supports a specific set of languages, and we're actively expanding language coverage and adding more categories.

Category	Description	Supported languages
Coding guidelines	Recommends Sonar rules to follow, based on the project's historical SonarQube issues filtered by what the agent is about to do (prompt nature and categories).	All SonarQube Cloud languages
Third-party dependency health and safety	Assesses whether a third-party dependency is healthy and safe to use before it's introduced or updated. Currently covers known security vulnerabilities, supply-chain malware, and license compliance, with more checks in progress. Available only with the SCA feature.	All SCA-supported languages and package managers
Architecture	Exposes the current architecture graph and user-defined architectural constraints, so the agent understands the current architecture and stays aligned with the intended design.	All languages supported by Architecture
Semantic navigation	Helps the agent understand the meaning of the code rather than relying on text-based grep, by exposing call stacks, class hierarchies, references, and exact source locations. This lets the agent navigate the codebase and modify the right places effectively.	Java, C#, JavaScript, TypeScript, Python, and Rust

With the agent plugin or SonarQube CLI setup, the installed skill tells the agent to access these capabilities through the SonarQube CLI: it retrieves coding guidelines before writing or editing code, checks third-party dependencies before changing a manifest or lockfile, and prefers SonarQube's semantic-navigation tools over plain-text search.

Context augmentation for coding guidelines

The guidelines tool injects relevant Sonar rules into the LLM context:

• Based on your prompt: for example, if the user prompt involves access to DB, include all guidelines about DB.
• Based on the SonarQube issues found in files modified or related to the LLM task: for example, if the LLM plans to modify DBStorage.java, include guidelines from past issues in DBStorage.java.

Diagram showing how the guidelines tools combine prompt classification from Sonar Rules with historically relevant issues from past analysis to augment the LLM context.

Context augmentation for architecture

The architecture tools give the LLM understanding of both the current architecture and the user-defined intended constraints, powered by semantic data from SonarQube Cloud's Architecture feature. These tools enable the LLM to:

• Build "the right thing", better aligning with user goals, avoiding mistakes and rework.
• Build "the thing right", provide an output that is in line with architecture expectations.

Diagram showing how the architecture tools expose the intended and current architecture to the LLM, based on SonarQube's architecture analysis configuration and results.

Context augmentation for semantic navigation

The semantic-navigation tools give the agent an understanding of the code's meaning, helping it find the right locations to modify based on meaning rather than text. With this context, the agent can:

• Reach the correct solution faster by jumping straight to the right symbols, references, types, call flows, class hierarchies, etc.
• Reduce token usage and cost, by avoiding blind reads of entire files.
• Produce safer, less buggy changes, by surfacing every relevant location that needs updating so nothing is missed.

Diagram showing how the semantic-navigation tools (code structure, code flow, and code search) expose context to the LLM, based on the universal dependency graph built from the local workspace.

Guide-and-verify loop

Using context augmentation together with agentic analysis allows you to build a guide-and-verify loop to ensure pull requests pass quality gates the first time, leading to faster code reviews with no back-and-forth. The loop has three steps:

1. Guide: Context augmentation injects architectural awareness and coding guidelines into the LLM context before it writes or edits code.
2. Verify: Agentic analysis verifies the resulting code with full CI-level precision.
3. Loop: The LLM refines the code based on analysis results and repeats until quality gates pass.

Setup

To learn how to set up context augmentation, see Add context to generate better code.

Related pages

• Guide your agents with context
• MCP Server
• Tools