smellcheck

smellcheck

Python Code Smell Detector & Refactoring Guide
83 refactoring patterns · 60 automated AST checks · zero dependencies

smellcheck is a Python code smell detector and refactoring catalog. It works as a pip-installable CLI, GitHub Action, pre-commit hook, or Agent Skills plugin for AI coding assistants.

No dependencies. Pure Python stdlib (ast, pathlib, json). Runs anywhere Python 3.10+ runs.

What are code smells? Code smells are surface-level patterns in source code that hint at deeper design problems — not bugs, but structural weaknesses that make code harder to maintain, extend, or understand. Learn more →

Installation

pip

pip install smellcheck

smellcheck src/
smellcheck myfile.py --format json
smellcheck src/ --min-severity warning --fail-on warning

Also available as a GitHub Action, pre-commit hook, SARIF/Code Scanning integration, Agent Skills plugin, and Cursor native plugin for Claude Code, Cursor, Copilot, Gemini CLI, and more.

Full installation guide →

Usage

# Scan a directory
smellcheck src/

# Scan multiple files
smellcheck file1.py file2.py

# JSON output
smellcheck src/ --format json

# GitHub Actions annotations
smellcheck src/ --format github

# SARIF output (for GitHub Code Scanning)
smellcheck src/ --format sarif > results.sarif

# JUnit XML output (for Jenkins, GitLab, CircleCI, Azure DevOps)
smellcheck src/ --format junit > smellcheck-results.xml

# GitLab CodeClimate output (for MR code quality widget)
smellcheck src/ --format gitlab > gl-code-quality-report.json

# Filter by severity
smellcheck src/ --min-severity warning

# Control exit code
smellcheck src/ --fail-on warning   # exit 1 on warning or error
smellcheck src/ --fail-on info      # exit 1 on any finding

# Run only specific checks
smellcheck src/ --select SC101,SC701,SC210

# Skip specific checks
smellcheck src/ --ignore SC601,SC202

# Module execution
python3 -m smellcheck src/

# Generate a baseline of current findings
smellcheck src/ --generate-baseline > .smellcheck-baseline.json

# Only report findings not in the baseline
smellcheck src/ --baseline .smellcheck-baseline.json

# Disable caching for a fresh scan
smellcheck src/ --no-cache

# Use a custom cache directory
smellcheck src/ --cache-dir .my-cache

# Clear cached results
smellcheck --clear-cache

# Show documentation for a rule (description + before/after example)
smellcheck --explain SC701

# List all rules in a family
smellcheck --explain SC4

# List all rules grouped by family
smellcheck --explain all

# Generate a phased refactoring plan
smellcheck src/ --plan
smellcheck src/ --plan --format json

Configuration

smellcheck reads [tool.smellcheck] from the nearest pyproject.toml:

[tool.smellcheck]
extends = "base.toml"               # inherit from a shared config file
select = ["SC101", "SC201", "SC701"]  # only run these checks (default: all)
ignore = ["SC601", "SC202"]          # skip these checks
per-file-ignores = {"tests/*" = ["SC201", "SC206"]}  # per-path overrides
fail-on = "warning"                  # override default fail-on
format = "text"                      # override default format
baseline = ".smellcheck-baseline.json"  # suppress known findings
cache = true                           # enable file-level caching (default: true)
cache-dir = ".smellcheck-cache"        # cache directory (default: .smellcheck-cache)