Using codqual with AI agents

codqual's agent surface is its REST API — there is no client to install. Any coding agent that can run curl (Claude Code, Cursor, Codex, and so on) can read codqual's findings and act on them.

Skip the reading — your agent can do this

Paste this prompt into your agent and it will walk the quickstart below with you:

I want to add codqual (AI code review) to this project. Read https://codqual.com/docs/agents and help me set it up step by step — The account, repo setup, the skill, the API key, and a first check that it works. Ask me for anything you need.

Quickstart

1. Install the skill

One portable SKILL.md works in Claude Code, Cursor, Windsurf, and Codex CLI — download it into your tool's skills directory. You only need to do this once: the skill carries a version and checks it against codqual.com at the start of each session, replacing its own copy when a newer one has shipped.

# Claude Code
mkdir -p ~/.claude/skills/codqual && curl -fsSo ~/.claude/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Cursor
mkdir -p ~/.cursor/skills/codqual && curl -fsSo ~/.cursor/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Codex CLI
mkdir -p ~/.codex/skills/codqual && curl -fsSo ~/.codex/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Windsurf
mkdir -p ~/.codeium/windsurf/skills/codqual && curl -fsSo ~/.codeium/windsurf/skills/codqual/SKILL.md https://codqual.com/SKILL.md

2. Create an API key

New accounts get a key at signup (shown once). Create more anytime in the dashboard under Settings → API Keys. The skill checks CODQUAL_API_KEY on first run and walks you through adding it to your shell profile — you never paste the key into the agent chat.

3. First request

Ask your agent something like "fix the open codqual issues in this repo", or verify access directly:

curl -fsS -H "Authorization: Bearer $CODQUAL_API_KEY" "https://api.codqual.com/issues?status=open"

MCP endpoint

Agents that speak the Model Context Protocol can skip curl entirely: codqual is an MCP server at https://api.codqual.com/mcp (streamable HTTP, stateless), authenticated with the same API key as a Bearer token. It exposes the read surface as seven tools — list_issues, get_issue_timeline, list_reviews, get_review, get_maturity, get_repo_memory, get_quota — read-only like every use of an API key: an agent can read results and act on them, never trigger analysis.

# Claude Code
claude mcp add --transport http codqual https://api.codqual.com/mcp --header "Authorization: Bearer $CODQUAL_API_KEY"

In any other MCP client, configure an HTTP (streamable) server with url https://api.codqual.com/mcp and an Authorization: Bearer header carrying your key.

Closing the loop from the PR

After fixing a finding, the agent reports back on the codqual PR comment itself — with the user's own gh auth, never a codqual credential:

reply /codqual addressed (and react 👍) when the finding was correct and is now fixed;
reply /codqual dispute <reason> (and react 👎) when it is a false positive — codqual records it as a learning signal for human review, it never silently dismisses;
suppression stays human: a repo maintainer replies /codqual ignore false-positive (or intentional) to stop a finding from reappearing.

Machine-readable docs

Give your agent https://codqual.com/llms.txt (an index of these docs), https://codqual.com/llms-full.txt (everything in one file), or any page's markdown twin — for example https://codqual.com/docs/api.md.

API contract (OpenAPI)

The read API's full surface — issues and their timelines, reviews, scans, repositories, maturity and the public rubric — is described by an OpenAPI 3.1 spec at https://api.codqual.com/openapi.json — kept honest by CI against the live route code, both directions: a documented route must exist, and a readable route must be documented.