quodeq 0.9.0

Source code quality evaluation platform powered by AI

The quality code compass

Your guide to drive any codebase to excellence.

v0.8.1

Quodeq scans any codebase with AI and scores it across six quality dimensions — Security, Reliability, Maintainability, Performance, Flexibility, and Usability — based on ISO 25010. Get grades, find violations, fix what matters.

Watch the demo · Website · Releases

---

Getting Started

pipx install quodeq    # Install quodeq
quodeq dashboard       # Launch the dashboard

That's it. The dashboard lets you point to any project and run evaluations from the UI.

Also available via brew install quodeq/tap/quodeq or pip install quodeq.

Requirements

Dependency	Version
Python	3.12+	Runtime (brew install python or download)
Node.js	18+	Dashboard UI (brew install node or download)
Claude Code	latest	AI analysis engine (npm i -g @anthropic-ai/claude-code)

During the current development phase, Quodeq uses Claude Code as its AI analysis engine. We plan to expand LLM ecosystem support in future releases, including other providers and local LLMs.

Optional: Setting ANTHROPIC_API_KEY enables the dashboard to fetch the latest available models from the Anthropic API. Without it, a built-in default model list is used. Claude Code CLI handles its own authentication — no API key is needed to run evaluations.

---

Dashboard

The Quodeq Dashboard is the main way to use Quodeq. Launch evaluations, browse results, and track quality over time — all from a single web UI.

quodeq dashboard

Opens at http://localhost:4173 with:

• Overall grade & score — A-F letter grade, numeric score /10, trend across runs
• Dimension breakdown — individual scores per quality dimension with severity counts
• Violations explorer — drill into findings by file, principle, or CWE classification
• Top offending files — ranked list of where to focus remediation
• Run history — track how your codebase evolves over time

Click any dimension, file, or principle to explore the details.

QuodeqBar (macOS) — coming soon

A native menu bar companion app to manage the dashboard — start/stop the server, see evaluation status at a glance, and open the dashboard in one click.

Early preview: You can try it now by downloading the DMG from Releases. Since it's not yet signed, allow it with:

xattr -cr /Applications/QuodeqBar.app

CLI usage

You can also run evaluations directly from the terminal:

quodeq evaluate /path/to/project

Run quodeq evaluate --help and quodeq dashboard --help for all available options.

---

How It Works

1. Detect — identifies the languages and structure of the codebase
2. Analyze — spawns an AI CLI with read-only tools to explore the code
3. Collect — findings stream as structured JSONL via tool calls
4. Score — maps findings to ISO 25010 principles with CWE classifications
5. Report — produces per-dimension reports with grades, violations, and compliance

Results are stored in ~/.quodeq/evaluations/ and persist across sessions.

Supported Languages

Quodeq can evaluate any codebase in any language. The AI analysis engine reads and understands code regardless of the tech stack.

---

The Q² Scoring Formula

Quodeq scores each principle on a 0–10 scale using four independent constraints:

1. Violation Base — hyperbolic curve where the first violations hurt most (10 / (1 + K * weighted_violations))
2. Compliance Lift — evidence of good practices fills the gap between the base and 10
3. Violation Ceiling — log₂-based cap prevents compliance from overriding significant violations
4. Severity Grade Floor — grade labels match reality (only critical violations can produce a "Critical" grade)

The final score: max(floor, min(ceiling, base + (10 - base) * lift))

Full details in src/quodeq/core/scoring/README.md.

Development

git clone https://github.com/quodeq/quodeq.git && cd quodeq
uv sync
uv run pytest

Built with Claude Code

Development powered by Claude Code from Anthropic.

Changelog

See CHANGELOG.md for release history.

License

See LICENSE.