RefactorX

Automated refactoring suggestions for Python code. Detect code smells, long functions, unused imports, deep nesting, duplicate blocks, and complex conditionals — all powered by Python's built-in ast module.

---

Architecture

flowchart LR
    A[Python Source Files] --> B[ast.parse]
    B --> C[RefactorEngine]
    C --> D1[Long Functions]
    C --> D2[Deep Nesting]
    C --> D3[Unused Imports]
    C --> D4[Complex Conditionals]
    C --> D5[Duplicate Blocks]
    D1 & D2 & D3 & D4 & D5 --> E[List of Suggestions]
    E --> F{Output}
    F -->|Rich Table| G[Terminal]
    F -->|JSON| H[CI / Tooling]

Loading

Features

Detector	What it finds	Default threshold
Long function	Functions exceeding N lines	50 lines
Deep nesting	Control-flow nested too deep	4 levels
Unused imports	Imported names never referenced	—
Complex conditional	Boolean expressions with too many operands	3 operands
Duplicate block	Repeated AST-identical code blocks	3 lines min

Every suggestion includes severity, description, line number, and a suggested fix.

Quickstart

# Clone and install
git clone https://github.com/MukundaKatta/RefactorX.git
cd RefactorX
pip install -e ".[dev]"

# Analyse a file
refactorx path/to/your_code.py

# Analyse a directory
refactorx src/

# JSON output (great for CI)
refactorx src/ --json

CLI Options

refactorx [OPTIONS] PATH

Options:
  -f, --max-func-len   Max lines per function      [default: 50]
  -n, --max-nesting    Max nesting depth            [default: 4]
  -b, --max-bool       Max boolean operands         [default: 3]
  -d, --min-dup        Min lines for duplicate det. [default: 3]
  -j, --json           Output as JSON

Using as a Library

from refactorx import RefactorEngine, RefactorConfig

config = RefactorConfig(max_function_length=30)
engine = RefactorEngine(config)

source = open("my_module.py").read()
for suggestion in engine.analyse(source, filename="my_module.py"):
    print(f"[{suggestion.severity.value}] line {suggestion.line}: {suggestion.description}")

Development

make install   # Install in editable mode with dev deps
make test      # Run pytest
make lint      # Run ruff
make run       # Analyse the src/ directory

Inspired by AI Coding Agents

RefactorX is inspired by the growing trend of AI coding agents — tools like OpenClaw, Cursor, and AI code assistants that help developers write better code faster. While those tools use LLMs, RefactorX takes a complementary approach: deterministic, AST-based analysis that runs instantly, offline, and with zero API costs. Use it alongside your favourite AI assistant for the best of both worlds.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — Copyright 2026 Officethree Technologies

---

Built by Officethree Technologies | Made with ❤️ and AI