OpenAI Codex

Install secrets-detection hooks, the SonarQube MCP server, SonarQube Agentic Analysis, and Context Augmentation for OpenAI Codex in one command.

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.

• An Agentic Analysis hook (SonarQube Cloud only, project-level installs only, when your organization is entitled): a PostToolUse hook on apply_patch that runs Agentic Analysis after Codex edits files.

• A Context Augmentation skill (SonarQube Cloud only, project-level installs only, when enabled for your organization) 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 installs it automatically in non-interactive mode. Accepted components are written 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 entitled, 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.

Agentic Analysis and Context Augmentation

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. Once integrated, Codex verifies code changes against SonarQube Cloud after each apply_patch, with no further setup required.

For overviews of these features, see Agentic Analysis and Context Augmentation.

For detailed setup and operational directives, see Make your agent verify its code.

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, or token repair; scope defaults to project when you omit --global, and it installs every component that isn't explicitly skipped. When you authenticate with environment variables, integrate commands also run in non-interactive mode even without the flag. Run sonar auth status afterward to confirm everything is wired up.

Related pages

• Overview

• Analyzing local changes

• Commands reference