> 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/opencode.md).

# OpenCode

Install an OpenCode secrets plugin, the SonarQube MCP server, and Sonar Vortex analysis and Vortex context on your machine.

`sonar integrate opencode` installs a secrets-scanning plugin for [OpenCode](https://opencode.ai/) and configures the [SonarQube MCP server](https://github.com/SonarSource/sonarqube-mcp-server). On a connection with a Sonar Vortex subscription, it also offers [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).

In an interactive terminal, the command prompts you to install each component:

* A check before OpenCode reads a file (the `tool.execute.before` hook on the `read` tool). When the file contains a secret, the read is blocked.
* A check on each chat message (the `chat.message` hook) that masks each reported secret in the message, then still sends the message. The plugin also asks the model to tell you what was masked and to rotate any real credential.
* The SonarQube MCP server, which lets OpenCode fetch projects, issues, and rules.
* 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): one prompt that installs Vortex analysis and Vortex context. Accepting it adds:
  * A plugin that runs fast `STANDARD` analysis (see the `--depth` option of [`sonar analyze agentic`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-analyze-agentic)) after each `edit` or `write` and appends findings to the tool output. The edit is not blocked.
  * End-of-turn Vortex analysis instructions in `~/.config/opencode/AGENTS.md` that tell OpenCode to run `DEEP` analysis on every file it modified in one command (repeat `--file` for each path, or use the git change set)
  * A Vortex context skill at `~/.config/opencode/skills/sonar-context-augmentation/SKILL.md`, plus instructions in the same `AGENTS.md` file that tell OpenCode to load the skill and use `sonar context`

Choose OpenCode from the bare `sonar integrate` menu, or run `sonar integrate opencode` directly.

Pass `--non-interactive` to accept the secrets plugin, the MCP server, and Vortex when eligible without prompts (see [Non-interactive install](#non-interactive-install)).

## Prerequisites

* [The SonarQube CLI is installed and authenticated](/sonarqube-cli/quickstart-guide.md).
* [OpenCode](https://opencode.ai/) is installed.
* `sonar` is on the `PATH` that OpenCode uses. If the secrets plugin cannot run `sonar`, it blocks the file read or replaces the message instead of sending the original text.

## Install

Install once for this machine:

```bash
sonar integrate opencode
```

The command writes `~/.config/opencode/plugins/sonar-secrets.ts` and `~/.config/opencode/opencode.json`. When you accept Vortex, it also writes `~/.config/opencode/plugins/sonar-sqaa.ts`, `~/.config/opencode/skills/sonar-context-augmentation/SKILL.md`, and managed snippets in `~/.config/opencode/AGENTS.md`. See [Project versus global scope](/sonarqube-cli/integrations/integrations.md#project-versus-global-scope).

Earlier CLI versions wrote the secrets plugin as `~/.config/opencode/plugins/sonar.ts`. The CLI now writes it as `sonar-secrets.ts` and does not remove the old file, so delete `sonar.ts` if it exists.

The plugin files and the Vortex context skill are managed by the CLI. Do not edit them by hand. Re-run `sonar integrate opencode` to refresh the plugins, the skill, the Vortex instructions, and the MCP server entry. The command keeps your other keys in `opencode.json`.

### 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 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 plugin, 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. In interactive mode, press Enter to confirm. Then it writes the accepted files.

   A common skip reason is that 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).

### Secrets plugin

| OpenCode hook                       | What it does                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `tool.execute.before` (`read` only) | Scans the file before OpenCode reads it. A secret blocks the read.                                     |
| `chat.message`                      | Scans each text part. Secrets that can be masked are replaced in the message, and the message is sent. |

Both checks fail closed. When any of the following is true, the plugin blocks the file read or replaces the message instead of letting it through:

* You are not authenticated, or the secrets analyzer is missing
* The scan crashes or times out
* `sonar` is missing from `PATH`, or the plugin cannot read the hook response
* A secret in a message cannot be masked

When a message is blocked, the original text is replaced with a short placeholder and is not sent. The plugin asks the model to tell you the message was blocked.

A file read that is not the `read` tool is left unchanged. A message with no secrets is left unchanged.

> **Note:** A multi-line private key may only have its first line masked. The scanner reports that line, so the rest of the key can remain in the message until the scanner reports the full span.

### Vortex analysis

When you accept Vortex, `sonar integrate opencode` installs these OpenCode touchpoints:

* `~/.config/opencode/plugins/sonar-sqaa.ts` runs after `edit` and `write`. It analyzes that file at `STANDARD` depth and appends findings to the tool output. The hook never blocks the edit. A missing project, a scan error, or `sonar` missing from `PATH` stays silent. On HTTP 403, OpenCode can show the same unavailable notice as the other Vortex analysis hooks. See [integrations/README.md](/sonarqube-cli/integrations/integrations.md#when-vortex-is-no-longer-available).
* A managed snippet in `~/.config/opencode/AGENTS.md` requires an end-of-turn `DEEP` run: one `sonar analyze agentic --depth DEEP` command covering every file OpenCode modified that turn. The CLI auto-detects the project key and the current git branch, so the instructions omit `--project` and `--branch`. 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.

For an overview of Vortex analysis, see [Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md).

### Vortex context

OpenCode has no session-start hook. When you accept Vortex, the CLI installs Vortex context as a skill and instructions:

* `~/.config/opencode/skills/sonar-context-augmentation/SKILL.md` tells OpenCode how to call `sonar context` for this project's guidelines, architecture, navigation, and dependencies.
* A second managed snippet in `~/.config/opencode/AGENTS.md` tells OpenCode to load that skill at the start of a task that reads or changes code, to run `sonar context guidelines get` before writing or editing code, and to prefer `sonar context navigation` when locating symbols, callers, or usages. It also tells OpenCode to ask any subagent to load the skill first.

The CLI installs the Vortex context binary under `~/.sonar/sonarqube-cli/bin/`. After that, `sonar context` forwards to the binary.

> **Note:** OpenCode reads `AGENTS.md` and uses `CLAUDE.md` only when `AGENTS.md` is absent at that level. Installing Vortex creates `~/.config/opencode/AGENTS.md`, so OpenCode no longer reads `CLAUDE.md` at that level (for example `~/.claude/CLAUDE.md`). To keep those instructions, copy them into `~/.config/opencode/AGENTS.md`.

For an overview of Vortex context, see [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md).

### MCP server

The command adds a `sonarqube` entry under `mcp` in `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "sonarqube": {
      "type": "local",
      "command": ["sonar", "run", "mcp"],
      "enabled": true
    }
  }
}
```

OpenCode starts that local command. The file does not include a project key. `sonar run mcp` resolves the project when it runs.

The command leaves an existing `opencode.jsonc` file untouched. OpenCode merges `opencode.json` and `opencode.jsonc`, so comments in `opencode.jsonc` stay in place. Other keys in `opencode.json`, including other MCP servers, are kept.

When [`SONAR_USER_HOME`](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#cli-home-directory) is set before you run the command, the entry also includes an `environment` object with that path.

### 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        | What is written                                                                                                                                                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User home       | `~/.config/opencode/plugins/sonar-secrets.ts`, `~/.config/opencode/opencode.json`, and, when Vortex is installed, `~/.config/opencode/plugins/sonar-sqaa.ts`, `~/.config/opencode/skills/sonar-context-augmentation/SKILL.md`, plus snippets in `~/.config/opencode/AGENTS.md` |
| Shared binaries | `~/.sonar/sonarqube-cli/bin/` (the secrets analyzer, and the Vortex context binary when Vortex is installed)                                                                                                                                                                   |

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

## Restart OpenCode

OpenCode loads plugins and MCP configuration when it starts. Restart OpenCode after you install or remove them.

## Verify it works

### Test a file read

1. Create a file in your project with a fake-looking but secret-shaped value:

   ```javascript
   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";
   ```
2. Ask OpenCode to read it: *"Read secrets.js."*
3. OpenCode should block the read and explain that the file contains a secret.

After you've confirmed the plugin is active, delete the test file.

### Test a message

Send OpenCode a message that includes the same kind of fake token. The token should be masked before the message is sent, and OpenCode should tell you that a secret was masked.

### Test the MCP server

In OpenCode, ask: *"Use the SonarQube MCP server to list my open projects."* OpenCode should call SonarQube and return your project list. If it does not, run `sonar auth status` to confirm the token is healthy and restart OpenCode.

`sonar system status` lists the OpenCode integration and reports MCP server status as **CONFIGURED**, **NOT CONFIGURED**, or **CONFIGURED / INVALID CONFIG**. It does not print a separate secrets-hook health line for this plugin. When the MCP entry is invalid, status recommends `sonar integrate opencode`. See [Check system status](/sonarqube-cli/administration/system-status.md).

### Test Vortex analysis

Make a code change through OpenCode (for example, ask it to edit a file). After the edit, OpenCode should receive the analysis on the tool output. Before ending the turn, it should run `DEEP` analysis on the modified files. This requires a [Sonar Vortex analysis](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-analysis.md) subscription.

### Test Vortex context

After you accept Vortex, ask OpenCode to look up a coding guideline or a symbol in this project. It should load the `sonar-context-augmentation` skill and call `sonar context`. This requires a [Sonar Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) subscription.

## Non-interactive install

For provisioning scripts, dotfiles, and onboarding automation:

```bash
sonar integrate opencode --non-interactive
```

In non-interactive mode the CLI does not prompt for feature selection, install confirmation, token repair, or feature removal. When you authenticate with [environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md), integrate commands also run in non-interactive mode even without the flag. Every component that is not explicitly skipped is installed automatically, including Vortex when your connection has a Vortex subscription. 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 opencode` again in an interactive terminal. For each installed feature, the CLI asks **Keep?**: answer No, confirm **Proceed with removal?**, and the CLI removes that feature and its state. Remove the secrets plugin, Vortex, and the MCP server separately. Vortex is removed as one unit (the analysis plugin, the Vortex context skill, and the managed snippets in `AGENTS.md`). 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 `~/.config/opencode/plugins/sonar-secrets.ts`. If Vortex was installed, also delete `~/.config/opencode/plugins/sonar-sqaa.ts` and `~/.config/opencode/skills/sonar-context-augmentation/SKILL.md`. Also delete `~/.config/opencode/plugins/sonar.ts` if an earlier CLI left it there.
2. Remove the managed Vortex snippets from `~/.config/opencode/AGENTS.md` (analysis and context). Leave any other content in that file.
3. Remove the `sonarqube` entry under `mcp` in `~/.config/opencode/opencode.json`. Leave other keys, other MCP servers, and any `opencode.jsonc` file in place.
4. Remove the OpenCode 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>

* [Secrets detection](/sonarqube-cli/analysis/secrets-detection.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 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/opencode.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.