pyscn
Python code analysis for AI agents: complexity, dead code, clones, coupling, and a health score.
Open source Open in the app JSON README (API)
About
Python code analysis for AI agents: complexity, dead code, clones, coupling, and a health score.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- ludo-technologies
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.30.2
- Stars
- 1,042
- Forks
- 70
- Open pull requests
- 5
- Last push
- 2026-09-04T12:11:24Z
- Repository state
- ativo
- Language
- Go
- License
- MIT
- Added
- 2026-08-29 04:00:26
- Updated
- 2026-09-06 16:00:54
- Origin id
io.github.ludo-technologies/pyscn
README
<div align="center">
[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [Français](README.fr.md)
<br>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg">
<source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
<img alt="pyscn" src="assets/logo-light.svg" width="320">
</picture>
**Code quality analysis for Python in the age of AI coding.**
Building with Cursor, Claude, or ChatGPT? pyscn keeps AI-generated code maintainable with structural analysis.
[](https://dev.to/daisukeyoda/pyscn-the-code-quality-analyzer-for-vibe-coders-18hk)
[](https://pypi.org/project/pyscn/)
[](https://pypi.org/project/pyscn/)
[](https://go.dev/)
[](LICENSE)
*Working with other languages? pyscn is part of [polyscan](https://github.com/ludo-technologies/polyscan) — code quality analyzers for JavaScript/TypeScript and more*
</div>
## Quick Start
```bash
# Run analysis without installation
uvx pyscn@latest analyze .
# or
pipx run pyscn analyze .
```
## Demo
<img alt="pyscn analysis report" src="https://raw.githubusercontent.com/ludo-technologies/pyscn/main/assets/demo-report.png" width="720">
## 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 and executable class suites 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)
```bash
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](https://github.com/ludo-technologies/add-skills) (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):**
```bash
claude plugin marketplace add ludo-technologies/pyscn
claude plugin install pyscn-mcp@pyscn-marketplace
```
**Manual setup for Claude Code:**
```bash
claude mcp add pyscn-mcp uvx -- pyscn-mcp
```
**Cursor / Claude Desktop:** add to your MCP settings (`~/.config/claude-desktop/config.json` or Cursor settings):
```json
{
"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
```bash
# Install with pipx (recommended)
pipx install pyscn
# Or with uv
uv tool install pyscn
```
<details>
<summary>Alternative installation methods</summary>
### Build from source
```bash
git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build
```
### Go install
```bash
go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest
```
</details>
## Common Commands
### `pyscn analyze`
Run comprehensive analysis with HTML report
```bash
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
```bash
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
```bash
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`:
```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
## Don't want to run the CLI every week?
[Install Polyscan on GitHub](https://codescan.dev/pyscn-bot) — it files a weekly health score as a GitHub Issue. Free for every repository.
---
## Documentation
📖 **[pyscn documentation site](https://docs.codescan.dev/)** — installation, rule catalog, CLI reference, configuration, output specification
For contributors: **[Development Guide](docs/DEVELOPMENT.md)** • **[Architecture](docs/ARCHITECTURE.md)** • **[Testing](docs/TESTING.md)**
## Enterprise Support
For commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org
## License
MIT License — see [LICENSE](LICENSE)
---
*Built with ❤️ using Go and tree-sitter*