qctx

Quality context for AI agents. Gathers SonarQube + Nexus IQ + GitLab MR/pipeline state into one normalized payload so agents can fix issues without round-tripping multiple APIs.

Status

Pre-1.0. CLI flags, env vars, and JSONL schema are stable across patch releases; minor releases may add fields but not remove them. Breaking changes only at 0.x → 0.(x+1) where flagged in CHANGELOG.

Install

go install github.com/RandomCodeSpace/qctx/cmd/qctx@latest
# or download a release binary from your GitLab/GitHub releases page

Docker:

docker pull registry.example.com/qctx:latest

Modes

Mode	Command	Output	Use case
Live	qctx fetch	JSON to stdout	Interactive AI agent shells out
Snapshot	qctx snapshot --out report.jsonl	JSONL file	GitLab pipeline writes an artifact

Live mode quick start

export SONAR_HOST_URL=https://sonar.example.com
export SONAR_TOKEN=...
export GITLAB_HOST_URL=https://gitlab.example.com
export GITLAB_TOKEN=...

qctx fetch \
  --mr "https://gitlab.example.com/team/my-svc/-/merge_requests/42" \
  --nexus-report nexus-iq-report.json | jq '.sonar.issues[].severity'

Pipeline snapshot quick start

# .gitlab-ci.yml in your project
include: docs/examples/gitlab-ci.yml

See docs/examples/gitlab-ci.yml for the full job spec.

Filters

Flag	Effect
--severity BLOCKER --severity CRITICAL	repeatable severity filter
--type BUG --type VULNERABILITY	repeatable type filter
--branch feat-x	override branch
--all	include all open issues, not just MR-touched
--include-resolved	include resolved/closed
--no-sonar / --no-gitlab / --no-nexus	disable a source
--strict	non-zero exit on any source failure
--config PATH	path to YAML config (default: $QCTX_CONFIG or ~/.qctx.yaml)
--log-level LEVEL	debug / info / warn / error (env: QCTX_LOG_LEVEL)

Enterprise

Custom URLs, CA bundles, SSO proxies, NO_PROXY, header injection: see docs/enterprise.md.

JSONL schema

Each line is one record with a type discriminator. Types: meta, sonar.issue, sonar.hotspot, sonar.measure, sonar.quality_gate, nexus.violation, gitlab.mr, gitlab.mr.diff_summary, gitlab.mr.discussion, gitlab.pipeline, gitlab.job, error. Full spec: docs/superpowers/specs/2026-05-19-qctx-design.md.

Auto-discovery

Given just a GitLab MR URL, qctx infers the Sonar project key from the pipeline's job traces (looks for -Dsonar.projectKey=… or sonar.projectKey=…). Override with --project KEY.

Development

make tidy
make ci         # tidy + fmt + lint + cover + cover-check + build
make e2e        # e2e against mock servers
make doctor     # verify required + optional tools are installed
make help       # list all targets

See CONTRIBUTING.md for the workflow, commit conventions, and the enterprise-host policy.

Project files

• CHANGELOG.md — release notes and pending changes
• CONTRIBUTING.md — how to build, test, and submit
• SECURITY.md — vulnerability reporting and threat model
• docs/adr/ — architecture decision records (why, not just what)
• docs/enterprise.md — self-hosted / CA / proxy / SSO guidance

License

Apache-2.0