pyscn 1.5.0

An intelligent Python code quality analyzer with architectural guidance

pyscn - Python Code Quality Analyzer

pyscn is 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 analyze .
# or
pipx run pyscn analyze .

Demo

https://github.com/user-attachments/assets/07f48070-c0dd-437b-9621-cb3963f863ff

Features

• 🔍 CFG-based dead code detection – Find unreachable code after exhaustive if-elif-else chains
• 📋 Clone detection with APTED + LSH – Identify refactoring opportunities with tree edit distance
• 🔗 Coupling metrics (CBO) – Track architecture quality and module dependencies
• 📊 Cyclomatic complexity analysis – Spot functions that need breaking down

100,000+ lines/sec • Built with Go + tree-sitter

MCP Integration

Run pyscn analyses straight from AI coding assistants via the Model Context Protocol (MCP). The bundled pyscn-mcp server exposes the same tools used in the CLI to Claude Code, Cursor, ChatGPT, and other MCP clients.

MCP Use Cases

You can interact with pyscn with your AI coding tools:

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"

Claude Code Setup

claude mcp add pyscn-mcp uvx -- pyscn-mcp

Cursor / Claude Desktop Setup

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"
      }
    }
  }
}

The instructions like "Analyze the code quality" trigger pyscn via MCP.

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

CI/CD Integration

# GitHub Actions
- uses: actions/checkout@v4
- run: pipx run pyscn check .    # Fail on quality issues

# Pre-commit hook
- repo: local
  hooks:
    - id: pyscn
      name: pyscn check
      entry: pipx run pyscn check .
      language: system
      pass_filenames: false
      types: [python]

---

Documentation

📚 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