> 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/agent-centric-development-cycle/developer-tools/agent-plugins/codex-cli.md). # Codex CLI The SonarQube plugin for Codex CLI connects your AI coding agent to SonarQube's code quality and security data through the [About the MCP Server](/sonarqube-mcp-server/about-the-mcp-server.md). SonarQube does the analysis; Codex calls the MCP tools and acts on the results. Once installed and configured, Codex can run SonarQube analysis on your code, list and fix issues, check quality gates, inspect coverage and duplication, and run [Agentic Analysis](/agent-centric-development-cycle/verify/agentic-analysis.md). The plugin also configures the SonarQube CLI to detect secrets, keeping credentials out of your prompts and the files the agent reads or writes. The plugin works with SonarQube Cloud or SonarQube Server. You can use the plugin from both the Codex CLI and the Codex IDE extension. ## Features The plugin gives the Codex agent access to the full set of [Tools](/sonarqube-mcp-server/reference/tools.md) exposed by the SonarQube MCP Server, including: * Code analysis: analyze code snippets and files in the agent context. * Issues: search, review, and update code issues. * Quality gates: check the quality gate status for a project. * Security hotspots: search and review security hotspots. * Coverage: find under-covered files and review line-by-line coverage. * Dependencies: check third-party dependencies for SCA issues. Through the SonarQube CLI integration it sets up, the plugin also adds: * Secrets detection: a `UserPromptSubmit` hook that scans prompts for secrets before they are sent to Codex, plus secrets-on-read instructions in `.codex/AGENTS.md` that tell Codex to refuse working with exposed tokens when it reads files. * Agentic Analysis (SonarQube Cloud only, project-level installs): a `PostToolUse` hook on `apply_patch` that runs Agentic Analysis after Codex edits files. ## Prerequisites * A SonarQube Cloud organization or SonarQube Server instance. * [OpenAI Codex](https://developers.openai.com/codex/) installed. * A container runtime (Docker, Podman, or nerdctl) to run the SonarQube MCP Server image. ## Install The SonarQube plugin is distributed through SonarSource's Codex plugin marketplace. Add that marketplace as a source in Codex, then install the plugin: * From your shell, register the marketplace: ```bash codex plugin marketplace add SonarSource/sonarqube-agent-plugins ``` * Start a Codex session, run `/plugins`, search for `sonarqube`, and install it. ## Configuration After installing the plugin, finish setup by running the guided integration skill: ``` $sonar-integrate ``` The skill does the following: 1. Install the SonarQube CLI if not already present, or update it with `sonar self-update`. 2. Authenticate with SonarQube Cloud or your SonarQube Server instance via `sonar auth login`. Your browser opens to complete login; the token is stored in your system keychain. 3. Run `sonar integrate codex`, which prompts you to install each component: the secrets-detection hook, the secrets-on-read instructions in `.codex/AGENTS.md`, the SonarQube MCP Server, and, for SonarQube Cloud project installs, the Agentic Analysis hook and Context Augmentation skill. ## Agentic Analysis and Context Augmentation On SonarQube Cloud, `sonar integrate codex` wires up SonarQube Cloud's [Agentic Analysis](/agent-centric-development-cycle/verify/agentic-analysis.md) and [Context Augmentation](/agent-centric-development-cycle/guide/context-augmentation.md) features: the Agentic Analysis hook runs after each `apply_patch`, and the Context Augmentation skill lets Codex pull project guidelines, architecture, semantic navigation, and dependency context as it works. Both features are project-scoped and skipped on a global install. Run `sonar integrate codex --project ` from a project directory to install the Agentic Analysis hook and the Context Augmentation skill for that project, or pass `--skip-context` to opt out of Context Augmentation. To enable these features and configure Codex to use them effectively, see [Make your agent verify its code](/agent-centric-development-cycle/verify/how-to-guides/make-your-agent-verify-its-code.md). ## Verify that it works ### Test the secrets hook 1. Restart Codex so the newly installed secrets-detection hook is active. 2. Compose a prompt to Codex that contains a fake-looking but secret-shaped value: ``` Here is my key: sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13 ``` 3. Send the prompt. 4. Codex should block or refuse the operation and explain that the prompt contains a secret. ### Test the MCP server In Codex, ask: *"List my SonarQube projects."* Codex should call the SonarQube MCP server and return your project list. If it doesn't, 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 Codex applies the patch, it should surface Agentic Analysis findings inline. This requires SonarQube Cloud and the Agentic Analysis entitlement on your organization. ## Non-interactive install For provisioning scripts and onboarding automation, skip the interactive skill and run the SonarQube CLI directly: ```bash sonar integrate codex --global --non-interactive ``` In non-interactive mode the CLI does not prompt. A `--global` install wires up the SonarQube MCP Server, the secrets-detection hook, and the secrets-on-read instructions, but skips the project-scoped Agentic Analysis hook and Context Augmentation skill. Run `sonar auth status` afterward to confirm the integration is wired up. See [OpenAI Codex](/sonarqube-cli/integrations/codex.md) in the SonarQube CLI docs for full details. ## Usage After setup, invoke SonarQube skills in Codex with `$` commands or in natural language. Both options are shown for each skill. ### List projects ``` $sonar-list-projects # all accessible projects $sonar-list-projects my-project # search by name or key ``` Or in natural language: * "List my SonarQube projects." * "Search for projects with `auth` in the name." ### List issues ``` $sonar-list-issues # issues in the current project $sonar-list-issues my-project --severity CRITICAL ``` Or in natural language: * "List the issues in `my-project`." * "Show me critical issues in `my-project`." * "Search issues in `my-project` on branch `main`." ### Fix an issue ``` $sonar-fix-issue java:S1481 src/main/java/MyClass.java $sonar-fix-issue python:S2077 src/auth/login.py:34 ``` Or in natural language: * "Fix the issue `java:S1481` in `src/main/java/MyClass.java`." * "Help me fix `python:S2077` on line 34 of `src/auth/login.py`." ### Quality gate ``` $sonar-quality-gate $sonar-quality-gate my-project --branch main ``` Or in natural language: * "Check the quality gate status for `my-project`." * "Show me the quality gate for `my-project` on pull request 42." ### Analyze a file ``` $sonar-analyze $sonar-analyze src/auth/login.py ``` Or in natural language: * "Analyze `src/auth/login.py` for code quality and security issues." * "Run analysis on the current file." ### Coverage ``` $sonar-coverage $sonar-coverage my-project --max 50 $sonar-coverage my-project --file src/auth/login.py ``` Or in natural language: * "What files in `my-project` have less than 50% coverage?" * "Show me line-by-line coverage for `src/auth/login.py`." ### Duplication ``` $sonar-duplication $sonar-duplication my-project --pr 42 $sonar-duplication my-project --file src/auth/login.py ``` Or in natural language: * "Find duplicated files in `my-project`." * "Show duplications in `my-project` on pull request 42." ### Dependency risks Dependency risks require SonarQube Advanced Security. ``` $sonar-dependency-risks $sonar-dependency-risks my-project --pr 42 ``` Or in natural language: * "List dependency risks in `my-project`." * "Show me SCA issues on pull request 42." ### Security hotspots Access security hotspots through the same `sonar-list-issues` skill: ``` $sonar-list-issues my-project ``` Or in natural language: * "Search security hotspots in `my-project`." * "Show hotspots in `my-project` that are still to review." ## Uninstall To remove the SonarQube plugin from Codex CLI, start a Codex session, run `/plugins`, and remove the SonarQube plugin. Uninstalling the plugin removes the skills and MCP wiring it registered. To also remove the underlying CLI integration files written by `sonar integrate codex` (the SonarQube MCP server entry, secrets-detection hook, and Agentic Analysis hook), see [OpenAI Codex](/sonarqube-cli/integrations/codex.md) in the SonarQube CLI docs. ## Related pages * [OpenAI Codex](/sonarqube-cli/integrations/codex.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/agent-centric-development-cycle/developer-tools/agent-plugins/codex-cli.md?ask=&goal= ``` `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.