Codex CLI

Install the SonarQube plugin for the Codex CLI or Codex IDE extension to bring code analysis, issue management, and secrets detection into your AI coding sessions.

The SonarQube plugin for Codex CLI connects your AI coding agent to SonarQube's code quality and security features. It works with SonarQube Cloud or SonarQube Server.

Use the plugin from both the Codex CLI and the Codex IDE extension.

Features

Through the SonarQube CLI integration it sets up, the plugin adds:

• Secrets detection: a hook that scans prompts for secrets before they are sent to Codex, plus secrets-on-read instructions in .codex/AGENTS.md that tell Codex to refuse working with exposed tokens when it reads files.
• Vortex analysis (project-level installs with a Vortex subscription: SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 Enterprise and Data Center editions): a hook that runs after Codex edits files.
• Vortex context (project-level installs with a Vortex subscription: SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 Enterprise and Data Center editions): a skill that tells Codex to pull project guidelines before editing code, check dependencies before changing a manifest, and use SonarQube's architecture and semantic-navigation context as it works.

The plugin also gives the Codex agent access to the full set of Tools exposed by the SonarQube MCP Server, including:

• Code analysis: analyze code snippets and files in the agent context.
• Issues: search, review, and update code issues.
• Quality gates: check the quality gate status for a project.
• Security hotspots: search and review security hotspots.
• Coverage: find under-covered files and review line-by-line coverage.
• Dependencies: check third-party dependencies for SCA issues.

Prerequisites

• A SonarQube Cloud organization or SonarQube Server instance.
• OpenAI Codex installed.
• A container runtime (Docker, Podman, or nerdctl) to run the SonarQube MCP Server image.

Install

The SonarQube plugin is distributed through SonarSource's Codex plugin marketplace. Add that marketplace as a source in Codex, then install the plugin:

• From your shell, register the marketplace:

  codex plugin marketplace add SonarSource/sonarqube-agent-plugins

• Start a Codex session, run /plugins, search for sonarqube, and install it.

Configuration

After installing the plugin, finish setup by running the guided integration skill:

$sonar-integrate

The skill does the following:

1. Install the SonarQube CLI if not already present, or update it with sonar self-update.
2. Authenticate with SonarQube Cloud or your SonarQube Server instance via sonar auth login. Your browser opens to complete login; the token is stored in your system keychain.
3. Run sonar integrate codex, which prompts you to install each component: the secrets-detection hook, the secrets-on-read instructions in .codex/AGENTS.md, the SonarQube MCP Server, and, for project installs with a Vortex subscription, the Vortex analysis hook and Vortex context skill.

Sonar Vortex: analysis and context features

When you run sonar integrate codex, the command configures Codex to use the What is Sonar Vortex? features. They run through the SonarQube CLI:

• Vortex analysis: a hook runs after Codex edits files and surfaces findings inline.
• Vortex context: gives Codex your project's coding guidelines, dependency health, architecture, and semantic-navigation context as it works.

Both features are project-scoped and skipped on a global install. Run sonar integrate codex --project <YourProjectKey> from a project directory to install them, or pass --skip-context to opt out of Vortex context.

Verify that it works

Test the secrets hook

1. Restart Codex so the newly installed secrets-detection hook is active.
2. Compose a prompt to Codex that contains a fake-looking but secret-shaped value:

   Here is my key: sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13

3. Send the prompt.
4. Codex should block or refuse the operation and explain that the prompt contains a secret.

Test the MCP server

In Codex, ask: "List my SonarQube projects." Codex should call the SonarQube MCP server and return your project list. If it doesn't, run sonar auth status to confirm the underlying token is healthy and restart Codex.

Test Sonar Vortex

Vortex adds Vortex analysis and Vortex context. To confirm both are working, see Checking that Vortex works properly.

Non-interactive install

For provisioning scripts and onboarding automation, skip the interactive skill and run the SonarQube CLI directly:

sonar integrate codex --global --non-interactive

In non-interactive mode the CLI doesn't prompt. A --global install wires up the SonarQube MCP Server, the secrets-detection hook, and the secrets-on-read instructions, but skips the project-scoped Vortex analysis hook and Vortex context skill. Run sonar auth status afterward to confirm the integration is wired up. See OpenAI Codex in the SonarQube CLI docs for full details.

Usage

After setup, invoke SonarQube skills in Codex with $ commands or in natural language. Both options are shown for each skill.

List projects

$sonar-list-projects                    # all accessible projects
$sonar-list-projects my-project         # search by name or key

Or in natural language:

• "List my SonarQube projects."
• "Search for projects with auth in the name."

List issues

$sonar-list-issues                                        # issues in the current project
$sonar-list-issues my-project --severity CRITICAL

Or in natural language:

• "List the issues in my-project."
• "Show me critical issues in my-project."
• "Search issues in my-project on branch main."

Fix an issue

$sonar-fix-issue java:S1481 src/main/java/MyClass.java
$sonar-fix-issue python:S2077 src/auth/login.py:34

Or in natural language:

• "Fix the issue java:S1481 in src/main/java/MyClass.java."
• "Help me fix python:S2077 on line 34 of src/auth/login.py."

Quality gate

$sonar-quality-gate
$sonar-quality-gate my-project --branch main

Or in natural language:

• "Check the quality gate status for my-project."
• "Show me the quality gate for my-project on pull request 42."

Analyze a file

$sonar-analyze
$sonar-analyze src/auth/login.py

Or in natural language:

• "Analyze src/auth/login.py for code quality and security issues."
• "Run analysis on the current file."

Coverage

$sonar-coverage
$sonar-coverage my-project --max 50
$sonar-coverage my-project --file src/auth/login.py

Or in natural language:

• "What files in my-project have less than 50% coverage?"
• "Show me line-by-line coverage for src/auth/login.py."

Duplication

$sonar-duplication
$sonar-duplication my-project --pr 42
$sonar-duplication my-project --file src/auth/login.py

Or in natural language:

• "Find duplicated files in my-project."
• "Show duplications in my-project on pull request 42."

Dependency risks

Dependency risks require SonarQube Advanced Security.

$sonar-dependency-risks
$sonar-dependency-risks my-project --pr 42

Or in natural language:

• "List dependency risks in my-project."
• "Show me SCA issues on pull request 42."

Security hotspots

Access security hotspots through the same sonar-list-issues skill:

$sonar-list-issues my-project

Or in natural language:

• "Search security hotspots in my-project."
• "Show hotspots in my-project that are still to review."

Uninstall

To remove the SonarQube plugin from Codex CLI, start a Codex session, run /plugins, and remove the SonarQube plugin.

Uninstalling the plugin removes the skills and MCP wiring it registered. To also remove the underlying CLI integration files written by sonar integrate codex (the SonarQube MCP server entry, secrets-detection hook, and Vortex analysis hook), see OpenAI Codex in the SonarQube CLI docs.

Related pages

• SonarQube CLI integration with Codex
• Set up the SonarQube MCP Server in Codex