English | 日本語 | 简体中文 | Français
A code quality analyzer for Python vibe coders.
Building with Cursor, Claude, or ChatGPT? pyscn performs structural analysis to keep your codebase maintainable.
Working with other languages? pyscn is part of polyscan — code quality analyzers for JavaScript/TypeScript and more
Quick Start
# Run analysis without installation
uvx pyscn@latest analyze .
# or
pipx run pyscn analyze .
Demo
https://github.com/user-attachments/assets/71d7a126-9c5e-4254-99f4-f2cdedd526ad
Features
One command scores your whole codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first.
pyscn looks at your code from five angles:
- 🧹 Dead code - unreachable code you can safely delete
- 📋 Duplicate code - copy-pasted and structurally similar code worth merging (Type 1-4 clone detection)
- 🌀 Complexity - functions that are hard to read and test (cyclomatic and cognitive complexity)
- 🔥 Module and directory hotspots - per-file quality and per-directory complexity rollups for prioritizing refactors
- 🏗️ Architecture - circular imports, layer rule violations (clean / layered / hexagonal / MVC presets), and auto-detected module communities that reveal how your code is actually structured
- 🧩 Class design - classes that do too much or depend on too much (CBO coupling, LCOM4 cohesion)
100,000+ lines/sec • Built with Go + tree-sitter
AI Agent Integration
pyscn ships Agent Skills that teach AI coding agents when and how to run each analysis: health checks, refactoring, architecture review, and CI-friendly reports.
Agent Skills (Recommended)
uvx add-skills ludo-technologies/pyscn
This installs the Skills into your project. They work with Claude Code, Cursor, Codex, Gemini CLI, and many other agents (add --agent cursor etc. to target one, --global for all projects).
Then just ask your agent:
-
"Analyze the code quality of the app/ directory"
-
"Find duplicate code and help me refactor it"
-
"Show me complex code and help me simplify it"
MCP Server (Optional)
For tighter integration, the bundled pyscn-mcp server exposes the same analyses as MCP tools to Claude Code, Cursor, ChatGPT, and other MCP clients.
Claude Code plugin (sets up the MCP server and the Skills together):
claude plugin marketplace add ludo-technologies/pyscn
claude plugin install pyscn-mcp@pyscn-marketplace
Manual setup for Claude Code:
claude mcp add pyscn-mcp uvx -- pyscn-mcp
Cursor / Claude Desktop: add to your MCP settings (~/.config/claude-desktop/config.json or Cursor settings):
{
"mcpServers": {
"pyscn-mcp": {
"command": "uvx",
"args": ["pyscn-mcp"],
"env": {
"PYSCN_CONFIG": "/path/to/.pyscn.toml"
}
}
}
}
Dive deeper in mcp/README.md for setup walkthroughs and docs/MCP_INTEGRATION.md for architecture details.
Installation
# Install with pipx (recommended)
pipx install pyscn
# Or with uv
uv tool install pyscn
Alternative installation methods
Build from source
git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build
Go install
go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest
Common Commands
pyscn analyze
Run comprehensive analysis with HTML report
pyscn analyze . # All analyses with HTML report
pyscn analyze --json . # Generate JSON report
pyscn analyze --select complexity . # Only complexity analysis
pyscn analyze --select deps . # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses
pyscn analyze --skip-communities . # Skip module community detection
pyscn check
Fast CI-friendly quality gate
pyscn check . # Quick pass/fail check
pyscn check --max-complexity 15 . # Custom thresholds
pyscn check --max-cycles 0 . # Only allow 0 cycle dependency
pyscn check --select deps . # Check only for circular dependencies
pyscn check --select di . # Detect DI anti-patterns (opt-in)
pyscn check --allow-circular-deps . # Allow circular dependencies (warning only)
pyscn init
Create configuration file
pyscn init # Generate .pyscn.toml
💡 Run
pyscn --helporpyscn <command> --helpfor complete options
Configuration
Create a .pyscn.toml file or add [tool.pyscn] to your pyproject.toml:
# .pyscn.toml
[complexity]
max_complexity = 15
[dead_code]
min_severity = "warning"
[output]
directory = "reports"
⚙️ Run
pyscn initto generate a full configuration file with all available options
Pyscn Bot (GitHub App)
Pyscn Bot monitors your Python code quality automatically.
Features
- PR Code Review - Automatic code review on every pull request
- Weekly Code Audit - Scans your entire repository and creates issues for architectural problems
Documentation
📖 pyscn documentation site — installation, rule catalog, CLI reference, configuration, output specification
For contributors: Development Guide • Architecture • Testing
Enterprise Support
For commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org
License
MIT License — see LICENSE
Built with ❤️ using Go and tree-sitter
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyscn-1.29.1-py3-none-win_amd64.whl.
File metadata
- Download URL: pyscn-1.29.1-py3-none-win_amd64.whl
- Upload date:
- Size: 11.4 MB
- Tags: Python 3, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
61c4d3fe6d82988b9776932ccedfbe4f6c9150eea274666eb01776b3f29b1450
|
|
| MD5 |
f62faef9dd4253963b55bfb5b4d332f1
|
|
| BLAKE2b-256 |
79bc1ae38573b5503613453c5b2db8d907060720489ed52cdc7d1b20a62e6efb
|
File details
Details for the file pyscn-1.29.1-py3-none-manylinux_2_17_x86_64.whl.
File metadata
- Download URL: pyscn-1.29.1-py3-none-manylinux_2_17_x86_64.whl
- Upload date:
- Size: 10.9 MB
- Tags: Python 3, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
adeff99afd3a1df1ae711463712c1122fc66e494f80c53c8d8f1826a14126ce1
|
|
| MD5 |
115cba6b66cddd0327cc6ef6f981570c
|
|
| BLAKE2b-256 |
e2e6b311086e861ec5f4d7b4fe2a112cc1a41039506c7453dca47bd0a0815cd3
|
File details
Details for the file pyscn-1.29.1-py3-none-macosx_11_0_arm64.whl.
File metadata
- Download URL: pyscn-1.29.1-py3-none-macosx_11_0_arm64.whl
- Upload date:
- Size: 10.0 MB
- Tags: Python 3, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eefcbc1388a3a573c20f404241df2ea4d38c4f3fa8ea59034039d90d8a49e02d
|
|
| MD5 |
861b21eaf68c71f679fa1fc593dd3461
|
|
| BLAKE2b-256 |
a0c4bba2b75c3ce677b96cbc34ac82acfc3fc61e402ab8e2fb6e44cec4af298f
|
