{
  "markdown": "<div align=\"center\">\n\n[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [Français](README.fr.md)\n\n<br>\n\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo.svg\">\n  <source media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo-light.svg\">\n  <img alt=\"pyscn\" src=\"assets/logo-light.svg\" width=\"320\">\n</picture>\n\n**Code quality analysis for Python in the age of AI coding.**\n\nBuilding with Cursor, Claude, or ChatGPT? pyscn keeps AI-generated code maintainable with structural analysis.\n\n[![Article](https://img.shields.io/badge/dev.to-Article-0A0A0A?style=flat-square&logo=dev.to)](https://dev.to/daisukeyoda/pyscn-the-code-quality-analyzer-for-vibe-coders-18hk)\n[![PyPI](https://img.shields.io/pypi/v/pyscn?style=flat-square&logo=pypi)](https://pypi.org/project/pyscn/)\n[![Downloads](https://img.shields.io/pypi/dm/pyscn?style=flat-square&logo=pypi&label=downloads)](https://pypi.org/project/pyscn/)\n[![Go](https://img.shields.io/github/go-mod/go-version/ludo-technologies/pyscn?style=flat-square&logo=go)](https://go.dev/)\n[![License](https://img.shields.io/github/license/ludo-technologies/pyscn?style=flat-square)](LICENSE)\n\n*Working with other languages? pyscn is part of [polyscan](https://github.com/ludo-technologies/polyscan) — code quality analyzers for JavaScript/TypeScript and more*\n\n</div>\n\n## Quick Start\n\n```bash\n# Run analysis without installation\nuvx pyscn@latest analyze .\n# or\npipx run pyscn analyze .\n```\n\n## Demo\n\n<img alt=\"pyscn analysis report\" src=\"https://raw.githubusercontent.com/ludo-technologies/pyscn/main/assets/demo-report.png\" width=\"720\">\n\n## Features\n\nOne command scores your whole codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first.\n\npyscn looks at your code from five angles:\n\n- 🧹 **Dead code** - unreachable code you can safely delete\n- 📋 **Duplicate code** - copy-pasted and structurally similar code worth merging (Type 1-4 clone detection)\n- 🌀 **Complexity** - functions and executable class suites that are hard to read and test (cyclomatic and cognitive complexity)\n- 🔥 **Module and directory hotspots** - per-file quality and per-directory complexity rollups for prioritizing refactors\n- 🏗️ **Architecture** - circular imports, layer rule violations (clean / layered / hexagonal / MVC presets), and auto-detected module communities that reveal how your code is actually structured\n- 🧩 **Class design** - classes that do too much or depend on too much (CBO coupling, LCOM4 cohesion)\n\n**100,000+ lines/sec** • Built with Go + tree-sitter\n\n## AI Agent Integration\n\npyscn ships Agent Skills that teach AI coding agents when and how to run each analysis: health checks, refactoring, architecture review, and CI-friendly reports.\n\n### Agent Skills (Recommended)\n\n```bash\nuvx add-skills ludo-technologies/pyscn\n```\n\nThis 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).\n\nThen just ask your agent:\n\n1. \"Analyze the code quality of the app/ directory\"\n\n2. \"Find duplicate code and help me refactor it\"\n\n3. \"Show me complex code and help me simplify it\"\n\n### MCP Server (Optional)\n\nFor tighter integration, the bundled `pyscn-mcp` server exposes the same analyses as MCP tools to Claude Code, Cursor, ChatGPT, and other MCP clients.\n\n**Claude Code plugin (sets up the MCP server and the Skills together):**\n\n```bash\nclaude plugin marketplace add ludo-technologies/pyscn\nclaude plugin install pyscn-mcp@pyscn-marketplace\n```\n\n**Manual setup for Claude Code:**\n\n```bash\nclaude mcp add pyscn-mcp uvx -- pyscn-mcp\n```\n\n**Cursor / Claude Desktop:** add to your MCP settings (`~/.config/claude-desktop/config.json` or Cursor settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"pyscn-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"pyscn-mcp\"],\n      \"env\": {\n        \"PYSCN_CONFIG\": \"/path/to/.pyscn.toml\"\n      }\n    }\n  }\n}\n```\n\nDive deeper in `mcp/README.md` for setup walkthroughs and `docs/MCP_INTEGRATION.md` for architecture details.\n\n## Installation\n\n```bash\n# Install with pipx (recommended)\npipx install pyscn\n\n# Or with uv\nuv tool install pyscn\n```\n\n<details>\n<summary>Alternative installation methods</summary>\n\n### Build from source\n```bash\ngit clone https://github.com/ludo-technologies/pyscn.git\ncd pyscn\nmake build\n```\n\n### Go install\n```bash\ngo install github.com/ludo-technologies/pyscn/cmd/pyscn@latest\n```\n\n</details>\n\n## Common Commands\n\n### `pyscn analyze`\nRun comprehensive analysis with HTML report\n```bash\npyscn analyze .                              # All analyses with HTML report\npyscn analyze --json .                       # Generate JSON report\npyscn analyze --select complexity .          # Only complexity analysis\npyscn analyze --select deps .                # Only dependency analysis\npyscn analyze --select complexity,deps,deadcode . # Multiple analyses\npyscn analyze --skip-communities .           # Skip module community detection\n```\n\n### `pyscn check`\nFast CI-friendly quality gate\n```bash\npyscn check .                         # Quick pass/fail check\npyscn check --max-complexity 15 .     # Custom thresholds\npyscn check --max-cycles 0 .          # Only allow 0 cycle dependency\npyscn check --select deps .           # Check only for circular dependencies\npyscn check --select di .             # Detect DI anti-patterns (opt-in)\npyscn check --allow-circular-deps .   # Allow circular dependencies (warning only)\n```\n\n### `pyscn init`\nCreate configuration file\n```bash\npyscn init                         # Generate .pyscn.toml\n```\n\n> 💡 Run `pyscn --help` or `pyscn <command> --help` for complete options\n\n## Configuration\n\nCreate a `.pyscn.toml` file or add `[tool.pyscn]` to your `pyproject.toml`:\n\n```toml\n# .pyscn.toml\n[complexity]\nmax_complexity = 15\n\n[dead_code]\nmin_severity = \"warning\"\n\n[output]\ndirectory = \"reports\"\n```\n\n> ⚙️ Run `pyscn init` to generate a full configuration file with all available options\n\n## Don't want to run the CLI every week?\n\n[Install Polyscan on GitHub](https://codescan.dev/pyscn-bot) — it files a weekly health score as a GitHub Issue. Free for every repository.\n\n---\n\n## Documentation\n\n📖 **[pyscn documentation site](https://docs.codescan.dev/)** — installation, rule catalog, CLI reference, configuration, output specification\n\nFor contributors: **[Development Guide](docs/DEVELOPMENT.md)** • **[Architecture](docs/ARCHITECTURE.md)** • **[Testing](docs/TESTING.md)**\n\n## Enterprise Support\n\nFor commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n*Built with ❤️ using Go and tree-sitter*\n",
  "bytes": 6782,
  "sha": "730550311b2d027cda121bcd2e9eabf907a8c74c805fc975e48ab726a1166148",
  "repo_slug": "ludo-technologies/pyscn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ludo_technologies_pyscn_e5a98ddf/readme"
}