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 to the equivalent global install. See 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 to start fresh. See 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:

MACOS, LINUX

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

WINDOWS (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

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:

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

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

• Removing installed features

• Updating the CLI

• Uninstalling

• Reset the CLI

• State and storage