Code Refactoring with Autohand

Why automated refactoring matters

Manual refactoring is error-prone. A missed reference during a rename breaks builds. An extracted function with incorrect scope leaks variables. These mistakes compound in large codebases where changes ripple across hundreds of files.

Autohand's refactoring tools analyze your code's structure to make changes consistently across your entire workspace. Each tool performs word-boundary-aware matching, respects scope rules, and previews changes before applying them.

This guide covers:

Finding symbol definitions and references
Renaming symbols safely across files
Extracting functions and variables
Organizing imports
Building refactoring workflows into your development process

Finding references and definitions

Before refactoring, you need to understand how a symbol is used. The find_references and find_definition tools map the relationships between symbols in your codebase.

Finding all references

Locate every usage of a symbol across your workspace:

# Find all references to a function
autohand "find all references to processOrder"

# The tool will output:
# Found 23 references to "processOrder"
#    src/orders/handler.ts:45:12 - export function processOrder(
#    src/orders/handler.ts:89:5 - return processOrder(validated);
#    src/checkout/flow.ts:112:8 - await processOrder(cart);
#    src/api/routes.ts:67:15 - handler: processOrder,
#    ...

You can limit the search to specific directories or file types:

# Search only in the api directory
autohand "find references to UserService in src/api"

# Search only TypeScript files
autohand "find references to Config, only in .ts files"

Finding definitions

Jump to where a symbol is declared:

# Find the definition of a class
autohand "find definition of PaymentGateway"

# Output:
# Definition of "PaymentGateway":
#    src/payments/gateway.ts:12
#    export class PaymentGateway implements IPaymentProcessor {

When multiple candidates exist (like overloaded functions or interface implementations), the tool lists all possibilities ranked by likelihood.

Renaming symbols

Renaming is the most common refactoring operation. Autohand's rename_symbol tool performs word-boundary-aware renaming, preventing partial matches that would corrupt unrelated code.

Basic renaming

# Rename a function
autohand "rename getUserById to fetchUserById"

# Output:
# Renamed "getUserById" to "fetchUserById"
#    Modified 8 files, 23 occurrences

Dry run mode

Preview changes without modifying files:

# Preview the rename
autohand "rename OrderStatus to OrderState with dry run"

# Output:
# Dry run: Would rename "OrderStatus" to "OrderState"
#    Would modify 45 occurrences in 12 files
#    src/orders/types.ts:8
#    src/orders/handler.ts:15, 34, 67
#    src/api/responses.ts:23
#    ...

Scoped renaming

Limit renaming to specific paths when the same name is used in different contexts:

# Rename only in the payments module
autohand "rename validate to validatePayment in src/payments"

# Rename only in TypeScript files
autohand "rename Config to AppConfig, only .ts files"

When renaming requires approval

The rename tool requires explicit approval before modifying files. This prevents accidental changes and gives you a chance to review the scope of the operation.

# In interactive mode, you'll see:
# Allow renaming symbol across files? [y/n]
#
# In CI/CD, use the --yes flag for automation:
autohand --yes "rename legacyHandler to modernHandler"

Extracting functions and variables

Extraction refactorings reduce code duplication and improve readability by pulling logic into named abstractions.

Extract function

Move a code block into a new function:

# Extract lines 45-60 into a new function
autohand "extract lines 45 to 60 of src/orders/handler.ts into a function called validateOrderItems"

# The tool will:
# 1. Create the new function with the extracted code
# 2. Replace the original lines with a function call
# 3. Infer parameters from variables used in the block

You can specify parameters and return types explicitly:

# Extract with explicit signature
autohand "extract lines 100-120 of src/auth/service.ts into validateCredentials with parameters user, password and return type boolean"

Extract variable

Replace a complex expression with a named variable:

# Extract a computed value
autohand "in src/pricing/calculator.ts line 34, extract columns 12-45 into a variable called basePriceWithTax"

# Before:
# const total = (price * quantity) * (1 + taxRate) + shippingCost;
#
# After:
# const basePriceWithTax = (price * quantity) * (1 + taxRate);
# const total = basePriceWithTax + shippingCost;

Organizing imports

Clean imports improve code readability and reduce merge conflicts. The organize_imports tool sorts and groups imports by convention.

# Organize imports in a file
autohand "organize imports in src/index.ts"

# The tool groups imports in this order:
# 1. Node.js built-ins (node:fs, node:path)
# 2. External packages (@company/lib, lodash)
# 3. Relative imports (./utils, ../types)

The result is consistently formatted imports:

// Before:
import { join } from 'path';
import { UserService } from './services/user';
import express from 'express';
import { readFile } from 'fs/promises';
import { Config } from '../config';

// After:
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import express from 'express';
import { Config } from '../config';
import { UserService } from './services/user';

Building refactoring workflows

Integrate refactoring tools into your development process for consistent code quality.

Pre-commit hooks

Run import organization before each commit:

# .husky/pre-commit or similar
#!/bin/sh
for file in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx)$'); do
  autohand --yes "organize imports in $file"
  git add "$file"
done

Batch refactoring

Process multiple files in a single session:

# Rename across the entire codebase
autohand "rename deprecated function createUser to registerUser across all files"

# The agent will:
# 1. Find all occurrences
# 2. Show you the scope of changes
# 3. Apply the rename after confirmation

Safe refactoring checklist

Before large refactoring operations:

Ensure all tests pass on the current state
Commit or stash any uncommitted changes
Use dry-run mode to preview the scope
Run tests after the refactoring completes
Review the diff before committing

# A typical safe refactoring workflow
git stash
autohand "rename OrderProcessor to OrderHandler with dry run"
# Review the output
autohand "rename OrderProcessor to OrderHandler"
npm test
git diff
git add -p
git commit -m "refactor: rename OrderProcessor to OrderHandler"

Language support

Refactoring tools work across multiple languages with language-aware patterns:

Language	Find refs	Rename	Extract	Imports
TypeScript	Full	Full	Full	Full
JavaScript	Full	Full	Full	Full
Python	Full	Full	Full	Partial
Rust	Full	Full	Basic	-
Go	Full	Full	Basic	-

Troubleshooting

Rename found too many matches

If a symbol name is too common, scope the rename to specific paths:

# Too broad
autohand "rename id to identifier"  # Matches everywhere

# Better - scope to a module
autohand "rename id to identifier in src/users"

Extract function parameters incorrect

The extraction tool infers parameters from variable usage. For complex cases, specify parameters explicitly:

# Let the tool infer (may miss some)
autohand "extract lines 10-20 of file.ts into processData"

# Explicit parameters
autohand "extract lines 10-20 of file.ts into processData with parameters input, options"

Definition not found

If the definition search returns no results, try providing a language hint:

# With language hint for better pattern matching
autohand "find definition of handleRequest in typescript files"

Next steps

Maintaining Documentation - Keep docs in sync with code changes
Tools Reference - Complete list of available tools