Revamp README to reflect the current state and installation paths#26
Open
voz wants to merge 7 commits into
Open
Revamp README to reflect the current state and installation paths#26voz wants to merge 7 commits into
voz wants to merge 7 commits into
Conversation
Restructure the README around two distinct installation paths (marketplace-first vs CLI-first), document the PrePrompt/PreTool/PostTool hook taxonomy honestly per agent, link SonarQube-specific marketplace listings (Claude, Copilot, Cursor Directory, Kiro), and replace the Compliance section with a shorter, less-formal team-rollout block. All external URLs HEAD-checked, all local file references verified, all internal anchors validated against headings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SummaryMajor README restructure, ~2x length, now framed for enterprise evaluation and rollout. Key changes:
Author verified 30/30 external URLs (200), all local refs resolve, anchors validated, terminology consistent (American English). What reviewers should knowStart reading at:
Non-obvious decisions:
Gotchas to watch:
|
voz
changed the title
voz
requested review from
a team,
damien-urruty-sonarsource and
sophio-japharidze-sonarsource
![sonar-review-alpha[bot]](https://avatars.githubusercontent.com/in/3025063?s=60&v=4){kind=small}
| Plugin: [`.claude-plugin/`](./.claude-plugin/). Marketplace: **[`claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)** — Anthropic's official catalog. Plugin listing: **[claude.com/plugins/sonarqube](https://claude.com/plugins/sonarqube)**. | ||
|
|
||
| ## Codex CLI | ||
| Beyond the skills, the Claude Code plugin installs a **SessionStart hook** ([`claude-hooks/hooks.json`](./claude-hooks/hooks.json) → [`scripts/setup.js`](./scripts/setup.js)) that reports CLI presence, authentication status, and any registered hooks (Secrets Detection, Agentic Analysis) when a session starts. The hook reports state; it does not install anything itself — run `sonar integrate claude` or `/sonarqube:sonar-integrate` for that. |
There was a problem hiding this comment.
The description of what the SessionStart hook reports is inaccurate. Looking at scripts/setup.js, the script outputs three things:
- Whether
sonaris onPATH(hasSonarCli()) - Which hooks are installed (filtering
state.agentExtensionsbyagentId === 'claude-code'and matching the working directory)
There is no authentication status check anywhere in the script — no call to sonar auth status, no reading of an auth token, and no auth-related field in state.json is inspected. A user who relies on the session start message to confirm they're authenticated will be misled.
Suggested change
| Beyond the skills, the Claude Code plugin installs a **SessionStart hook** ([`claude-hooks/hooks.json`](./claude-hooks/hooks.json) → [`scripts/setup.js`](./scripts/setup.js)) that reports CLI presence, authentication status, and any registered hooks (Secrets Detection, Agentic Analysis) when a session starts. The hook reports state; it does not install anything itself — run `sonar integrate claude` or `/sonarqube:sonar-integrate` for that. | |
| Beyond the skills, the Claude Code plugin installs a **SessionStart hook** ([`claude-hooks/hooks.json`](./claude-hooks/hooks.json) → [`scripts/setup.js`](./scripts/setup.js)) that reports CLI presence and any registered hooks (Secrets Detection, Agentic Analysis) when a session starts. The hook reports state; it does not install anything itself — run `sonar integrate claude` or `/sonarqube:sonar-integrate` for that. |
| | **Gemini CLI** | `gemini-extension.json`, `GEMINI.md` | | ||
| | **Kiro** | `kiro-power/` | | ||
| - **A SonarQube account.** [SonarQube Cloud](https://sonarcloud.io) (EU or US region), self-hosted **SonarQube Server**, or **SonarQube Community Build**. Some features (Agentic Analysis, Advanced Security / SCA) require Cloud or a specific Server edition. | ||
| - **The [SonarQube CLI](https://cli.sonarqube.com/)** (`sonar`) ends up on your `PATH` either way — Path A installs it for you via the bootstrap skill, Path B installs it as the first step. You don't need to install it yourself before getting started. |
There was a problem hiding this comment.
This claim is incomplete for Kiro and AgentHQ users. Line 185 explicitly tells those users to "follow Path B steps B1 and B2 to install the CLI and authenticate manually" — meaning they do need to install the CLI themselves. A Kiro user who reads this prerequisite bullet and interprets it as "I don't need to install the CLI before getting started" will hit the Path A → Step 2 handoff and be surprised.
The bullet should note the exception, or qualify "Path A" as applying only to agents that support the bootstrap skill.
Suggested change
| - **The [SonarQube CLI](https://cli.sonarqube.com/)** (`sonar`) ends up on your `PATH` either way — Path A installs it for you via the bootstrap skill, Path B installs it as the first step. You don't need to install it yourself before getting started. | |
| - **The [SonarQube CLI](https://cli.sonarqube.com/)** (`sonar`) ends up on your `PATH` either way — for agents that support the bootstrap skill (Claude Code, GitHub Copilot CLI), Path A installs it for you; for all other agents and for Path B, installing the CLI is step one. You don't need to install it yourself before getting started with Claude Code or Copilot CLI. |
| ## How plugins connect to SonarQube | ||
| 1. **Individual developers** who want a quality check that runs inside the agent instead of after the PR is opened. Install one plugin, get slash commands and natural-language access to the SonarQube ruleset, coverage, and quality gates. | ||
| 2. **Platform / DevEx teams** rolling SonarQube out across many engineers and many editors. Pin one CLI version, distribute one plugin per agent, get consistent rules and consistent auth flow regardless of which AI tool a team picks. | ||
| 3. **Security and compliance owners** who need credentials, secrets, and source code to stay on the developer's machine — not embedded in prompts sent to LLM providers. The PrePrompt and PreTool secrets hooks are the relevant controls. |
Contributor
There was a problem hiding this comment.
Suggested change
| 3. **Security and compliance owners** who need credentials, secrets, and source code to stay on the developer's machine — not embedded in prompts sent to LLM providers. The PrePrompt and PreTool secrets hooks are the relevant controls. | |
| 3. **Security and compliance owners** who need credentials, secrets, and source code to stay on the developer's machine — not embedded in prompts sent to LLM providers. The PromptSubmit and PreToolUse secrets hooks are the relevant controls. |
| sonar integrate claude # Claude Code: MCP, hooks, secrets scanning, etc. | ||
| sonar integrate copilot # GitHub Copilot CLI: MCP setup | ||
| ``` | ||
| ¹ See [Hook types](#hook-types) for what each hook does and why the per-agent breakdown matters. The MCP server, the nine skills, and the Quick Start work in every supported agent — the columns above reflect only the *automated* secrets and Agentic Analysis hooks. |
Contributor
There was a problem hiding this comment.
Suggested change
| ¹ See [Hook types](#hook-types) for what each hook does and why the per-agent breakdown matters. The MCP server, the nine skills, and the Quick Start work in every supported agent — the columns above reflect only the *automated* secrets and Agentic Analysis hooks. | |
| ¹ See [Hook types](#hook-types) for what each hook does and why the per-agent breakdown matters. The MCP server, the skills, and the Quick Start work in every supported agent — the columns above reflect only the *automated* secrets and Agentic Analysis hooks. |
|
|
||
| **SonarQube CLI** can wire everything for you: | ||
| | Agent | Plugin location | Install from | Secrets scanning¹ | Agentic Analysis¹ | | ||
| | --- | --- | --- | --- | --- | |
Contributor
There was a problem hiding this comment.
Please align the table
| ¹ See [Hook types](#hook-types) for what each hook does and why the per-agent breakdown matters. The MCP server, the nine skills, and the Quick Start work in every supported agent — the columns above reflect only the *automated* secrets and Agentic Analysis hooks. | ||
|
|
||
| Run these **after** `sonar auth login`. Use the **`/sonarqube:sonar-integrate`** skill in Claude Code if you prefer a guided flow (install/update CLI, login, then integrate). | ||
| > **GitHub AgentHQ** ships as a separate plugin — [`SonarSource/sonarqube-agenthq-plugin`](https://github.com/SonarSource/sonarqube-agenthq-plugin) — because AgentHQ has different packaging requirements. PrePrompt secrets scanning is wired today; other hooks are tracked there. |
Contributor
There was a problem hiding this comment.
Suggested change
| > **GitHub AgentHQ** ships as a separate plugin — [`SonarSource/sonarqube-agenthq-plugin`](https://github.com/SonarSource/sonarqube-agenthq-plugin) — because AgentHQ has different packaging requirements. PrePrompt secrets scanning is wired today; other hooks are tracked there. | |
| > **GitHub AgentHQ** ships as a separate plugin — [`SonarSource/sonarqube-agenthq-plugin`](https://github.com/SonarSource/sonarqube-agenthq-plugin) — because AgentHQ targets different use-cases and does not rely on SonarQube CLI. |
Contributor
There was a problem hiding this comment.
Update: We should remove this altogether. We don't want to accidentally announce things before the official announcement from GH
| ▼ | ||
| ┌─────────────────────────────────────────────────────┐ | ||
| │ Skills ── skills/sonar-* │ | ||
| │ Nine agent-agnostic playbooks (this repo) │ |
Contributor
There was a problem hiding this comment.
Suggested change
| │ Nine agent-agnostic playbooks (this repo) │ | |
| │ Agent-agnostic playbooks (this repo) │ |
| ▼ | ||
| ┌─────────────────────────────────────────────────────┐ | ||
| │ SonarQube Cloud / Server / Community Build │ | ||
| │ 7,000+ rules, quality gates, project history │ |
Contributor
There was a problem hiding this comment.
Suggested change
| │ 7,000+ rules, quality gates, project history │ | |
| │ 7,500+ rules, quality gates, project history │ |
|
|
||
| Skills are the same across agents. Ask in natural language, invoke skills explicitly, or use the **SonarQube MCP** tools your client shows after MCP starts. | ||
| - **Path A — Marketplace-first.** You're already inside the agent (or one click away from it). Install the SonarQube plugin from the agent's plugin catalog, then run `/sonarqube:sonar-integrate` inside the agent. The skill installs the SonarQube CLI for you if it's missing, walks you through `sonar auth login`, and wires the hooks. You never leave the agent. | ||
| - **Path B — CLI-first.** You're in a terminal. Install the SonarQube CLI, `sonar auth login`, then `sonar integrate <agent>`. One terminal session, plugin and hooks both wired. |
Contributor
There was a problem hiding this comment.
Today the sonar integrate * command does not install agent plugins. So Path A is always required.
So maybe it's best to just leave that path - install the plugin and run integrate skill.
| SonarQube is published to the default **[`awesome-copilot`](https://awesome-copilot.github.com/plugins/)** marketplace ([source repo](https://github.com/github/awesome-copilot)) — no `marketplace add` step needed: | ||
|
|
||
| ```text | ||
| /plugin install sonarqube@awesome-copilot |
Contributor
There was a problem hiding this comment.
We are currently having an issue with this path. Let's promote it only after it's fixed. So for now we can leave the sonar's own marketplace & plugin commands.
|
|
||
| That's it — the agent now has skills, MCP tools, and whichever hooks your agent supports. For agents where slash commands aren't exposed (Kiro today, AgentHQ), follow Path B steps B1 and B2 to install the CLI and authenticate manually. | ||
|
|
||
| ### Path B — From the SonarQube CLI |
Contributor
There was a problem hiding this comment.
Let's keep it simple & drop path B. Steps and end result is exactly the same.
| | [`.codex-plugin/`](./.codex-plugin/) | Codex CLI plugin manifest | | ||
| | [`.cursor-plugin/`](./.cursor-plugin/) | Cursor plugin manifest | | ||
| | [`.github/plugin/`](./.github/plugin/) | GitHub Copilot CLI plugin + marketplace | | ||
| | [`.agents/plugins/`](./.agents/plugins/) | Cross-agent marketplace catalog | |
Contributor
There was a problem hiding this comment.
Suggested change
| | [`.agents/plugins/`](./.agents/plugins/) | Cross-agent marketplace catalog | | |
| | [`.agents/plugins/`](./.agents/plugins/) | Codex CLI marketplace catalog | |
|
|
||
| This repository ships **configuration**, not analyzers. Where work happens: | ||
|
|
||
| 1. **Locally**, through the SonarQube CLI binary — `sonar run mcp`, the secrets scanner (`sonar analyze secrets`), and `sonar verify` against your working tree. Source code stays on your machine. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. **Locally**, through the SonarQube CLI binary — `sonar run mcp`, the secrets scanner (`sonar analyze secrets`), and `sonar verify` against your working tree. Source code stays on your machine. | |
| 1. **Locally**, through the SonarQube CLI binary — `sonar run mcp`, the secrets scanner (`sonar analyze secrets`), and `sonar analyze agentic` against your working tree. Source code stays on your machine. |
| Where an agent doesn't expose the hook surface natively, the same protections can be approximated by adding the equivalent instructions to the agent's system prompt — useful as a stopgap, but lower assurance than a hook that the runtime enforces. | ||
|
|
||
| Copyright (C) 2025-2026 SonarSource Sàrl. Licensed under [SSAL-1.0](LICENSE). | ||
| **Telemetry.** The CLI ships anonymous usage telemetry, on by default with a single opt-out toggle — run `sonar config telemetry --disabled` to turn it off, and see the [SonarQube CLI docs](https://docs.sonarsource.com/sonarqube-cli/) for details. This repository contains no runtime code that phones home; it is only configuration consumed by the agent and the CLI. |
Contributor
There was a problem hiding this comment.
Should we mention this here? It is about CLI, not plugins
|
|
||
| A few things worth knowing if you're pushing this out beyond your own laptop: | ||
|
|
||
| - **The CLI and the plugins move together.** Plugin `2.1.0` is built against a specific [SonarQube CLI](https://cli.sonarqube.com/) release. Pick the CLI version your team has validated; the matching plugin version goes with it. Treat them as one unit when you upgrade. |
Contributor
There was a problem hiding this comment.
We do not fix a CLI version, only the latest at all times.
|
|
||
| - **The CLI and the plugins move together.** Plugin `2.1.0` is built against a specific [SonarQube CLI](https://cli.sonarqube.com/) release. Pick the CLI version your team has validated; the matching plugin version goes with it. Treat them as one unit when you upgrade. | ||
| - **Pick a rollout pattern that matches your scale.** A solo developer installs the CLI and one plugin and is done. A repo commits `sonar-project.properties` so every contributor's agent picks up the project key automatically. Org-wide, ship the CLI binary and the agent plugin through whatever distribution channel you already trust — managed install, internal package registry, MDM — and let Renovate keep this repo's dependencies fresh on the way through. | ||
| - **Self-hosted and air-gapped work the same way.** `sonar auth login -s https://sonar.mycompany.com` and you're done. The MCP server only talks to the SonarQube instance you point it at — no SonarSource SaaS dependency, no surprise outbound calls. Tokens stay in the OS keychain. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Self-hosted and air-gapped work the same way.** `sonar auth login -s https://sonar.mycompany.com` and you're done. The MCP server only talks to the SonarQube instance you point it at — no SonarSource SaaS dependency, no surprise outbound calls. Tokens stay in the OS keychain. | |
| - **Self-hosted and air-gapped work the same way.** `sonar auth login -s https://sonar.mycompany.com` and you're done. The MCP server only talks to the SonarQube instance you point it at — no surprise outbound calls. Tokens stay in the OS keychain. |
|
|
||
| ## Contributing | ||
|
|
||
| We are not actively soliciting feature contributions — the plugin surface tracks Sonar's product roadmap and our quality bar is tight. Cosmetic fixes (typos, broken links, README polish) are welcome via PR. For anything larger, open an issue first so we can confirm the direction before you invest time. |
Contributor
There was a problem hiding this comment.
Suggested change
| We are not actively soliciting feature contributions — the plugin surface tracks Sonar's product roadmap and our quality bar is tight. Cosmetic fixes (typos, broken links, README polish) are welcome via PR. For anything larger, open an issue first so we can confirm the direction before you invest time. | |
| We are not soliciting feature contributions — the plugin surface tracks Sonar's product roadmap and our quality bar is tight. |
sophio-japharidze-sonarsource
requested changes
May 20, 2026
sophio-japharidze-sonarsource
left a comment
sophio-japharidze-sonarsource
left a comment
Contributor
There was a problem hiding this comment.
Left a few suggestions. Overall content looks OK but I feel it's A LOT for what it is. I would advocate to keep it much more simple and concise. Humans are still around and look at the content, not only agents :)
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
Co-authored-by: Sophio Japharidze <104207951+sophio-japharidze-sonarsource@users.noreply.github.com>
|
There was a problem hiding this comment.
This commit introduced two new bugs on top of the two prior issues that remain unresolved — see inline comments and the notes below.
Two previously flagged issues are still open: the inaccurate "authentication status" claim about scripts/setup.js (line 317) and the misleading prerequisite bullet for Kiro/AgentHQ users (line 105). Neither was touched by this commit.
| # SonarQube plugins for agents | ||
|
|
||
| Automatically enforce SonarQube code quality and security in the agent coding loop — 7,000+ rules, secrets scanning, agentic analysis, and quality gates across 40+ languages. | ||
| ** SonarQube is the AI code quality and security verification platform used by millions of developers to catch bugs, vulnerabilities, and leaked secrets. This plugin enforces those standards automatically in the coding loop: 7,500+ distinct issue types, secrets scanning, agentic analysis, and quality gates across 40+ languages.** |
There was a problem hiding this comment.
The space between ** and SonarQube breaks the bold rendering — GitHub will treat this as literal ** characters, not a bold span. CommonMark requires the opening ** to be immediately followed by a non-whitespace character.
Suggested change
| ** SonarQube is the AI code quality and security verification platform used by millions of developers to catch bugs, vulnerabilities, and leaked secrets. This plugin enforces those standards automatically in the coding loop: 7,500+ distinct issue types, secrets scanning, agentic analysis, and quality gates across 40+ languages.** | |
| **SonarQube is the AI code quality and security verification platform used by millions of developers to catch bugs, vulnerabilities, and leaked secrets. This plugin enforces those standards automatically in the coding loop: 7,500+ distinct issue types, secrets scanning, agentic analysis, and quality gates across 40+ languages.** |
|
|
||
| The Plugin helps agents connect to [SonarQube CLI](https://cli.sonarqube.com/) and [SonarQube MCP Server](https://docs.sonarsource.com/sonarqube-mcp-server) for issue detection, checking project metrics such as test coverage & duplications, fetch dependency risks, etc. Claude Code & Copilot integrations (through SonarQube CLI) install agent hooks. This is coming soon for other agents too. | ||
| - 🔍 **7,500+ rules across 40+ languages** — SonarQube rules, on demand, from inside the agent. | ||
| - 🔒 **Secrets blocked before they reach the LLM** — PromptSubmit and PreToolUse hooks (Claude Code, Copilot CLI today) intercept hardcoded credentials before the agent sends them to its model. |
There was a problem hiding this comment.
This commit changed PrePrompt and PreTool hooks to PromptSubmit and PreToolUse hooks, but the rest of the document consistently uses PrePrompt and PreTool — the capability matrix (line 62–65), the "Who this is for" section (line 56), the hook-types definitions (lines 354–356), and the troubleshooting section (line 391). A reader who follows this bullet to the "Hook types" reference section will find no matching terminology.
PromptSubmit and PreToolUse appear to be the raw Claude Code hook event names, not the human-readable abstractions the README standardises on. Revert to the previous terminology.
Suggested change
| - 🔒 **Secrets blocked before they reach the LLM** — PromptSubmit and PreToolUse hooks (Claude Code, Copilot CLI today) intercept hardcoded credentials before the agent sends them to its model. | |
| - 🔒 **Secrets blocked before they reach the LLM** — PrePrompt and PreTool hooks (Claude Code, Copilot CLI today) intercept hardcoded credentials before the agent sends them to its model. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major README revamp aimed at an enterprise audience evaluating these plugins and rolling them out across many engineers.
What changed
/sonarqube:sonar-integrate) and Path B (sonar integrate <agent>from a terminal) are now genuinely independent — no shared prerequisites that mislead either audience./sonarqube:sonar-integrate.Verified