> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/integrations/codex.md).

# OpenAI Codex

`sonar integrate codex` configures the SonarQube CLI to work alongside [OpenAI Codex](https://openai.com/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**](https://docs.sonarsource.com/sonarqube-mcp-server/) so Codex can fetch projects, issues, and rules directly.
* Vortex (project-level installs when your connection has a Vortex subscription: SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 Enterprise and Data Center editions): one prompt that installs Vortex analysis and Vortex context together. Accepting it adds:
  * A [Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) `PostToolUse` hook on `apply_patch` that runs fast `STANDARD` analysis after Codex edits files
  * End-of-turn Vortex analysis instructions in `AGENTS.md` that tell Codex to run `DEEP` analysis on every file it modified in one command (multi `--file` or git change set)
  * A [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) skill 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](#non-interactive-install)).

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/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
```

> **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](/sonarqube-cli/integrations/integrations.md#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:** Vortex is project-scoped. It's skipped when you run `sonar integrate codex --global`; rerun the command without `--global` from a project directory to install Vortex for that project.

### What the command does

The integrator runs in three phases:

1. **Discovery and validation.** It locates your project's config using the [project key auto-detection](/sonarqube-cli/integrations/integrations.md#project-key-auto-detection) chain, 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, and Vortex 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](/sonarqube-cli/integrations/integrations.md#install-confirmation) 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).
   * Your connection doesn't have a Vortex subscription (only available with SonarQube Cloud Team or Enterprise plan, or SonarQube Server 2026.5 Enterprise and Data Center editions), or you used `--global` (it's project-scoped).

   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).                                               |

### Where files are installed

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

State for installed integrations is recorded in `~/.sonar/sonarqube-cli/state.json`. See [State and storage](/sonarqube-cli/administration/state-and-storage.md).

## Vortex analysis and Vortex context

When you run `sonar integrate codex` against a SonarQube Cloud project, Vortex installs these Codex touchpoints:

* A `PostToolUse` hook on `apply_patch` runs fast `STANDARD` analysis after each patch and surfaces findings inline. The CLI auto-detects the current git branch for each analysis when `--branch` isn't passed.
* Instructions in `AGENTS.md` require a mandatory end-of-turn `DEEP` run—one command covering every file Codex modified that turn (repeat `--file` for each path, or fall back to the git change set with `--depth DEEP`). Branch context is auto-detected the same way, so agents don't need to pass `--branch`.
* A Vortex context skill lets Codex retrieve project guidelines, architecture, semantic navigation, and dependency context through the CLI integration.

For overviews of these features, see [Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) and [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md).

## 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 Vortex analysis

Make a code change through Codex (for example, ask it to edit a file). After the patch, Codex should surface Vortex analysis findings inline. This requires a [Sonar Vortex](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) subscription.

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
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](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode without the flag. Run [`sonar auth status`](/sonarqube-cli/using-sonarqube-cli/commands.md#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. Vortex is removed as one unit (Vortex analysis hook, end-of-turn instructions, and Vortex context skill). See [integrations/README.md](/sonarqube-cli/integrations/integrations.md#removing-installed-features) 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](/sonarqube-cli/administration/uninstall.md) for the full removal procedure.

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.