OpenAI Codex

Install secrets-detection hooks, the SonarQube MCP server, and Sonar Vortex's agentic analysis and context augmentation features for OpenAI Codex with the SonarQube CLI.

sonar integrate codex configures the SonarQube CLI to work alongside OpenAI Codex. In an interactive terminal, the command prompts you to install each component:

• A secrets-detection hook: a UserPromptSubmit handler that scans prompts for secrets before they are sent to Codex.
• Secrets-on-read instructions in .codex/AGENTS.md that tell Codex to refuse working with exposed tokens when it reads files.
• The SonarQube MCP server so Codex can fetch projects, issues, and rules directly.
• A Sonar Vortex agentic analysis hook (SonarQube Cloud only, project-level installs only, when your organization is entitled): a PostToolUse hook on apply_patch that runs DEEP change-set analysis after Codex edits files.
• A Sonar Vortex context augmentation skill (SonarQube Cloud only, project-level installs only, when your organization is entitled on an eligible SonarQube Cloud plan) so Codex 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.
• Codex 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 codex --project <YourProjectKey>

Or install once for your whole machine:

sonar integrate codex --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.

Warning: --project and --global are mutually exclusive. Passing both causes the command to fail with an "invalid options" error (exit code 2).

Note: Agentic analysis is project-scoped. It's skipped when you run sonar integrate codex --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 codex --global; rerun the command without --global from a project directory to install the context augmentation skill there.

To configure OpenAI Codex without context augmentation, pass --skip-context:

sonar integrate codex --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 hook, secrets-on-read instructions, MCP server, agentic analysis hook, 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 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.

   If global Codex instructions already exist and you run a project install, the CLI asks whether you also want a project-local copy of the secrets-on-read instructions.

Options

Option	Description
--project, -p	SonarQube project key. Mutually exclusive with --global.
--global, -g	Install hook and config globally to ~/.codex instead of the project directory.
--non-interactive	Non-interactive mode (no prompts).
--skip-context	Skip the context augmentation skill install.

Where files are installed

Scope	Hook & config location
--global	~/.codex/ (hooks, AGENTS.md, config.toml)
Project (default)	Inside the repo's Codex configuration directory
Shared binaries	~/.sonar/sonarqube-cli/bin/

State for installed integrations is recorded in ~/.sonar/sonarqube-cli/state.json. See State and storage.

Sonar Vortex: agentic analysis and context augmentation features

When you run sonar integrate codex against a SonarQube Cloud project, the command also installs a PostToolUse hook so Codex can use SonarQube Cloud's agentic analysis. After each apply_patch, the hook runs DEEP analysis on the git change set and surfaces findings inline. The CLI auto-detects the current git branch for each analysis when --branch isn't passed.

For overviews of these features, see Sonar Vortex agentic analysis and Sonar Vortex context augmentation.

Verify it works

Test the secrets hook

1. Compose a message to Codex that contains a fake secret. For example, paste a credential-like string directly into your prompt.
2. Send the prompt.
3. Codex should block or refuse the operation and explain that the prompt contains a secret.

Test the MCP server

Ask Codex to list your SonarQube projects via the MCP server. If the call fails, run sonar auth status to confirm the underlying token is healthy and restart Codex.

Test agentic analysis (SonarQube Cloud only)

Make a code change through Codex (for example, ask it to edit a file). After the patch, Codex should surface agentic analysis findings inline. This requires SonarQube Cloud and the agentic analysis entitlement on your organization.

Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

sonar integrate codex --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. Every component that isn't explicitly skipped is installed automatically. When you authenticate with environment variables, integrate commands also run in non-interactive mode without the flag. Run sonar auth status afterward to confirm everything is configured correctly.

Uninstall

Run sonar integrate codex 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 for the full flow.

For a manual cleanup or non-interactive environments:

1. Delete the hook files written under ~/.codex/ (global) or in your project's Codex configuration (project).
2. Remove the SonarQube MCP server entry from your Codex configuration.
3. Remove the integration entry from ~/.sonar/sonarqube-cli/state.json (under integrations.installed).

See Uninstalling for the full removal procedure.

Related pages

• Overview

• Analyzing local changes

• Commands reference