# OpenAI Codex

> **Warning:** This product is in Beta stage and we may release breaking changes.

`sonar integrate codex` configures the SonarQube CLI to work alongside [OpenAI Codex](https://openai.com/codex/). One command installs:

* **A secrets-detection hook**: a `UserPromptSubmit` handler that scans prompts for secrets before they are sent to Codex.
* **The SonarQube MCP server** so Codex can fetch projects, issues, and rules directly.
* **SonarQube Agentic Analysis instructions** (SonarQube Cloud only, when a project key is available and your organization is entitled) so Codex can run `sonar analyze` on your changes.
* **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.

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-developer-tools/sonarqube-cli/quickstart-guide.md).
* [Codex](https://developers.openai.com/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:

```bash
sonar integrate codex --project <YourProjectKey>
```

Or install once for your whole machine:

```bash
sonar integrate codex --global
```

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

### 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. |
| `--skip-context`  | Skip the Context Augmentation skill install.                                     |

### Where files are installed

| Scope             | Hook & config location                          |
| ----------------- | ----------------------------------------------- |
| `--global`        | `~/.codex/`                                     |
| 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](/sonarqube-developer-tools/sonarqube-cli/administration/state-and-storage.md).

> **Note:** **Agentic Analysis is project-scoped.** A global install does not enable Agentic Analysis instructions. Run `sonar integrate codex --project <key>` from a project directory to enable it for that project.

## Context Augmentation

When your SonarQube Cloud organization is entitled, a project-level `sonar integrate codex` installs a Context Augmentation skill that lets Codex pull project guidelines, architecture, semantic navigation, and dependency context through the CLI integration as it works.

Context Augmentation is project-scoped: a `--global` install skips it. Run `sonar integrate codex --project <YourProjectKey>` from a project directory to install the skill there, or pass `--skip-context` to opt out.

For a feature overview, see [Context Augmentation](/agent-centric-development-cycle/features/context-augmentation.md) in the Agent Centric Development Cycle documentation.

## 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 Agentic Analysis (SonarQube Cloud only)

In Codex, ask: *"Run `sonar analyze --staged` and summarize new issues."* This requires SonarQube Cloud and the Agentic Analysis entitlement on your organization.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Overview](/sonarqube-developer-tools/sonarqube-cli/integrations/integrations.md)
* [Analyzing local changes](/sonarqube-developer-tools/sonarqube-cli/analysis/analyzing-local-changes.md)
* [Commands reference](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/commands.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-developer-tools/sonarqube-cli/integrations/codex.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.