quodeq 1.9.0

AI-powered code quality and security scanner

Watch the demo · Website · Blog · Discussions · 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

On macOS you can skip this step by installing through Homebrew (see step 2). The formula pulls in its own Python.

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

Homebrew (macOS, and the shortest path):

brew install quodeq/tap/quodeq

pipx / pip (every platform):

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

Prefer a desktop app to the CLI? See Desktop apps below.

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

llama.cpp is also supported. See AI Providers for the full list and how to choose.

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.

Desktop apps (beta)

Every release attaches three prebuilt apps to Releases. They bundle their own Python, so none of the prerequisites above apply.

macOS. Open the .dmg and drag the app to Applications. The apps are unsigned, so the first launch needs one of:

xattr -cr /Applications/Quodeq.app       # or /Applications/QuodeqBar.app

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

Windows. Unzip anywhere and run Quodeq.exe. SmartScreen will warn about an unrecognized publisher on first launch: choose More info then Run anyway.

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

AI Providers

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

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.

Threat model

By default Quodeq scores a project as if it were a hosted multi-tenant service. For a local-first tool that produces noise: a file path built from a value the operator already controls gets reported as an attack surface, and the real findings get buried under it.

A project can say what it actually is, in .quodeq/project-profile.json at the repo root:

{
  "version": 1,
  "multiTenant": false,
  "networkExposure": "loopback"
}

multiTenant answers whether more than one user's data lives behind the same code. networkExposure is one of loopback, lan, or public, and answers whether an untrusted party can open a socket to the process.

Findings the declared model rules out are capped at minor rather than dropped, and carry a marker naming the rule that moved them, so nothing becomes invisible. A finding whose evidence names a real remote source is never capped, whatever the profile says.

The file is optional. Without it Quodeq infers what it can from your manifests and otherwise assumes the most pessimistic model, which is how it behaves today.

Privacy

There is no Quodeq account, no Quodeq server, and no telemetry. Your source code is read locally and evaluation results are written to ~/.quodeq/evaluations/ as plain JSON. If you run a local provider, nothing about your code leaves the machine at all. If you pick a cloud provider, your code goes to that provider under your own API key and nowhere else.

Quodeq makes exactly one network call of its own: a daily unauthenticated version check (PyPI for pip/pipx/uv installs, GitHub Releases for the desktop apps). It shows a dismissible notice with the right upgrade step and never replaces itself. Turn it off with QUODEQ_NO_UPDATE_NOTIFIER=1, or under Settings → Updates.

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).

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers the development setup, the test suite, and how changes get reviewed. Everyone taking part is expected to follow the Code of Conduct.

• Found a bug or want a feature? Open an issue.
• Want to ask something, or show what you built? Discussions.
• Found a security problem? Please don't open a public issue. SECURITY.md has the disclosure process.

If Quodeq is useful to you, starring the repo genuinely helps other people find it.

Changelog

See CHANGELOG.md for release history, or the release announcements for the readable version.

License

MIT. See LICENSE.