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

# Orphaned integration files

Leftover per-project SonarQube integration files the automatic migration to global-only integrations cannot detect or convert, and how to remove them.

This page applies when a repository contains SonarQube-related files that your machine's CLI state has no record of. Follow the steps below to identify and remove them safely.

These files might include a `.claude/`, `.cursor/`, `.codex/`, or `.github/` folder containing SonarQube hooks or configuration, a Git hook running SonarQube checks, or a coding assistant referencing SonarQube instructions. These steps apply equally to a developer inspecting an unfamiliar repository and to an AI coding agent tasked with identifying and cleaning up such files.

`sonar integrate` now always installs at the global level, and every integration lives in your home directory instead of inside a repository. The CLI no longer accepts `--project`/`-p` on `sonar integrate`; `--global`/`-g` is still accepted for compatibility, but it's deprecated and a no-op because the install is already global. The first time you run a supported CLI version after an upgrade, it automatically migrates the project-level integrations it recognizes from [CLI state](/sonarqube-cli/administration/state-and-storage.md) to the equivalent global install. See [Migrate project-scoped agent integrations](/sonarqube-cli/administration/self-update.md#migrate-project-scoped-agent-integrations) for what that migration does and its limits.

That migration can only act on installs your machine's `state.json` currently has a record of. It cannot detect project-level integration files state.json does not track, even ones installed by an earlier CLI version on this same machine before a reset. Two common examples: you cloned a repository where someone else ran an older project-scoped `sonar integrate`, or you set up a project on a machine you have since reset or switched away from. Those files get left behind, and this guide walks through finding and removing them by hand.

This is entirely optional and safe. The files described below only affect how your coding assistant or Git hooks behave in this one project. None of the steps touch your SonarQube account or settings.

**Not covered here:** `sonar-project.properties` and `.sonar-config.json` just record which SonarQube project this folder belongs to. They're not integration files. This guide leaves them alone.

## Prerequisites

* Check for an easier path first. If `sonar` still recognizes this project, run `sonar integrate <tool>` again and decline to keep the existing install, or run [`sonar system reset`](/sonarqube-cli/administration/system-reset.md) to start fresh. See [Removing installed features](/sonarqube-cli/integrations/integrations.md#removing-installed-features) for the full flow. The steps below are for when the CLI has no record of this project, where neither option removes anything.
* If this folder is a git repository, use `git status`/`git diff` to see exactly what you're about to remove, and to confirm afterward that you removed only that. One exception: `.git/hooks/` files have no git diff. Take a quick look at the file before deleting it.
* Not sure a file matches what is described below? Leave it alone. Better safe than sorry.

## Removing leftover integration files

Rather than checking each tool below one by one, search the whole folder up front for anything Sonar left behind:

{% tabs %}
{% tab title="MACOS, LINUX" %}

```bash
grep -rlE "sonar:(begin|end)|sonar-(secrets|sqaa|vortex|pre-commit|pre-push|posttoolusefailure)|sonarqube-agentic-analysis-protocol|SonarQube secrets scanning for prompts protocol" \
  --include='*' <YourProjectPath> 2>/dev/null
```

{% endtab %}

{% tab title="WINDOWS (POWERSHELL)" %}

```powershell
Get-ChildItem -Path C:\<YourProjectPath> -Recurse -File -ErrorAction SilentlyContinue |
  Select-String -Pattern 'sonar:(begin|end)|sonar-(secrets|sqaa|vortex|pre-commit|pre-push|posttoolusefailure)|sonarqube-agentic-analysis-protocol|SonarQube secrets scanning for prompts protocol' -List |
  Select-Object -ExpandProperty Path
```

{% endtab %}
{% endtabs %}

This lists every file worth a look. Two kinds of files do not show up in this search. Check for them separately: `.git/hooks/pre-commit` / `.git/hooks/pre-push`, and any folder named `skills` (`.claude/skills/`, `.agents/skills/`, `.github/skills/`).

### Git hooks

Depending on how this repository's git hooks were set up, you may find one (or more, if it was set up more than once over time) of these:

**Native git hook**

File: `.git/hooks/pre-commit` or `.git/hooks/pre-push`

Look for one of these lines in the file:

* `sonar pre-commit hook - installed by sonar integrate git`
* `sonar pre-push hook - installed by sonar integrate git`
* `Sonar secrets scan - installed by sonar integrate git` (older installs)

If the file only contains Sonar's script, delete it:

```bash
rm .git/hooks/pre-commit .git/hooks/pre-push   # whichever exist
```

```powershell
Remove-Item .git\hooks\pre-commit, .git\hooks\pre-push -ErrorAction SilentlyContinue
```

If you had your own hook before setting this up, look for a line further down that calls out to another script. That's your original hook still running. Keep that part and remove only Sonar's lines around it, or restore your original hook from a backup if you have one.

**Husky**

Files: `.husky/pre-commit`, `.husky/pre-push`

Look for a block like this:

```
# sonar:begin husky-pre-commit
...
# sonar:end husky-pre-commit
```

(`husky-pre-push` in the pre-push file.)

Delete everything from the `# sonar:begin husky-...` line to the matching `# sonar:end husky-...` line, including both marker lines. If nothing meaningful is left in the file afterward, delete the file too.

**pre-commit framework**

File: `.pre-commit-config.yaml`

Look for an entry under `repo: local` with a hook `id` of `sonar-pre-commit` or `sonar-pre-push` (very old installs instead point `repo:` at `https://github.com/SonarSource/sonar-secrets-pre-commit`, with hook `id: sonar-secrets`).

Delete that hook entry. If it was the only one under that `repo:` block, delete the whole block.

### Claude Code

The paths below are for a project-level setup. If Claude Code was set up globally instead, the same files live under your home folder rather than in this project.

| What                                       | Where                                                              | How to spot it                                                                                                                          | How to remove it                                         |
| ------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Secrets scanning                           | `.claude/settings.json`, `.claude/hooks/sonar-secrets/`            | An entry under `PreToolUse` or `UserPromptSubmit` mentioning `sonar-secrets`                                                            | Delete the entry, then delete the `sonar-secrets` folder |
| Vortex analysis instructions               | `CLAUDE.md`                                                        | A block between `<!-- sonar:begin:sonarqube-agentic-analysis-protocol -->` and `<!-- sonar:end:sonarqube-agentic-analysis-protocol -->` | Delete that block; leave the rest of the file as is      |
| Vortex analysis hook                       | `.claude/settings.json`, `.claude/hooks/sonar-sqaa/`               | An entry under `PostToolUse` mentioning `sonar-sqaa`                                                                                    | Delete the entry, then delete the `sonar-sqaa` folder    |
| Vortex context hook (failure handling)     | `.claude/settings.json`, `.claude/hooks/sonar-posttoolusefailure/` | An entry under `PostToolUseFailure` mentioning `sonar-posttoolusefailure`                                                               | Delete the entry, then delete the folder                 |
| Vortex context hook (session start)        | `.claude/settings.json`, `.claude/hooks/sonar-vortex/`             | An entry under `SessionStart`/`SubagentStart` mentioning `sonar-vortex`                                                                 | Delete the entry, then delete the folder                 |
| Vortex context skill file (older installs) | `.claude/skills/sonar-context-augmentation/SKILL.md`               | The file exists                                                                                                                         | Delete it (and the folder, if now empty)                 |
| MCP server                                 | `.mcp.json` (project) or `.claude.json` (global)                   | A `sonarqube` entry under `mcpServers`                                                                                                  | Delete that entry                                        |

Tip: if removing an entry leaves an empty list (`[]`) anywhere in `settings.json`, it's tidier to remove that empty key too, but leaving it is harmless.

### Codex

| What                                       | Where                                                | How to spot it                                                                                                                          | How to remove it                                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Secrets scanning                           | `.codex/hooks.json`, `.codex/hooks/sonar-secrets/`   | An entry under `UserPromptSubmit` mentioning `sonar-secrets`                                                                            | Delete the entry, then delete the folder                                                                                                  |
| Secrets-on-read instructions               | `.codex/AGENTS.md`                                   | A block between `<!-- sonar:begin:codex-secrets-on-read -->` and `<!-- sonar:end:codex-secrets-on-read -->`                             | Delete that block                                                                                                                         |
| Vortex analysis instructions               | `AGENTS.md`                                          | A block between `<!-- sonar:begin:sonarqube-agentic-analysis-protocol -->` and `<!-- sonar:end:sonarqube-agentic-analysis-protocol -->` | Delete that block                                                                                                                         |
| Vortex analysis hook                       | `.codex/hooks.json`, `.codex/hooks/sonar-sqaa/`      | An entry under `PostToolUse` mentioning `sonar-sqaa`                                                                                    | Delete the entry, then delete the folder                                                                                                  |
| Vortex context hook                        | `.codex/hooks.json`, `.codex/hooks/sonar-vortex/`    | An entry under `SessionStart`/`SubagentStart` mentioning `sonar-vortex`                                                                 | Delete the entry, then delete the folder                                                                                                  |
| Vortex context skill file (older installs) | `.agents/skills/sonar-context-augmentation/SKILL.md` | The file exists                                                                                                                         | Delete it (and the folder, if now empty). This folder may be shared with Cursor and Antigravity; see the Cursor and Antigravity sections. |
| MCP server                                 | `.codex/config.toml`                                 | A `[mcp_servers.sonarqube]` section                                                                                                     | Delete that section and everything under it, up to the next `[...]` section (or the end of the file)                                      |

### Cursor

| What                                       | Where                                                | How to spot it                                                                                      | How to remove it                                                             |
| ------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Secrets scanning                           | `.cursor/hooks.json`, `.cursor/hooks/sonar-secrets/` | An entry mentioning `sonar-secrets` (under `beforeSubmitPrompt`, `beforeReadFile`, or `preToolUse`) | Delete the entry (or entries), then delete the folder                        |
| Vortex analysis rule                       | `.cursor/rules/sonar-agentic-analysis.mdc`           | The file exists                                                                                     | Delete it                                                                    |
| Vortex context hook                        | `.cursor/hooks.json`, `.cursor/hooks/sonar-vortex/`  | An entry mentioning `sonar-vortex`                                                                  | Delete the entry, then delete the folder                                     |
| Vortex context skill file (older installs) | `.agents/skills/sonar-context-augmentation/SKILL.md` | The file exists                                                                                     | Delete it (and the folder, if now empty). Shared with Codex and Antigravity. |
| MCP server                                 | `.cursor/mcp.json`                                   | A `sonarqube` entry under `mcpServers`                                                              | Delete that entry                                                            |

### GitHub Copilot CLI

| What                                       | Where                                                      | How to spot it                                                                                                                          | How to remove it                                                     |
| ------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Secrets scanning                           | `.github/hooks/hooks.json`, `.github/hooks/sonar-secrets/` | An entry mentioning `sonar-secrets`                                                                                                     | Delete the entry, then delete the folder                             |
| Secrets-on-read instructions               | `.github/instructions/sonarqube.instructions.md`           | A block between `<!-- sonar:begin:copilot-prompt-secrets -->` and `<!-- sonar:end:copilot-prompt-secrets -->`                           | Delete that block; delete the file too if nothing else is left in it |
| Vortex analysis instructions               | `.github/instructions/sonarqube.instructions.md`           | A block between `<!-- sonar:begin:sonarqube-agentic-analysis-protocol -->` and `<!-- sonar:end:sonarqube-agentic-analysis-protocol -->` | Delete that block; delete the file too if nothing else is left in it |
| Vortex context hook                        | `.github/hooks/hooks.json`, `.github/hooks/sonar-vortex/`  | An entry mentioning `sonar-vortex`                                                                                                      | Delete the entry, then delete the folder                             |
| Vortex context skill file (older installs) | `.github/skills/sonar-context-augmentation/SKILL.md`       | The file exists                                                                                                                         | Delete it (and the folder, if now empty)                             |
| MCP server                                 | `.mcp.json`                                                | A `sonarqube` entry under `mcpServers`                                                                                                  | Delete that entry                                                    |

### Antigravity

Antigravity has no way to hook into the start of a session. This section covers secrets scanning and Vortex analysis only; skip Vortex context cleanup for this agent.

| What                                   | Where                                            | How to spot it                      | How to remove it                         |
| -------------------------------------- | ------------------------------------------------ | ----------------------------------- | ---------------------------------------- |
| Secrets scanning rule                  | `.agents/rules/sonar-prompt-secrets.md`          | The file exists                     | Delete it                                |
| Secrets scanning rule (older installs) | `.agents/instructions/sonarqube.instructions.md` | The file exists                     | Delete it                                |
| Secrets scanning hook                  | `.agents/hooks.json`, `.agents/sonar/hooks/`     | An entry mentioning `sonar-secrets` | Delete the entry, then delete the folder |
| Vortex analysis rule                   | `.agents/rules/sonar-agentic-analysis.md`        | The file exists                     | Delete it                                |

Antigravity's MCP server setup lives under your home folder rather than in any one project, with nothing to remove at the project level.

## Verifying the result

Run the search command from [Removing leftover integration files](#removing-leftover-integration-files) again over the same folder. No results means no marker text is left. Since skill folders and `.git/hooks/` files do not show up in that search, give those a quick manual check too if you found any earlier.

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

* [Overview](/sonarqube-cli/integrations/integrations.md#removing-installed-features)
* [Updating the CLI](/sonarqube-cli/administration/self-update.md)
* [Uninstalling](/sonarqube-cli/administration/uninstall.md)
* [Reset the CLI](/sonarqube-cli/administration/system-reset.md)
* [State and storage](/sonarqube-cli/administration/state-and-storage.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/orphaned-integrations.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.