| name | codeql-fix |
| description | Run CodeQL security/quality analysis and fix findings. Use when the user asks to run CodeQL, security scan, static analysis, or fix CodeQL findings. |
| compatibility | Requires [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases) on PATH (e.g. brew install codeql). Python and [uv](https://github.com/astral-sh/uv) aligned with [`.python-version`](../../../.python-version) and [`pyproject.toml`](../../../pyproject.toml). Run `uv sync` or `make setup` before analysis when findings should reflect installed dependencies (matches [`.github/workflows/codeql.yml`](../../../.github/workflows/codeql.yml)). |
CodeQL Fix
Use when the user asks to run CodeQL or static analysis, or to fix CodeQL findings (see frontmatter description).
Preconditions
- CodeQL CLI on
PATH (e.g. brew install codeql).
- Install project deps before creating the database (
uv sync, make setup, or CI-style uv sync --frozen) so results match installed dependencies.
Run analysis (repository root)
All commands below assume cd "$(git rev-parse --show-toplevel)".
Do not commit CodeQL databases or SARIF outputs (large, machine-specific). They belong in .gitignore (for example .codeql_db/, codeql-results.sarif).
1. Preferred: Makefile (matches dev/codeql.sh)
make codeql
This creates .codeql_db, analyzes with codeql/python-queries:codeql-suites/python-security-and-quality.qls, writes codeql-results.sarif, and passes --download to resolve query packs.
2. Manual CLI (equivalent to the script)
Create the database (Python needs no build command for extraction):
codeql database create .codeql_db --language=python --source-root . --overwrite
Analyze and emit SARIF:
codeql database analyze .codeql_db \
"codeql/python-queries:codeql-suites/python-security-and-quality.qls" \
--format=sarif-latest \
--output=codeql-results.sarif \
--download
- For a narrower suite closer to default GitHub code scanning, use
codeql/python-queries:codeql-suites/python-code-scanning.qls instead.
- If packs are missing and you are not using
--download, run codeql pack download codeql/python-queries once.
View SARIF in the VS Code SARIF extension (or upload where your org uses code scanning).
3. Optional: code scanning config (paths-ignore)
Use the renderer when you want paths-ignore for large or generated trees, hand-edited query blocks, or parity with GitHub code scanning YAML.
REPO="$(git rev-parse --show-toplevel)"
"$REPO/.claude/skills/codeql-fix/scripts/render-code-scanning-config.sh" "$REPO" /tmp/codeql-config.yml
codeql database create .codeql_db --language=python --source-root . --codescanning-config=/tmp/codeql-config.yml --overwrite
Then run codeql database analyze as in section 2. See references/code-scanning-config.md.
Fixer loop
If the relevant SARIF has an empty runs[].results array, there are no CodeQL alerts to fix for that suite; stop unless the user wants a broader suite or diagnostic queries.
When SARIF findings remain:
- Identify: Read the SARIF or CLI output for reported findings.
- Fix: Apply the minimum necessary edit to resolve each finding.
- Verify: From the repository root, run
make test, then make lint (see AGENTS.md and the Makefile; make lint runs trunk check -a).
- Re-scan: Run
make codeql or repeat the manual create + analyze steps until clean or up to 3 iterations to avoid unbounded loops.
Optional: code scanning config details
See references/code-scanning-config.md and the official code scanning configuration reference.
