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 │
│ │
└─────────────────────────────────────────────────────────────────┘
`

$3

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 |

$3

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

$3

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:
`json
[
{ "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

`bash
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:

`bash
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:

`bash
mkdir -p .coderefactoragent
`

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

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

3. Run the agent:

`bash
code-refactor-agent
`

$3

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

$3

`bash


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

$3

`bash
git clone
cd code-refactor-agent
npm install
`

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

$3

Link the package globally for local testing:

`bash
npm run build
npm run link
`

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

To unlink:

`bash
npm run unlink
``

License

ISC