code-refactor-agent

An autonomous coding agent for refactoring codebases using Claude AI.

Architecture

This project implements an Orchestrator-Implementer pattern—a proven multi-agent architecture for long-running tasks that avoids context window exhaustion and maintains coherence across sessions.

┌─────────────────────────────────────────────────────────────────┐
│                     CODE REFACTOR AGENT                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────┐         ┌─────────────────────────────┐   │
│   │   ORCHESTRATOR  │         │       IMPLEMENTER           │   │
│   │   (First Run)   │         │    (Iterative Sessions)     │   │
│   ├─────────────────┤         ├─────────────────────────────┤   │
│   │ • Analyze code  │         │ • Pick ONE pending task     │   │
│   │ • Create tasks  │ ──────► │ • Implement changes         │   │
│   │ • Set rules     │         │ • Validate & mark done      │   │
│   │ • Init notes    │         │ • Log session progress      │   │
│   └─────────────────┘         └──────────┬──────────────────┘   │
│                                          │                      │
│                                          ▼                      │
│                               ┌──────────────────┐              │
│                               │  All tasks done? │              │
│                               └────────┬─────────┘              │
│                                   No   │   Yes                  │
│                                   │    └────► Complete!         │
│                                   ▼                             │
│                              Next session                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Why Two Agents?

Modern LLM agent research (see Anthropic's context engineering guide and Azure's orchestration patterns) identifies key challenges for long-running tasks:

| Challenge | How This Architecture Solves It | |-----------|--------------------------------| | Context window exhaustion | Implementer starts fresh each session, focused on a single task | | Context rot (degraded performance as tokens accumulate) | Clean context per task prevents quality degradation | | Lost state between sessions | session_notes.txt maintains continuity and decisions | | Unclear progress | tasks.json provides explicit tracking with status | | Inconsistent validation | Rules defined upfront by orchestrator, applied consistently |

The Orchestrator Agent

Runs once at project initialization to:

• Analyze codebase structure, tech stack, and patterns
• Decompose the refactoring goal into discrete, focused tasks
• Create project-specific validation rules (lint, build, test commands)
• Initialize session notes with architectural context

The Implementer Agent

Runs iteratively until all tasks complete:

• Single-task focus: Picks exactly ONE pending task per session
• Full lifecycle: Implement → Validate → Update status → Log progress
• Context isolation: Each session starts with minimal context (notes + current task)
• Automatic continuation: Sessions chain automatically with progress tracking

Progress Tracking & Session Logs

All state persists in the .coderefactoragent/ directory:

.coderefactoragent/
├── refactor_goal.txt     # Your refactoring objective (user-created)
├── tasks.json            # Task list with status tracking
├── session_notes.txt     # Cumulative log of all sessions
└── validation_rules.md   # Project-specific validation commands

tasks.json - Structured task tracking:

[
  { "id": 1, "description": "Convert var to const in utils/", "status": "done" },
  { "id": 2, "description": "Update imports in components/", "status": "pending" }
]

session_notes.txt - Session-by-session progress log:

Session 3 completed Task #2
Changes: Updated 15 import statements in src/components/
Validation: npm run lint ✓, npm run build ✓
Next: Task #3 - Update test files

Progress displayed after each session:

Progress: 5/12 tasks completed (41.7%)

Installation

npm install -g code-refactor-agent

Prerequisites

Option 1: Claude Code (Recommended)

If you have a Claude subscription and are logged into Claude Code installed locally, no API key is needed. The agent will authenticate automatically.

Option 2: API Key

Set your Anthropic API key as an environment variable:

export ANTHROPIC_API_KEY=your_api_key_here

Or create a .env file in your project root:

ANTHROPIC_API_KEY=your_api_key_here

Usage

1. Create a .coderefactoragent directory in your project root:

mkdir -p .coderefactoragent

2. Create a refactor_goal.txt file with your refactoring goal:

echo 'Convert all var declarations to const/let' > .coderefactoragent/refactor_goal.txt

3. Run the agent:

code-refactor-agent

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -d, --project-dir <path> | Project directory to refactor | Current directory | | -i, --max-iterations <number> | Maximum number of iterations | Unlimited | | -m, --model <name> | Claude model to use | claude-haiku-4-5 |

Examples

# Run in current directory
code-refactor-agent

# Run on a specific project
code-refactor-agent -d /path/to/project

# Limit iterations and use a different model
code-refactor-agent -i 10 -m claude-sonnet-4-5

Development

Setup

git clone <repository-url>
cd code-refactor-agent
npm install

Build

npm run build

Run in Development

npm run dev

Local Testing

Link the package globally for local testing:

npm run build
npm run link

Now you can use code-refactor-agent anywhere on your system.

To unlink:

npm run unlink

License

ISC