quodeq 1.7.2

Source code quality evaluation platform powered by AI

AI-powered code quality and security scanner

v1.7.2

Watch the demo · Website · Blog · Releases

---

AI models can now find vulnerabilities and design flaws that human review misses, but most tools that put this to work are locked behind enterprise contracts. Quodeq is the open alternative.

Open source. MIT license. Runs locally. No telemetry. No account. No servers.

Scans any codebase with AI across six quality dimensions from ISO 25010: Security, Reliability, Maintainability, Performance, Flexibility, and Usability.

Every finding maps to a CWE identifier. You get grades, violations with line numbers, and a fix plan. Cloud providers (Claude, Gemini, Codex) for speed. Local models via Ollama for privacy.

---

What It Finds

CRITICAL    src/db.py:15        SQL injection via string concatenation     CWE-89
            query = f"SELECT * FROM users WHERE id = {user_id}"

MAJOR       src/auth.py:42      Hardcoded credentials in source code       CWE-798
            credentials = {"user": "admin", "pass": "secret123"}

MINOR       src/utils.py:23     Bare except clause hides errors            CWE-396
            except: pass

COMPLIANT   src/api.py:88       Parameterized query prevents injection     CWE-89
            cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

Each finding includes a reason, the offending code, and a fix plan. Results are stored as JSON on your machine.

---

Getting Started

1. Prerequisites

OS	Command
macOS	brew install python pipx
Windows	winget install Python.Python.3.13 then python -m pip install --user pipx && python -m pipx ensurepath
Debian / Ubuntu	sudo apt install -y python3.12 python3-pip pipx
Fedora / RHEL	sudo dnf install -y python3.12 python3-pip pipx
Arch	sudo pacman -S python python-pipx

Debian/Ubuntu heads-up: If you use the native desktop window (not --browser), you'll need sudo apt install -y python3-gi gir1.2-webkit2-4.1 too. Otherwise quodeq will auto-fall-back to opening the dashboard in your default browser.

Windows note: The test suite runs on windows-latest as a blocking CI gate, so a Windows regression blocks the PR. The desktop window (WebView2) is smoke-tested manually per release. If anything misbehaves, please open an issue.

Minimum versions: Python 3.12+. (The dashboard UI ships pre-built inside the wheel, so end users no longer need Node.js or npm. Contributors who want to iterate on the UI source need Node 20+ and npm 10+, see CONTRIBUTING.md.)

2. Install quodeq

pipx install quodeq    # isolated, recommended
# or: pip install quodeq

3. Pick an AI provider

Quodeq needs an LLM to do the evaluation. You have two options:

Local, free, private — Ollama with Gemma 4:

# install ollama from https://ollama.com/download, then:
ollama pull gemma4:26b
ollama serve    # runs in the background

Cloud, faster — one of the agentic CLIs (at least one):

• Claude Code — npm install -g @anthropic-ai/claude-code
• Codex CLI — npm install -g @openai/codex
• Gemini CLI — npm install -g @google/gemini-cli

4. Launch the dashboard

quodeq

The dashboard opens at http://127.0.0.1:7863. Use Settings → AI Provider to select the one you installed in step 3, then Evaluate to point at a project and start your first scan.

If the native window doesn't show up (common on Linux without GTK), run quodeq --browser instead.

macOS App (beta)

Download the .dmg from Releases, open it, and drag Quodeq.app to Applications. On first launch:

xattr -cr /Applications/Quodeq.app    # Required for unsigned apps

Or right-click the app, select Open, then click Open in the dialog.

---

Dashboard

• Grades and scores per dimension with A-F letter grades, numeric scores, and trends across runs
• Violations explorer to drill into findings by file, principle, or CWE classification
• Code map showing a visual heatmap of where issues concentrate in your codebase
• Custom standards to create your own evaluation dimensions or import from the library

Click any dimension, file, or principle to explore the details. Dismiss false positives directly from the UI.

Running quodeq is equivalent to quodeq dashboard. Both open the same UI.

CLI

quodeq evaluate /path/to/project
quodeq evaluate /path/to/project --scope src/api    # Scoped to a subdirectory
quodeq evaluate /path/to/project -d security        # Single dimension

Excluding paths (.quodeqignore)

To keep fixture, vendored, or generated code out of an evaluation, add a .quodeqignore file at the scan root. Each line is a glob pattern matched against paths relative to that root; a pattern that names a directory excludes everything under it. Blank lines and # comments are skipped, and * crosses directory separators.

# test fixtures with intentionally bad code
benchmarks/corpus/
tests/fixtures

# generated files, at any depth
*.gen.py
*.min.js

Exclusions apply everywhere files are collected — full scans, --scope runs, monorepo subproject discovery, and --diff-from change detection — on top of the built-in skips (node_modules, dist, dot-directories, ...).

SARIF / GitHub code scanning

Quodeq can emit findings as SARIF 2.1.0 for GitHub code scanning (the Security tab), GitLab SAST, or any SARIF consumer. Generate it during a scan, or export it from a past run:

quodeq evaluate . --sarif quodeq.sarif            # during a scan
quodeq export sarif --evaluation-dir <dir> -o quodeq.sarif   # from existing reports

Code snippets are omitted by default (so source never leaves your machine on upload); pass --with-snippets to include them. Use --min-severity to drop low-severity findings.

Upload to GitHub code scanning:

- run: quodeq evaluate . --sarif quodeq.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: quodeq.sarif

---

Updates

Quodeq checks for new versions once a day in the background (PyPI for pip/pipx/uv installs, GitHub Releases for the macOS/Windows apps) and shows a dismissible notice with the right upgrade step. It never auto-replaces itself and sends no telemetry — the only network call is an unauthenticated request to PyPI/GitHub.

Disable it by setting QUODEQ_NO_UPDATE_NOTIFIER=1, or toggle "Automatic checks" off under Settings → Updates.

---

AI Providers

Choose what fits your workflow. Configure in Settings from the dashboard.

Provider	Type	Getting started
Ollama	Local	Free, private, code never leaves your machine
llama.cpp	Local	Run any GGUF directly. Supports speculative decoding (MTP) via a draft model
Claude Code	Cloud	Best balance of speed, quality, and cost
Codex CLI	Cloud	OpenAI models
Gemini CLI	Cloud	Google models

For local analysis we recommend Gemma 4 (gemma4:26b). Reducing the context window to 32k still gives good results and allows running multiple subagents in parallel.

Using llama.cpp

llama.cpp is one process per model, fixed at launch. Start llama-server yourself, then point Quodeq at it from Settings → AI Provider → llama.cpp.

# Quodeq creates ~/.quodeq/logs/ on first launch — just redirect there
# and the CONSOLE button picks it up automatically.
llama-server -m path/to/target.gguf --port 8080 \
  > ~/.quodeq/logs/llama-server.log 2>&1

# Speculative decoding (MTP), pair a target with a smaller drafter
llama-server -m path/to/target.gguf -md path/to/drafter.gguf --port 8080 \
  > ~/.quodeq/logs/llama-server.log 2>&1

Quodeq probes http://localhost:8080 and looks for the log file at ~/.quodeq/logs/llama-server.log (or platform-standard locations like ~/Library/Logs/llama-server.log on macOS). Override with LLAMACPP_LOG_FILE. To use a different port or host, set LLAMACPP_BASE_URL. To switch models, stop llama-server and relaunch with a different -m.

---

How It Works

1. Detect languages, frameworks, and project structure
2. Analyze with AI agents that read the code using read-only tools
3. Collect findings as structured JSONL via tool calls
4. Score against ISO 25010 principles with CWE classifications
5. Report per-dimension grades, violations, compliance, and fix plans

Results are stored in ~/.quodeq/evaluations/ and persist across sessions. Works with any language. The AI analysis engine reads and understands code regardless of the tech stack.

Quodeq scores each principle on a 0 to 10 scale using four independent constraints. Full details in the scoring formula documentation.

Standards

By default, Quodeq evaluates the six ISO 25010 dimensions. It also ships with Clean Architecture and Domain-Driven Design standards. You can create your own from the dashboard, or ask any AI to generate one as a .json file and import it.

Numeric thresholds on the built-in standards (max function lines, max parameters, ...) can be tuned per project from the dashboard. Overrides live in .quodeq/standards-overrides.json at the repo root, so the whole team scans with the same numbers.

---

Development

Run from a fresh checkout:

git clone https://github.com/quodeq/quodeq.git && cd quodeq
uv sync                   # install Python deps into .venv/
uv run quodeq             # launch the dashboard
uv run pytest             # run the test suite

Same OS prerequisites as the pipx install (Python 3.12+), plus Node 20+ and npm 10+ because a source checkout builds the dashboard UI from the working copy. You also need a configured LLM provider (Ollama or Claude Code / Codex CLI / Gemini CLI) before you can actually scan anything.

If the dashboard window doesn't appear on Linux, run uv run quodeq --browser (the native window needs python3-gi + gir1.2-webkit2-4.1, which aren't pulled in by the pip wheel).

Changelog

See CHANGELOG.md for release history.

License

MIT. See LICENSE.