python-sdk/docs/tools/refactor.md

hanzo-tools-refactor

Advanced refactoring with LSP/AST support. FAST parallel processing for large codebases.

Installation

pip install hanzo-tools-refactor

Or as part of the full toolkit:

pip install hanzo-mcp[tools-all]

Overview

hanzo-tools-refactor provides intelligent code refactoring:

• rename - Rename symbol across entire codebase
• rename_batch - Batch rename multiple symbols
• extract_function - Extract code into a new function
• extract_variable - Extract expression into a variable
• inline - Inline a function or variable
• move - Move symbol to another file
• change_signature - Modify function parameters
• find_references - Find all references to a symbol
• organize_imports - Clean up and sort imports

Quick Start

# Rename a symbol
refactor(action="rename", file="main.py", line=10, column=5, new_name="newName")

# Batch rename multiple symbols
refactor(
    action="rename_batch",
    renames=[
        {"old": "foo", "new": "bar"},
        {"old": "baz", "new": "qux"}
    ],
    path="./src"
)

# Change function signature
refactor(
    action="change_signature",
    file="utils.py",
    line=15,
    add_parameter={"name": "timeout", "default": "30"}
)

# Find references
refactor(action="find_references", file="models.py", line=25, column=8)

Actions Reference

rename

Rename a symbol at a specific location.

refactor(
    action="rename",
    file="/path/to/file.py",
    line=42,
    column=10,
    new_name="betterName"
)

Parameters:

• file (required): File containing the symbol
• line (required): Line number (1-based)
• column (required): Column number (1-based)
• new_name (required): New name for the symbol

rename_batch

Rename multiple symbols across the codebase in parallel.

refactor(
    action="rename_batch",
    renames=[
        {"old": "getUserData", "new": "fetchUserData"},
        {"old": "setUserData", "new": "updateUserData"},
        {"old": "deleteUserData", "new": "removeUserData"}
    ],
    path="./src",
    parallel=True  # Default: true
)

Parameters:

• renames (required): List of {old, new} pairs
• path: Directory to search (default: current directory)
• parallel: Process in parallel (default: true)

extract_function

Extract selected code into a new function.

refactor(
    action="extract_function",
    file="/path/to/file.py",
    start_line=20,
    end_line=30,
    new_name="processData"
)

Parameters:

• file (required): Source file
• start_line (required): First line of code to extract
• end_line (required): Last line of code to extract
• new_name: Name for the new function

extract_variable

Extract an expression into a variable.

refactor(
    action="extract_variable",
    file="/path/to/file.py",
    line=15,
    start_column=10,
    end_column=45,
    new_name="calculatedValue"
)

Parameters:

• file (required): Source file
• line (required): Line containing the expression
• start_column: Start of expression
• end_column: End of expression
• new_name: Variable name

inline

Inline a function or variable at its call sites.

refactor(
    action="inline",
    file="/path/to/file.py",
    line=10,
    column=5
)

Parameters:

• file (required): Source file
• line (required): Line of the symbol
• column (required): Column of the symbol

move

Move a symbol to a different file.

refactor(
    action="move",
    file="/path/to/source.py",
    line=15,
    column=6,
    target_file="/path/to/destination.py"
)

Parameters:

• file (required): Source file
• line (required): Line of the symbol
• column (required): Column of the symbol
• target_file (required): Destination file

change_signature

Modify a function's parameters.

# Add a parameter
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    add_parameter={"name": "timeout", "default": "30", "type": "int"}
)

# Remove a parameter
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    remove_parameter="deprecated_param"
)

# Reorder parameters
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    reorder_parameters=["user_id", "data", "options"]
)

find_references

Find all references to a symbol.

refactor(action="find_references", file="models.py", line=10, column=6)

Response:

{
  "symbol": "UserModel",
  "references": [
    {"file": "views.py", "line": 15, "column": 8},
    {"file": "tests/test_models.py", "line": 22, "column": 12}
  ],
  "count": 2
}

organize_imports

Clean up and sort imports in a file.

refactor(action="organize_imports", file="main.py")

Parallel Processing

The refactor tool uses parallel processing for large-scale operations:

# Parallel is enabled by default
refactor(
    action="rename_batch",
    renames=[...],  # Many renames
    path="./large_codebase",
    parallel=True   # Uses all CPU cores
)

# Disable for sequential processing
refactor(
    action="rename_batch",
    renames=[...],
    parallel=False
)

Preview Mode

Preview changes before applying them:

# Preview only - don't apply changes
refactor(
    action="rename",
    file="main.py",
    line=10,
    column=5,
    new_name="newName",
    preview=True
)

Response:

{
  "preview": true,
  "changes": [
    {"file": "main.py", "line": 10, "old": "oldName", "new": "newName"},
    {"file": "utils.py", "line": 25, "old": "oldName", "new": "newName"}
  ],
  "files_affected": 2
}

Examples

Safe Symbol Rename

# 1. Find all usages first
refs = refactor(action="find_references", file="models.py", line=10, column=5)

# 2. Preview the rename
preview = refactor(
    action="rename",
    file="models.py",
    line=10,
    column=5,
    new_name="BetterName",
    preview=True
)

# 3. Apply the rename
refactor(
    action="rename",
    file="models.py",
    line=10,
    column=5,
    new_name="BetterName"
)

Large-Scale Refactoring

# Rename multiple patterns across codebase
refactor(
    action="rename_batch",
    renames=[
        {"old": "v1_api", "new": "legacy_api"},
        {"old": "v2_api", "new": "current_api"},
        {"old": "v3_api", "new": "api"}
    ],
    path="./src",
    parallel=True
)

Extract Common Code

# Extract duplicated logic into a function
refactor(
    action="extract_function",
    file="handlers.py",
    start_line=45,
    end_line=60,
    new_name="validate_and_process"
)

Best Practices

1. Always preview first - Use preview=True for important refactors
2. Run tests after - Verify refactoring didn't break functionality
3. Use batch operations - rename_batch is faster than individual renames
4. Commit before refactoring - Have a clean git state to easily revert
5. Combine with LSP - Use lsp tool for initial symbol discovery