> 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

Install secrets-detection hooks, the SonarQube MCP Server, and Vortex analysis and Vortex context features for OpenAI Codex with the SonarQube CLI.

`sonar integrate codex` configures the SonarQube CLI to work alongside [OpenAI Codex](https://openai.com/codex/). In an interactive terminal, the command shows these recommended components, then asks you to install them or customize the selection (see [Install confirmation](/sonarqube-cli/integrations/integrations.md#install-confirmation)):

* **A secrets-detection hook**: a `UserPromptSubmit` handler that scans prompts for secrets before they're 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/), which lets Codex fetch projects, issues, and rules directly.
* Vortex (when your connection has a Vortex subscription: SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions): installs Vortex analysis and Vortex context together. 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)
  * `SessionStart` (startup and clear) and `SubagentStart` hooks that inject [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) when a session starts, letting Codex use project guidelines, architecture, semantic navigation, and dependency context

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.

## Install

Install once for this machine:

```bash
sonar integrate codex
```

The command writes hooks and config to `~/.codex/` and applies to every Codex session on this machine. See [Project versus global scope](/sonarqube-cli/integrations/integrations.md#project-versus-global-scope).

Codex skips new or changed hooks until you trust them. This means the secrets-detection hook and, when installed, the Vortex analysis and Vortex context hooks might not run right after you install them. Review and trust the hooks when Codex asks, or run `/hooks` in the Codex CLI. If a prompt that contains a secret is not blocked, or Vortex findings do not appear, confirm that Codex trusts the hooks.

### What the command does

The integrator runs in two phases:

1. Validation. It checks that your saved token can reach SonarQube. On SonarQube Cloud, your connection must include an organization. An invalid token stops setup and tells you to run `sonar auth login`. An unreachable server stops setup and asks you to check the server URL and your network connection.
2. Installation. The CLI shows a [What will be installed](/sonarqube-cli/integrations/integrations.md#install-confirmation) summary of the recommended components (secrets hook, secrets-on-read instructions, MCP server, and Vortex when eligible). In an interactive terminal, choose **Install recommended** to write that set, or **Customize** to accept or decline each component and then press Enter. Components that are not available are skipped with an explanation. In non-interactive mode, every eligible component is installed without prompts. The CLI then writes the accepted components into `~/.codex/`.

   Common skip reasons include:

   * Your connection does not have a Vortex subscription (only available with SonarQube Cloud Team (annual) or Enterprise plan, or SonarQube Server 2026.5 or newer Enterprise and Data Center editions).

### Options

| Option              | Description                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--non-interactive` | Non-interactive mode (no prompts).                                                                                                 |
| `--global`, `-g`    | Deprecated since 1.9.0. The install is already global; using the flag prints a warning and does not change the installation scope. |

### Where files are installed

| Location        | Hook and config location                        |
| --------------- | ----------------------------------------------- |
| User home       | `~/.codex/` (hooks, `AGENTS.md`, `config.toml`) |
| 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` is not 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`). Those instructions go in `~/.codex/AGENTS.md`. Branch context is auto-detected, and each file is analyzed against the project that owns it, so agents do not need to pass `--branch` or `--project`. In a repository with several projects, the instructions tell Codex to run that command from a directory that contains every file changed in the turn, usually the repository root. Re-run `sonar integrate codex` so an existing snippet picks up that paragraph. The patch hook analyzes the change set the same way. If analysis reports that no project is configured, the instructions tell the agent to stay silent for the rest of the session instead of repeating a skip notice. See [Files and the project root](/sonarqube-cli/analysis/analyzing-local-changes.md#files-and-the-project-root).
* `SessionStart` (startup and clear) and `SubagentStart` hooks inject Vortex context when a session starts, letting Codex use project guidelines, architecture, semantic navigation, and dependency context. When context cannot load, Codex shows the warning in the UI once per session. A subagent start does not show it. See [When Vortex context does not load](/sonarqube-cli/integrations/integrations.md#when-vortex-context-does-not-load). If a previous install wrote `.agents/skills/sonar-context-augmentation/SKILL.md`, update to SonarQube CLI 1.8.0 or newer, then re-run `sonar integrate codex` to replace that leftover skill with the session-start hooks.

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

### Check the recorded installation

Run [`sonar system status`](/sonarqube-cli/administration/system-status.md#check-codex-installation-status). Codex is reported as **INSTALLED**, with the recorded installation path. When the managed requirements file contains Sonar hook commands, the next line names that file and lists those events. On macOS and Linux the file is `/etc/codex/requirements.toml`. On Windows it is `%ProgramData%\OpenAI\Codex\requirements.toml`.

### 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. If findings do not appear, confirm that Codex trusts the hooks. See [Install](#install).

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
sonar integrate codex --non-interactive
```

In non-interactive mode, the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal. Every component that is not 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 and choose **Customize**. 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 session-start hooks). 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/`.
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>

* [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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.