pyscn 1.26.1

An intelligent Python code quality analyzer with architectural guidance

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 JavaScript/TypeScript? Check out jscan

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)
• 🏗️ 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:

1. "Analyze the code quality of the app/ directory"

2. "Find duplicate code and help me refactor it"

3. "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 --help or pyscn <command> --help for 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 init to 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 [e-mail]

License

MIT License — see LICENSE

---

Built with ❤️ using Go and tree-sitter