Pi SonarQube CLI

SonarQube CLI integration for pi: the sonar binary becomes a first-class citizen of the agent session — dedicated tools, a pre-commit secrets guard and a system-prompt briefing — filling the gap left by sonar integrate, which targets Claude, Copilot, Codex, Cursor and Antigravity but not pi.

How it works

Three integration channels:

Channel	What it does
Tools	Seven sonar_* tools wrap the most common commands: structured parameters, bounded timeouts, truncated output, auth errors with escalation hints.
Context	A system-prompt section teaches the agent when to prefer the tools and how to drive the rest of the CLI surface (sonar api, config, integrate, …) via bash.
Guard	When the agent runs git commit, staged files are scanned with sonar analyze secrets first; findings block the commit.

Nothing is injected when the sonar binary is not installed: the prompt section disappears and the tools answer with install instructions.

Tools

Tool	Wraps	Auth	Notes
sonar_auth_status	sonar auth status	no	Server, org, token source, verification.
sonar_list_projects	sonar list projects	yes	Discover project keys.
sonar_list_issues	sonar list issues	yes	Defaults to --format toon (LLM-optimized), page size 50.
sonar_analyze_secrets	sonar analyze secrets	no	Paths or inline text via stdin. Findings (exit 51) are a result, not a failure.
sonar_dependency_risks	sonar analyze dependency-risks	yes	Security and license risks, status presets supported.
sonar_analyze_agentic	sonar analyze agentic	yes	Server-side Vortex analysis, SonarQube Cloud only; always --force.
sonar_remediate	sonar remediate	yes	AI remediation for up to 20 issue keys, Cloud only.

Output is truncated beyond ~30K characters with a hint to narrow the query — nothing is ever cut silently.

Secrets guard

The guard intercepts bash tool calls containing a real git commit invocation (chained commands included), collects the staged files (git diff --cached --name-only --diff-filter=ACMR) and scans them. Findings block the commit with the scan report attached, so the agent can remove the secret and retry.

The guard fails open by design: not a git repository, nothing staged, CLI missing or a broken scan only skip the check — they never freeze your work. Disable it per session with /sonar guard off.

Commands

• /sonar — status report (CLI version, guard state, live sonar auth status)
• /sonar guard on|off — toggle the pre-commit secrets guard for this session
• /sonar reload — re-probe the binary (after installing or fixing the CLI)
• /sonar hide — dismiss the report widget

Prompt template

The package ships /fix-sonar-issues [hints]: a three-phase triage flow — discover the project key and list issues grouped by severity and rule, fix the groups you select with minimal idiomatic changes, then verify with a fresh analysis. Server-side status changes (accept, false positive) always require explicit approval; issues involving credentials are flagged for revoke-and-rotate.

Known limitations

• The guard matches git commit in bash commands; commits performed through other tools or paths (aliases, IDE integrations) are not intercepted.
• A commit message or script mentioning the literal text git commit may trigger a scan — harmless, since scanning is read-only.
• sonar analyze agentic and sonar_remediate are SonarQube Cloud only (CLI limitation, not an extension one).

Install

Requires the SonarQube CLI on PATH (sonar --version ≥ 1.5.0 recommended) and, for server commands, sonar auth login done manually once.

pi install git:github.com/giuseppe-trisciuoglio/pi-sonarqube-cli
# or from npm:
pi install npm:@giuseppe.trisciuoglio/pi-sonarqube-cli
# or from a local checkout:
pi install /path/to/pi-sonarqube-cli
# or try without installing:
pi -e /path/to/pi-sonarqube-cli/src/index.ts

Development

npm install
npm test              # typecheck + smoke tests
npx tsx test/smoke-test.ts --live   # + probe the real sonar binary

No build step: pi loads TypeScript extensions directly.

sonar.txt at the repository root is a snapshot of the upstream docs/llms.txt the integration surface was derived from; kept for reference when the CLI evolves.

License

MIT — see LICENSE.